ShowTable of Contents
This document outlines how to create a service for use in IBM Lotus Forms Application Experience Designer Beta (Application Designer). The method outlined in this document will be supported in the Beta release only, as the Application Designer's service feature is undergoing a large amount of development post-Beta. All feedback is welcome. To create a service it is expected that you have a reasonable understanding of Java and Eclipse, as well as experience with servlets and OSGI.
Eclipse J2EE version (tested on 3.5.1)
IBM JAVA 1.6
This document will reference the included sample service. Complete the following instructions to install and configure the sample.
Import Sample Service
1. In a new Eclipse workspace, click File
-> Existing Projects Into Workspace
, and then click Next
2. Select Select archive File
, browse to the ZIP file for the demo project (demo.zip), and then click Finish
Exploring the Sample
The sample should have 1 error displayed by Eclipse: No available bundle exports package 'com.ibm.freedom.service.registry'. The project is an OSGI plugin that references a package in the Application Designer's code that the Development team has not provided to Eclipse. For the Beta, this error can be safely ignored.
1 /src – The source code
1.1 com.ibm.demo.servlet.SKUServlet – The Java servlet which implements the back end of our service that does the actual work.
2 /META-INF/MANIFEST.MF – The manifest file that describes - among other things - what Java packages this bundle will use and what OSGI services it provides.
3 /OSGI-INF – The directory that contains OSGI service definitions. There are multiple ways to register a service in OSGI, in this sample we use XML activator files.
3.1 ServiceRegistry_DemoService.xml – The XML activator file that registers the front end our service (URL, inputs and outputs) defined in DemoService.xml.
3.2 SKUServlet.xml – The XML activator file that registers the SKUServlet class that is the back end code that will respond to calls made to the service defined in DemoService.xml.
4 /DemoService.xml – The XML file that defines our services front end (URL, inputs and outputs).
Defining a Service in Application Designer
This section will refer to the sample for all examples.
Currently a service in Application Designer consists of two distinct pieces:
1. Registering the front end which will be used by the client on the browser and includes:
- The URL to call
- The input URL parameters (and readable names)
- The output values in the returned JSON (and their readable names)
2. The back end service that responds to the call from the client:
- The back end must be at the same URL and port as the Application Designer in order not to violate browser cross-site scripting security settings.
- It can be written using any Technology that can respond to a URL, for our sample we are using a servlet and providing a mechanism for registering that servlet with Application Designer.
Defining the Front End
To define the front end you need to create the front end description file. The description file is an XML file (sample seen below) that describes the service.
The description file XML file consists of the following parts:
1. serviceRegistryEntry@id – Unique name of the service.
2. serviceRegistryEntry/name - Display name of the service that will appear in the Forms Composer when selecting a service to use.
3. serviceRegistryEntry/urlPattern – URL to use to call the service back end. For our example it should be the same as the URL defined in the back end configuration. Any input parameters (see below) will be inserted into the URL at runtime and must be indicated by using the '#' syntax shown in the example
4. serviceRegistryEntry/inbound – List of input parameters for the service.
- parameter@name – unique input parameter identifier that will be used to map it onto the URL
- parameter/title – Display name of the parameter that will be displayed in the mapping interface when setting up the service in the composer.
5. serviceRegistryEntry/outbound – List of output parameters for the service.
- parameter@name – Unique output parameter identifier that will be used to look it up in the JSON data returned as the response by the back end.
- parameter/title – Display name of the parameter that will be shown in the mapping interface when setting up the service in the composer.
The description file needs to be registered with the OSGI environment that the Application Designer server runs in. To do that we will use a activator file to register our service definition. This file should be placed in the /OSGI-INF directory. (This is set by the line Service-Component: OSGI-INF/*.xml in the MANIFSET.MF file)
A complete description of OSGI services and how they are registered is beyond the scope of this document, below are listed the pieces that need to be updated or changed when defining a new service entry. (see ServiceRegistry_DemoService.xml in the sample)
1. component@name – Unique name for your service, used internally.
2. component/property@value – Path to the description file for the service in your JAR.
Defining the Back End
The back end is the server side component that responds to service calls from the browser, reads in the input parameters, dose some work and returns the JSON formatted response. While this could be any server side technology (php, jsp, servlets etc) for the beta we only recommend using servlets which are registered as an OSGI service.
Create the servlet
1. Create a javax.servlet.http.HttpServlet as you normally would (see SKUServlet in the sample).
2. Implement the doGet method and configure it to handle the URL with inputs you create defined in the front end definition.
3. Perform your service (examples: call out to WSDL, check an LDAP registry, query a Database etc).
4. Return your response with the output parameters from the front end definition in the simple JSON format as:
Register the Servlet
As with registering the font end you must create an activation file and place it in the OSGI-INF directory. In this case we are registering our Servlet service with the OSGI (see SKUServlet.xml from the sample). The following elements need to be updated when you create a new service:
1. component@name – Unique name for the service which is registered with OSGI.
2. component/implementation@class – The class which we are registering.
3. component/property@value – The URL from the root of the Application Designer to which this servlet will be registered.
Deploying the Service to the Application Designer server
Now that your service is complete, you must build a JAR file and deploy it.
To build the JAR so that it can be deployed to the extensions directory where it will detected and loaded by the Application Designer:
1. Click File
-> JAR File
and then click Next
2. Click Browse
and select the location and name for the JAR file.
3. Your settings should look like:
4. Click Next
twice and make sure “Use existing manifest from workspace” is selected, and the MANIFEST.MF defined in the project is selected.
5. Click Finish
to create the JAR.
6. Copy the JAR into the extensions directory.
On Windows the default location of the extensions directory is C:\IBM\Lotus Forms\extensions. On Linux it is \opt\IBM\Lotus Forms\extensions.
If the extensions directory does not exist you will have to create it and restart the server.
to download a copy of this article.