Extending LiveCycle ES software through custom DSC development – Part 1: Create a basic service component

This is Part 1 of the series. The goal of this article is to introduce the basic environment around a custom Document Service Component (DSC) and to show how you can go about developing one yourself. Part 2 will expand on that information and demonstrate more advanced Java constructs (beans, enumerated types, etc.).

With Adobe LiveCycle ES software, you have the ability to extend the product's functionality using Java classes. This means that you can develop your own Java classes that act as operations within a LiveCycle ES workflow. Extending the LiveCycle product in this way enables you to add your own functionality, interact with your existing programs, and integrate with third-party applications. Once a component is deployed to LiveCycle ES software, the services contained within the component become LiveCycle services.

Component Architecture

Document Service Components consist of three main elements (see Figure 1):

• Service class(es): your Java classes containing the code that is executed when the service is run. The service will have at least one class and quite often will contain several classes, depending on the complexity of the project.
• Resources file(s): additional libraries, images, property files, and other resources required by the service. This may include utility JAR files as well as the icons for your DSC. (I'll explain the icons later.)
• Component file: a single component.xml file describing all aspects of your component to LiveCycle ES. The component.xml file is used for the DSC property sheet as well as several other operations.

These files will be combined into a single JAR file that will be imported into LiveCycle ES software using the Workbench tool.

A simple DSC

The easiest way to explain DSC development is to build a custom component. Here I will use a very simple "Hello, world" example consisting of a single Java class file and the required component.xml.

The Java class

Create a simple project and Java class file using your favorite editor (I prefer Eclipse, but the choice is up to you) called helloComponent.java. Put it in whatever package you want; I'm using com.adobe.sample. Add a method that takes a string and returns another. You can then add some code to return a string that includes the input string—something like this:

Compile the class into a .class file.

The Component XML file

Okay, now that you have a simple Java class, add the component descriptor file. To be frank, it's a bit of a pain to write the XML file from scratch. You can copy one from an existing component (or from this article).

This sample includes the following tags:

• component-id: a unique identifier for your component.
• version: the version info for your component
• supports-export: specifies whether the component should beincluded if you export an archive that uses the component; that is, should thecomponent be exported as part of the LiveCycle Archive (LAR) file.
• services: describes the services included in this component(this one only has one service)
  • service name: the name of the serviceonce it is deployed
  • auto-deploy: The category-id attribute is the name of the service category in which this componentwill be deployed.
  • implementation-class: the package andclass name of your component
  • operations: These equate to publicmethods in your class. Any methods you wish to expose need to have theirown operation tag.
    • operation name: the name of the method
    • input-parameter: where you list themethod's input parameters. Note that the type attributecorresponds to the Java class for that parameter.
    • output-parameter: the object that isreturned by the method.

Note that there are many other tags, but this is all we needfor this simple example.

Make a JAR file

Now that you have a compiled class file and the propercomponent.xml file, you can create a Java Archive file that will contain all ofthe component parts. The JAR file will be imported into LiveCycle ES software usingthe Workbench tool. You can build the JAR file using a command line tool orusing your IDE; however, there are a few things to keep in mind:

• Include all java class files
• Include all resource files (images, utility jar files, otherresources)
• Include the component.xml; make sure it's at the root.

Note: If you use Eclipse to create your JAR file,make sure that that the "Compress the contents of the JAR file"option is off. You will not be able to import compressed JAR files.

Import your component

The following steps will import your component intoLiveCycle ES software:

1. Open LiveCycle Workbench ES and log in to a LiveCycle ES server.
2. Switch to the Components window (if you don't see the Components window,choose Window > Show Views > Components from the menu bar).
3. Right-click the root of the Components tree and choose "InstallComponent…"
4. Browse to your JAR file and click Open.
5. Expand the Components tree and find your component (the components arelisted by package and class name).
6. Right-click the component and choose Start Component.

The component should now appear in the Services tab underthe category you specified in the component.xml file (see Figure 2). You cannow use your component in your workflow process. Note that the property sheetwill reflect the information you put in the component.xml file.

Where to go from here

This article shows a pretty simple component, but it is a starting point. To learn how to create an advanced service component, read Part 2 of this series. For more in-depth information on developing components, please refer to the official Adobe documentation.