Using existing Java in an XpageAdded by Jo Grant on February 20, 2009 | Version 1
A popular method of adding business logic
to Notes applications is via Java script libraries. (Note: this is a script
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
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
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
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
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
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
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
but we do need to "look under the covers" a little bit to deploy
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
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.
var companyName =
var db = session.getDatabase(DB_SERVER(),
var logic = new com.ibm.demo.leadmanager.logic.CreditRatingLogic();
creditRating = logic.calculateCreditRating(db, companyName);
business logic in a JAR file.
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
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
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