In the last article, we told you how you could use the Eclipse integrated development environment (IDE) to develop Java agents and programs with Lotus Notes/Domino. Now, we want to turn our attention to how you can use Eclipse to access the Notes/Domino back-end Java classes. With this method, it is possible to interact with the Notes/Domino backend and to display information through the Eclipse Standard Widget Toolkit (SWT) model.
The IBM Workplace Client Technology rich client edition is also based on the Eclipse SWT framework, so any plug-ins that you develop to work within the native Eclipse environment will also work from the IBM Workplace Client Technology. As a result, any skills you gain in developing plug-ins with Lotus Notes/Domino puts you in a very good position when it comes time to use the IBM Workplace Client Technology with your existing databases.
This article is intended for experienced Notes/Domino application developers with knowledge of Java. Some experience with Eclipse is helpful, but not required.
We suggest that you first read the earlier article on this subject, "Using Lotus Notes with Eclipse to manage and run your Java programs"; however, it is not necessary to follow it through to the conclusion. For the sake of brevity, we assume that you have already installed Eclipse 3. In older versions of Eclipse, you may have needed to also install the plug-in development environment (PDE) and the samples, but in recent versions of the software, this is not necessary. See the Eclipse.org Web site download page, if you do not already have Eclipse installed. In this article, we use Eclipse 3 because it has the ability to include a manifest file in the project, which simplifies the process and allows more advanced control of the classpath for a plug-in. We discuss the manifest file later in this article.
We will not go into too much detail on the many and wide variety of Standard Widget Toolkit (SWT) widgets (UI objects) or the extension point framework. There are a number of good books and tutorials published on the matter. We will just stick to the examples and show you the minimum amount of Notes/Domino Java you need to get started. From there, we will leave you to explore the rest and to develop some really cool and useful plug-ins. Focusing on a simple sample plug-in and wizard-generated code keeps the Notes/Domino aspect obvious, so you can take it from there.
Start with the plug-in wizard
Eclipse has a lot of wizards to simplify tasks, and it is possible to build your own wizards. Going through a wizard gives you a good understanding of how Eclipse is designed to work, and it is an easy way to get started. For our purposes, we create a new plug-in based on a view example. Eclipse offers a few different types of design elements much like Lotus Notes. There are views for data similar to Notes views. There are also other elements, such as forms that are like Notes forms. For more information about Eclipse design elements, you may want to refer to the book, The Java Developer's Guide to Eclipse by Sherry Shavor, et al.
In Eclipse, choose File - New - Project, then select the Plug-in Project option. (If you do not see this option, then the PDE from Eclipse is not installed.) For our plug-in project, we give it the name NotesView, although you can use any name you prefer.
Figure 1. New Plug-in Project dialog box
Eclipse comes with a number of examples referred to as templates, and it is a good idea to see some of the examples and how they all fit together. In this article, we want to create a view, so we select the "Create a plug-in using one of the templates" option, then select the "Plug-in with a view" template, which serves as the basis of our plug-in.
We suggest that you change the view name and category so that the view will be easy to find when you run the sample later. Click Finish when done to generate the plug-in project and code.
Figure 2. New plug-in project with a sample view dialog box
Testing the view in debug mode
The wizard creates all the code you need to get started. After the wizard is finished, go through the class code it has generated for you. You will see it has created a fair amount to get you started compared to the amount of code you get from Domino Designer when you start an agent. In Notes development, we typically go to the help file and copy and paste the relevant code. We have found with Eclipse that we go through the wizard and then take it from there -- no copying and pasting of code is necessary.
Eclipse has a number of perspectives that you can switch to that help you focus on which activity you are currently performing. For instance, when you are debugging, you switch to the debug perspective (choose Window - Open Perspective - Debug) where you can set/remove break points, watch variables, and step through code. There is a perspective that is targeted towards plug-in development as well as general Java development.
By default, the plug-in perspective is launched. You are presented with an overview page. Click the "Launch a runtime workbench" link to start another Eclipse desktop that includes the new plug-in. Your plug-in should look like this if all went well.
Figure 3. Notes View plug-in
If the workbench does not display properly, choose the Window - Show View - Other menu option. In the dialog box, look for the category that you specified when you created your project to find your view. In our case, it is Notes Category (see figure 2).
Linking to Lotus Notes/Domino
To link the project to Lotus Notes/Domino, you must have Lotus Notes installed. Unlike the previous article in which a specific version of the Notes client was required to enable the java_enable_debug setting in the Notes.ini file, you can use any version of Lotus Notes with this project. We need to link to the Notes.jar library as a required library for runtime. The Notes.jar file is the Java archive file that contains all the Notes/Domino back-end classes; it knows how to interact with Lotus Notes/Domino.
NOTE: You can also use the CORBA API Java archive file to access IIOP-enabled Domino servers. In this article, we focus only on using the local access API method.
Specify Notes.jar as a required runtime library
You need to add Notes.jar as a required library for runtime in your plug-in description. In the window titled Plug-in Development, select the Runtime tab. In the Runtime libraries section, click New. Enter Notes.jar when prompted and click OK to save. After you add the Notes.jar file, the plugin.xml file, which was generated when you created when you created the plug-in project and which describes your plug-in, lists both the Notes View JAR file and the Notes.jar file in the runtime. Click the plugin.xml tab to see the code.
<runtime> <library name="Notes_View.jar"> <export name="*"/> </library> <library name="Notes.jar"> <export name="*"/> </library> </runtime>
Plug-in manifest file
In Eclipse 3, you have the ability to create a manifest file (Manifest.MF), which you need to run your plug-in. The manifest file is new in Eclipse 3. It provides extra information about the requirements for the plug-in and ensures that the classpath includes the Notes.jar file when we declare it. This is similar to setting the class path for your plug-in. Without it, you get errors that the plug-in cannot load. When we did this the first time, we had to dive into Eclipse code to find that the error came about when the first Notes class was referenced. This meant that the Notes.jar file was not being loaded by the Eclipse JVM and that the classes were not available. By declaring them in the manifest file, they are loaded correctly.
To create a manifest file (Manifest.MF), select the Runtime tab, then click the "Create a manifest file" link. The manifest file contains the following code:
Manifest-Version: 1.0 Bundle-Name: Notes_View Plug-in Bundle-SymbolicName: Notes_View; singleton=true Bundle-Version: 1.0.0 Bundle-ClassPath: Notes_View.jar, Notes.jar Bundle-Activator: Notes_View.Notes_ViewPlugin Bundle-Localization: plugin Require-Bundle: org.eclipse.ui, org.eclipse.core.runtime Eclipse-AutoStart: true
In the manifest file, you need to include the full path to your Notes.jar file. This ensures that Eclipse loads the file properly and that you have access to the classes. Edit the bold line above to include the full Notes.jar path, for instance:
Next, you import the Notes.jar file as a library into the project. This allows you to build the files and to import the lotus.domino.* classes into the project. To import the JAR file, right-click the project in the Package Explorer pane and select Properties. In the Properties box, select Java Build Path, click the Libraries tab, and then click the Add External JARs button to add Notes.jar.
Figure 4. Properties for Notes View project
After you have included the Notes.jar file in your build path, you can add the import directive and create a simple view. In the Package Explorer pane, click the src directory to open it, then open Notes_View.views. Open NotesView.java and select ViewContentProvider. Add the following import directives to the code:
To change what our view displays, modify the default code for the ViewContentProvider inner class. This class has a method, getElements. By removing the default response of three strings and replacing with the code below, the view can display Domino data. In this case, the data is the birthday and anniversary list in the local address book (names.nsf). Replace the default ViewContentProvider class code with the following:
A message, such as âAn error has occurred when creating this view,â may mean either that Eclipse cannot find the Notes.jar in the path and cannot create the Notes objects or that Eclipse cannot initialize Lotus Notes. Make sure your runtime library is set, and you have the full path in your manifest file. Then make sure to specify your Notes path, for instance, c:\lotus\notes, in your Path variable.
If all worked out well, you should see a list that reflects the birthdays listed in your local address book.
Figure 5. Notes View with local address book entries
We have just covered the basics of getting Lotus Notes/Domino to interact with Eclipse 3. From here, you can build any plug-in that you can imagine that requires access to the Notes/Domino back-end Java classes. You can open databases, create documents, send mail, read from view, trigger agents, and anything else that you would expect from Lotus Notes/Domino. The difference is that you can now take full advantage of the SWT widgets and Eclipse framework. By building upon these skills, you can add value and features to the IBM Workplace Client Technology as well as the Eclipse integrated development environment.
- The developerWorks: Lotus article, "Using Lotus Notes with Eclipse to manage and run your Java programs," describes how to use the Eclipse IDE to develop Java agents for Lotus Notes and Domino.
- The developerWorks article, "What is Eclipse, and how do I use it?," describes the Eclipse platform and answers some common questions.
- The Java Developer's Guide to Eclipse provides a solid introduction to Eclipse for Java developers from the IBM Eclipse Jumpstart team.
- Get the latest version of Eclipse at the Eclipse.org Web site.
- To learn more about Lotus Notes and Domino, visit the product page. You'll find technical documentation, how-to articles, education, downloads, product information, and more.
- Get involved in the developerWorks community by participating in developerWorks blogs.
- Browse for books on these and other technical topics.