Java library design elements
Table of contents
How to work with Java libraries in Domino
Java can be included in the Domino Database as a shared code library. The Script Libraries window in Domino Designer has a specific action button to create a shared Java library. When the library is created, Domino pre-fills nothing except the actual class statement, as you can see in the following figure. You must to change the name of the class and save it before you can use the class.
Creating a new class
You can include multiple classes in a library. To include a new class, use the New Class action in the Domino Designer pane while editing the library. Each new class appears in the designer pane as a new Java file. In order to reference the script library, we recommend that you include a package name. The package name is placed at the beginning of the Java file, which is standard convention.
Saving your project automatically compiles the code. Alternately, you can explicitly use the Compile... function to compile all or individual files.
When you use the Export function to export your library files, only the .java source files are written to your file system. You can then include and use them in another Java IDE project. Keep in mind that if you compile such files in another development environment, you must ensure that the other development environment has notes.jar available for inclusion.
Calling your library
In order to call your Java library from an agent, you must perform the following actions:
- While editing the agent, use the Edit Project button at the bottom of the design window, and include the library as part of your project.
- Any agent that references your library simply includes it via an import statement.
The following figure shows a sample of the edit project window.
There are two options to browse the available Java files. The first option is to reference your shared Java library. The second option is to reference an external JAR, class, or Java file. After you make your selection, click the appropriate Add/Replace
button to include them in your project. Then click OK
It is best practice to put all your Java classes in a Java package. This simply requires that you put a correct package declaration at the top of your class file and put the file in the correct place.
The package declaration looks like this.
This might be appropriate for code written by the a company 'Foo' with a project 'Bar.' The corresponding directory structure for this package is therefore this.
You put your actual Java file in the bar directory.
To import Java / class files with package declarations into a Domino Java library correctly you must first browse to the root of your package directory structure. From there you can navigate to the files you wish to import.
In this example the base of the package structure is c:\java\graph\src, so this is what we select as the base directory. From there we navigate down through com, foo and bar packages to display Java files we want. Select them and click Add/Replace File(s) to import them.
Remember to use the Java classes that have been imported in this package space, other classes that need to use the packaged class must import them, using the import declaration in the class file. This includes any classes in agents as well as other classes in script libraries.
Some tips on using Java with Domino
Always recycle the underlying Domino objects, because Java's garbage collection does not recycle the mapping and underlying Domino C++ objects. To avoid this, explicitly call each Domino object's method when they are no longer referenced.
Do not attach JAR files to agents or script libraries, because the JAR files must be detached, and then loaded and unloaded every time the agent runs. This can result in low or out of memory issues. If you place the files directly on the file system (the notes external jar directory), then they are only loaded once. Your next best option is to import the source code and have everything self contained in the database.