Creating an XPages Library

Introduction

This article is part of the XPages Extensibility API Developers Guide.

This article shows you step-by-step (with screenshots and code samples) how to create an XPages library to package an existing Java control so it can be used by multiple applications. This assumes you have already created a Java control for XPages in an NSF application. If not, you can begin with the article "Creating a Java Control in an NSF".

If you are already familiar with XPages library contents, you can continue with the article "Blank XPages Library".

The rough steps are:

1. Move the Java control classes and config files to a new plugin
2. Implement the XspLibrary class and contribute it
3. Package the plugin in a feature and an update site
4. Build the update site and make it available to people who need to install it into Domino Designer

Create the plugin

In Domino Designer, switch to the Java perspective. Select Window - Open Perspective - Other... - Java - OK.

Create a new plugin project

From the menu bar, select File - New - Project... - Plugin Development - Plugin Project - Next.



Enter the project name "com.example.xsp".
If you want to save it under source control, you should specify the path in the location field. Otherwise, the default location is fine.
Enable the check box "Create a Java project". The default source and output folders are fine.
Select Next.



Change the Plugin Version to "1.0.0.qualifier". This will append the current timestamp to the plugin version.
Choose a translatable Plugin Name and enter your company name as the Plugin Provider.
Change the Execution Environment to 1.5 so that it will work with the Notes Client on the Mac operating system.
Disable the first two check boxes: "Generate an activator" and "This plugin will make contributions to the UI".
Select Finish.

If prompted to open the Plugin Development perspective, select Yes. Otherwise, select Window - Open Perspective - Other... - Plugin Development - OK.

Copy in the Java classes

Here's a handy tip when copying Java classes to ensure the copy has the same package name as the original.
Open the Java class in the editor. Copy all of the file's contents then right-click the source folder in the plugin project and select Paste.
This will create the Java class file with the correct package. Alternatively, if you copy the file then you will have to manually create the package first.

Copy the Java classes from your application into the source folder of the plugin project.You will get compile errors in both classes.

In the application, open the "plugin.xml" file and select the Dependancies tab. Note that there is a dependancy on "com.ibm.xsp.core". That's the dependancy you need.



Double-click on it in the dependancies list and copy the plugin ID.



In the plugin project, open the file "META-INF/MANIFEST.MF" and select the Dependancies tab.
Under the section "Required Plugins", select Add. Paste the plugin ID "com.ibm.xsp.core" in the dialog and select OK.



Finally, save the changes and the compile errors will go away.

Copy in the config files

In the plugin project, create a new META-INF folder under the source folder.
Right-click the plugin project and select New - Other... - General - Folder - Next.

Create this new folder using these details and select Finish.
Parent folder: com.example.xsp/src
Folder name: META-INF



There is already a META-INF folder at the project root containing the MANIFEST.MF file. That is the only file that will ever be present in the root META-INF folder but we will be adding files to the "src/META-INF" folder.

Copy in the xsp-config file from the application ("WebContent/WEB-INF/exampleControl.xsp-config") to the plugin project at the location "src/META-INF".
Copy in the faces-config file from the application to the plugin project at the same location, and rename it to "example-faces-config.xml".
You cannot have a file with the name "faces-config.xml" in a library, they should only be present in an application.

Create the library

Create the library class

The XspLibrary is used by the infrastructure to find the names of the config files and other information about this library of controls.

Right-click the plugin project and select New - Other... - Java - Class - Next.

Enter these details and select Finish.
Package: com.example.library
Name: ExampleLibrary
Superclass: com.ibm.xsp.library.AbstractXspLibrary



The generated class is like so:



Your class must extend from the provided default implementation because in later releases other methods may be added to the XspLibrary interface, with a default implementation in the AbstractXspLibrary class.

Right-click the library class (ExampleLibrary.java) and select Source - "Override/Implement Methods".
Enable the check boxes beside the following methods and select OK.


The getDependencies method is not needed because this library will only depend on the core library which is in the default dependancies list. If you needed to extend a control provided in another library you have implemented, you would need to list a dependancy on that other library.
The isDefault method is not needed because this library is not a default library. Only applications that explicitly depend on this library will load it as a prereq.

The getLibraryId method should return "com.example.library". This is the ID that applications will use to depend on this library. We're using a naming convention that should end in ".library".
The getPluginId method should return the plugin's id. The pluginId is necessary in Domino Designer where it is added to the application's "plugin.xml" file so that the application can compile references to classes in the shared library.
In the getFacesConfigFiles and getXspConfigFiles methods, list the faces-config and xsp-config files in this library respectively. Both these methods use "/" as the path separator.

This resulting library class should be as follows.

Contribute the library as an extension

The XspLibrary is contributed through the Eclipse Extension point named "com.ibm.commons.Extension".

In the plugin project, open the "META-INF/MANIFEST.MF" file. In the Dependancies tab, add a dependancy on "com.ibm.commons" and move it up before the dependancy on the "com.ibm.xsp.core" plugin.



In the Extensions tab, select Add - "com.ibm.commons.Extension" - Finish.



Select the "(service)" entry under the extension then enter the following details and Save.


Note, that extension is saved to the new "plugin.xml" file which is created in the library plugin. It is edited through the same editor as the "MANIFEST.MF" file.

Package the plugin in a feature and update site

To use the plugin into Domino Designer, you need to create a feature and package it into an update site.

Create a feature

Select File - New - Project... - "Plugin Development" - "Feature Project" - Next.

Enter the following details and select Next.
Project name: com.example.xsp.feature
Feature Name: Example XSP Feature
Feature Version: 1.0.0.qualifier



Select your plugin from the "Referenced Plugins and Fragments" list and Finish.

Create an update site

Select File - New - Project... - "Plugin Development" - "Update Site Project" - Next. Enter the Project name "libraryUpdateSite" and select Finish.
In the update site, open the file "site.xml". In the "Site Map" tab, select "Add Feature" - "com.example.xsp.feature" - OK. Save your changes.

Build the update site

In the update site, open the file "site.xml". In the "Site Map" tab, select the button "Build All".



This will build the features and plugins and save the output to the update site in the workspace. If you cannot see the build output, in the "Package Explorer" view, right-click the update site and select Refresh.

If you select "Build All" again, it will rebuild the update site but with a later time stamp in the version. When Eclipse installs from an update site, it will only install the latest version number so copies with an earlier time stamp will be ignored.

The update site is now ready to be installed into Domino Designer. To learn how to do this, you can continue with the article "Using an XPages Library in Domino Designer". If installing it yourself, you can just install from the update site's current folder location or to share it with other developers you can publish it on a web server.

For more information about deployment, refer to the article "Deploying XPages Libraries"

Example files

Download the example files archive. This contains the plugin source, feature source and the update site containing the built plugin and fragment.

To use the example files, switch to the Java perspective and import the example files archive.
Select File - Import - General - "Existing Projects into Workspace" - Next - "Select archive file" - Browse - Finish.