Beginner LotusScript for Notes Domino 7
Intermediate LotusScript for Notes and Domino 7
Advanced LotusScript for Notes Domino 7


Using LS2J to Access Java Classes from LotusScript

Java has been the programming language of choice for the last few years. Many Java APIs (classes) have been released. For example, several of the credit card processors (like VeriSign) provide a Java API to process credit card transactions. There are also classes to enable the consumption of web services (as a client.)

Release 6 added the ability to call Java classes from LotusScript using the LS2J LotusScript Extension. This extended the world of Java to LotusScript.

Technique - Using LS2J to Access Java Classes from LotusScript

There are four main steps to access a Java class from LotusScript. Click the section headings below for details on each step.

Step 1: Provide Access to the Java Class from Notes/Domino

Step 2: Load the LS2J LotusScript Extension

Step 3: Connect to the Java Library

Step 4: Call the Java Class Methods from LotusScript Code

Demonstration Using LS2J to Access Java Classes from LotusScript This demonstration shows how a button which is coded with LotusScript can invoke a method in a Java library. This demonstration has a Java class which gets the stock price for a stock. Note that this Java class has hardcoded stock values for three stocks, IBM, MSFT, and JNJ. This class simulates Java code that could be written to use web services to actually obtain a stock quote. For more information on writing Java web services go to the following article on DeveloperWorks at IBM's website: http://www-128.ibm.com/developerworks/lotus/library/domino-webservices/ Detach the database below to your Notes data directory by clicking on the database icon: Open the LS2J Demonstration database. Create a new document with the Demo 1.8 Calling Java from LotusScript form. Follow the demonstration steps continued on the form. Continue to the Technique section below.

Technique Technique Here is a description of the code for the [Get Stock Price] button in the demonstration. These three lines of code are from the (Options) event for the button. The LS2J LotusScript Extensions are loaded in Line 2. In Line 3, the StockQuote799 Java library is accessed. 1. Option Declare 2. Uselsx "*javacon" 3. Use "StockQuote799" The rest of the code is from the Click event for the button. The first set of statements declare and set variables for the current workspace, the front-end document and the back-end document. 1. Sub Click(Source As Button) 2. Dim ws As New NotesUIWorkspace 3. Dim uidoc As NotesUIDocument 4. Set uidoc = ws.CurrentDocument 5. Dim doc As NotesDocument 6. Set doc = uidoc.Document These two statements declare and instantiate a JavaSession object, mySession. 7. Dim mySession As JAVASESSION 8. Set mySession = New JavaSession() A JavaClass object, jclass, is declared and instantiated. The jclass object is set to access fields and methods in the "StockQuote799" Java library. 9. Dim jclass As JAVACLASS 10. Set jclass = mySession.getClass("StockQuote799") A JavaObject object, jobj, is declared in Line 11 and instantiated in Line 12 using the createObject method of the JavaClass class. In this example, a single string-type argument (i.e. doc.Stock(0)) is passed as the second argument in the CreateObject method. The first argument passed to CreateObject indicates the type of data for the argument which is passed. In this example, a single string-type argument is passed so the first argument of CreateObject is "(Ljava/lang/String;)V". Line 13 calls the getQuote() Java method to retrieve the stock price. 11. Dim jobj As  JavaObject 12. Set jobj = jclass.CreateObject("(Ljava/lang/String;)V", doc.stock(0)) 13. doc.price = jobj.getQuote() 14. End Sub

Tip Terminology - Property same as Field The Lotus Domino Designer 7 Help uses the term property and many of the methods and properties of the LS2J classes use property as part of their name. Examples would be the JavaProperty class and the getProperty method in the JavaClass class. Some Java programmers may be more familiar with the term "fields." These are the same as properties. A field is a variable declared in a class. If this variable is public then the field's value can be accessed and set. Field and property can be thought as being the same for the discussions in this lesson and in Lotus Domino Designer 7 Help.

Accessing Java Properties and Methods using getProperty and getMethod

In the example above, a Java method was called by referencing its name using dot notation syntax. The dot notation syntax can also be used to set a Java property.

Syntax Dot Notation Syntax to Access Java Properties and Methods Use this dot notation syntax to call a Java method: javaobject.javamethodname() which will return a value to LotusScript. Use this dot notation syntax to set a Java property: javaobject.javamethodname = (some LotusScript value)

However, there are several situations when the dot notation syntax may not work. Instead, the getProperty and getMethod methods of the JavaClass class must be used to access the property or method. Failure to use this approach may result in ambiguous results or a run-time error.

There are three situations when the dot notation syntax may not work:

1. Java is case sensitive and LotusScript is not. Java allows the use of two methods that differ only by the case of the name. Since LotusScript is not case sensitive, it has no way to differentiate the two different Java methods using the dot notation syntax.
2. A Java method or property name is greater than 40 characters. LotusScript does not allow for more than 40 characters for a method name, Java does.
3. Java allows for more than one method with the same name. LotusScript does not. The way Java differentiates between these methods is by comparing the input parameters (signature). There could be two Java methods called getStockQuote which differ only by the input parameter's data type. One getStockQuote requires a String input parameter and the other an integer value:
   
   getStockQuote(String s)
   getStockQuote(integer i)
   
   The method that gets executed will depend on the data type passed. getStockQuote("IBM") would run the first method and getStockQuote(345) would run the second. This is called overloading in Java and there is no equivalent in the LotusScript language.

Technique - Using the getProperty Method

Use the getProperty method of the JavaClass class to return a specified property in the form of a JavaProperty object.. The getProperty method takes the name of the property to return as an argument. This argument is case sensitive and can be greater that 40 characters.

From Lotus Domino Designer 7 Help getProperty method This method returns a property. Defined in JavaClass Syntax Set Javaproperty = javaclass.getProperty(PropertyName) Parameter Propertyname - String. Case sensitive. Name of the property you want a handle of. Usage This method returns the property matching Propertyname.

The getProperty method returns the specified property in the form of a JavaProperty object. To get and set the property values, use the getValue and setValue methods of the JavaProperty class.

From Lotus Domino Designer 7 Help: getValue Method

setValue Method

Technique - Using the getMethod Method

Use the getMethod method of the JavaClass class to return a specified method in the form of a JavaMethod object. The getMethod method takes two arguments. The first argument is the name of the property to return, is case sensitive and can be greater that 40 characters. The second argument indicates the signature of the method to return.

From Lotus Domino Designer 7 Help getMethod method This method returns a method from a JavaClass object. Defined in JavaClass Syntax Set Javamethod = javaclass.GetMethod(Methodname, Signature) Parameters Methodname - String. Case sensitive. Name of the method you want a handle of. Signature - String. JNI Signature representing the method needed. JNI Signature Description B byte C char D double F float I int J long S short V void Z Boolean L<fully-qualified-class> fully-qualified class [<sigtype> Array of <sigtype> Usage This method returns the method matching the name given with the specified signature. Error thrown NoSuchMethodException if the Java method does not exist with the signature given.

The getMethod method returns the specified method in the form of a JavaMethod object. To invoke the method, use the Invoke method of the JavaMethod class.

From Lotus Domino Designer 7 Help Invoke method This method executes a method. Defined in JavaMethod Syntax Set Variant = javamethod.Invoke([JavaObject [,Argument1...[, Argument12]]) Parameters JavaObject - JavaObject. The instance of an object, if the method is not static. Optional if the method is static. Argumentn - Variant. Optional. The arguments needed by the method. Maximum of 12 arguments. Return value Variant. Result of the invoked method.