ShowTable of Contents
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:
- Move the Java control classes and config files to a new plugin
- Implement the XspLibrary class and contribute it
- Package the plugin in a feature and an update site
- 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.
com.example.component.ExampleControl
com.example.renderkit.html_basic.ExampleRenderer
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:
package com.example.library;
import com.ibm.xsp.library.AbstractXspLibrary;
public class ExampleLibrary extends AbstractXspLibrary {
public String getLibraryId() {
// TODO Auto-generated method stub
return null;
}
}
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.
getFacesConfigFiles
getPluginId
getXspConfigFiles
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.
package com.example.library;
import com.ibm.xsp.library.AbstractXspLibrary;
public class ExampleLibrary extends AbstractXspLibrary {
public String getLibraryId() {
return "com.example.library";
}
@Override
public String getPluginId() {
return "com.example.xsp";
}
@Override
public String[] getFacesConfigFiles() {
return new String[] {
"META-INF/example-faces-config.xml",
};
}
@Override
public String[] getXspConfigFiles() {
return new String[] {
"META-INF/exampleControl.xsp-config",
};
}
}
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.
Type: com.ibm.xsp.Library (same as the service)
Class: com.example.library.ExampleLibrary
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.