Using existing Java in an Xpage 

A popular method of adding business logic to Notes applications is via Java script libraries. (Note: this is a script library written in Java, not a library written in JavaScript! Although the names are similar, they are very different things.) These can be used by agents written in Java.
From an XPage it is easy to call Service Side JavaScript for business logic. The JavaScript has built in features that enable it to call Java. Unfortunately Server Side JavaScript, as used by XPages, cannot currently call Java routines created in a Java library. However it can call into a Java library that has been exported as a JAR file. As it turns out you can also create a Java library that also calls into a Java JAR file.
The approach this article recommends, then, is to consolidate your Java based business logic into an Eclipse based Java project. To export from this project a JAR file containing that business logic. Then to use that JAR file in both your Java script library and your XPage application. This way you have a single source base to maintain and can use the same logic for both your Notes rich client applications and your XPage applications.

Migrating to code to an Eclipse Project
To extract your code from your Java script library, open it in Domino Designer. At the bottom of the editor is an Export button. Click this and pick a temporary directory to export your files to.



The next step is to create a Java Eclipse project. The Eclipse IDE used for Domino Designer has full support for creating Java project. This is done via the Java perspective. To switch perspective in Domino Designer, choose Window -> Open Perspective -> Other. From the list choose Java and click OK.
An Eclipse Java project is stored as a directory in your workspace which is usually on your local disk. It is not associated with any Notes database. If you want centralized storage of the code it is recommended that you use one of the source control packages available for Eclipse.
To create an Eclipse Java project choose File -> New -> Project, and select the Java twistie, and then the Java project node. Click Next. On the first panel of the wizard enter in a meaningful project name. We recommend selecting under Project Layout "Create separate folders for source and class files". This will make it easier to manage the JAR file creation within the project.



After clicking Next you move on to the Java Settings page of the wizard. Since we use the Notes Java classes in our library we need to declare that in our project so that when it compiles it knows to use them. Select the Libraries tab. Then click on the Add External JARs button. Use the file dialog to navigate to the NCSO.jar file in your \domino\java directory. Click Open to add it to your project.



You can now click Finish to create the project.

For the next step we import the files from the temporary directory we exported them to above. Open up the twistie for the Java project in the Package Explorer. Right click the "src" directory and choose "Import". In the Import dialog open up the "General" twistie and select "File System". Click on Next.
The next page of the wizard lets you pick which files. Use the Browse button to select the directory you exported to, and select the files from the UI.



Click Finish and Your code should now import into your project. Eclipse automatically compiles your code each time you make a change so you should not need to tell it to compile. If there are any external dependencies that were not declared, the errors should show up now. If you do not see any red marks, then it all has built fine!
Java classes frequently reside in Java packages. This is a convenience to help organize code and to resolve naming conflicts. However, because Java script libraries in Domino are often used in very narrow contexts, it is usually not necessary to keep distinct namespaces. So packages are not commonly used. It is not a requirement to move your code into Java packages to be used from Server Side JavaScript, but unless you have very unique class names, it is recommended.
To create a package in your Eclipse Java project, you can right click on the "src" twistie and select New -> Package. The package name can be anything but the usual convention is to follow the reverse of the domain name for your company, plus an identifier for your project. For example, since IBM's web page is "ibm.com" we might choose "com.ibm.leadmanager" for our package name. You can then move your source code form the default package into the package (or packages) you have created by dragging the file in the Package Explorer or by right clicking it and choosing Refactor -> Move.

Exporting a JAR File from your Eclipse Project
We can do any additional amount of development we want on the source code at this point. We may want to repeat the process and import in several Java script libraries, or add additional features. When we're ready, the next step is to output the project as a JAR file.
There are several ways to manage this, but this article recommends that the files to do it are maintained within the project in a "dist" directory. To create this, right click on the top level twistie for the project and choose New -> Folder. Enter a folder name of "dist" and click "Finish".
Right click again on the top level twistie for the project and this time choose Export. From the Export dialog box choose the Java twistie, then JAR file. Click Next.
In the JAR File Specification page of the wizard, make sure your project is checked off in the list of projects. Expand it's twistie and check off only the "src" directory. Ensure "Export generated class files and resources" is checked, and, unless space or confidentiality is a consideration, also check "Export Java source files and resources. (It is not essential to include the source, but it can help diagnose problems later if you package the source files into your JAR file.) For the export destination, we suggest specifying your project, the dist directory, and using your project name for the name of the jar file. You can choose any place and name you wish, but this keeps everything under the one project and makes it easy to identify later where the jar file came from.



Clicking Next brings you to the JAR Packaging Options. We recommend that you check on "Save the description of the JAR file in the workspace." Again, we recommend that you save it into the dist directory of your project and that you name it the same as your JAR file. By saving the JAR description, in the future you can just right click it and select "Create Jar" to repackage your JAR file. You don't need to go through all these steps again.



You can click Finish at this point and it will export the jar file. You will see it appear in the Package Explorer in the "dist" folder.

Using a JAR file from an XPage
XPages applications are implemented under the covers as a J2EE application. It's structure will be familiar to those who have dealt with J2EE applications before. It's not necessarily to understand J2EE layout to use a JAR file from Server Side JavaScript, but we do need to "look under the covers" a little bit to deploy it.
While in the Java perspective in Domino Designer, you open up the database with your XPages application in it. This is similar to the Domino Designer perspective, but a much lower level file is exposed in the Package Explorer.
Navigate to the WebContent twistie and under that to the WEB-INF twistie. If you do not see a "lib" folder there, create it by right clicking on WEB-INF and selecting New -> Folder. Enter a folder name of "lib" and click "Finish". JAR files placed in this directory are stored in your NSF and automatically appended to the run time class pass of JavaScript.
You can place a copy of your JAR file (in the dist directory created above) here by right clicking the jar file and selecting Copy. Then right click the lib folder and select Paste. It should now appear here under the package explorer.

To use this, you need to go back to the Domino Designer perspective. Select Window -> Open Perspective -> Other. Choose Domino Designer from the list and click OK.
Navigate to the XPage element you want to make the business logic call from. As an example we will follow the same use case above, and add it to the Creating Rating label in the Company Summary custom control.
The following code was used to compute the value of the label.


JavaScript code to call business logic in a JAR file.

(1)	var companyName = CompanyForm.getItemValueString("ContractorName");
(2)	var db = session.getDatabase(DB_SERVER(), DB_CORE_PATH());
(3)	var logic = new com.ibm.demo.leadmanager.logic.CreditRatingLogic();
(4)	var creditRating = logic.calculateCreditRating(db, companyName);
(5)	return "$" + creditRating;

As in the above example, we extract the value of the company name from the current data form (1) and resolve the database from our internal libraries (2). On line (3) we create an object declared by the JAR file we added. You need to use the full package name here when creating an instance of it.
On line (4) we then make the call into the business logic and return the result for use by the label (5).

Using a JAR file from a Java script library
This step is optional. But it makes sense in a lot of circumstances to go back and change your Java script library to use the JAR file from the Eclipse project. This way there is only one copy of your source code to maintain. If you need to do an update to the source code, you only change the code in the Eclipse project, then export it and use it in your XPage and NSF script libraries.
However for some applications you may not want to perturb the existing setup and will want to keep the source code in the Java script library. You can do so, but then whenever you make a code change you need to do a two step process. First export the new code from the Java script library and import it into your Eclipse project. Then export the JAR file from your Eclipse project to use in your XPage project. This is just following through several of the steps above. To upgrade your Java script library to use the JAR file created above, perform the following steps.
First open up your Java script library and click on the Edit Project button. Select all the java files from the right hand pane and click "Delete". (Don't worry, these are safely in your Eclipse project!) In the left hand pane select "Local File System" from the Browse drop down. Navigate to the project's "dist" directory. (This should be in \workspace\\dist". Check the "Archive" checkbox. Your JAR file should now appear. You can select it and click "Add/Replace Files(s)". This will add it to your library. Click OK to save and close the dialog.





Your Java script library has now been upgraded to use the new JAR file. No change is required to any agent or code using this Java script library. The only difference is that instead of using class files generated by compiling code in the script library, it is now using the same class files as contained in the Java archive.

For other techniques for reusing business logic from XPages please see this article here.