LiveCycle Developer Center

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.

Requirements

In order to make the most of this article, you need the following software and files:

LiveCycle ES

• Try
• Buy

LiveCycle Workbench ES

• Try
• Learn more

Java development environment

• A Java development environment using JDK 1.5 (I am using Eclipse 3.2 as my IDE, but you can use whatever Java environment in which you feel comfortable)

Sample files:

• hello_component.zip (ZIP, 3K)

Prerequisites:

As a great deal of this article is about developing your own software component, I assume that you are comfortable coding in Java. You should also have a basic working knowledge of the LiveCycle ES workflow environment, including the LiveCycle ES Workbench tool.

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.

Figure 1. DSC Architecture

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:

package com.adobe.sample;
public class helloComponent {
    public String hi(String yourName){        
        return "Hello, " + yourName;
    }
}

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).

<component xmlns="http://adobe.com/idp/dsc/component/document">
    <component-id>com.adobe.sample.helloComponent</component-id>
    <version>8.0.0</version>
    <supported-connectors/>
    <supports-export>true</supports-export>
    <services>
        <service name="helloComponent" orchestrateable="true" title="Hello Component">
            <hint>A simple component to show how to build a DSC</hint> 
            <auto-deploy major-version="1" minor-version="0" category-id="Hello"/>
            <implementation-class>com.adobe.sample.helloComponent</implementation-class>
            <operations>
                <operation name="hi">
                    <hint>Returns a string</hint>
                    <input-parameter name="yourName" title="Put your name here" type="java.lang.String">
                        <hint>Put your name here</hint>
                           <supported-expr-types>Literal,XPath,Template,Variable</supported-expr-types>
                    </input-parameter>
                    <output-parameter name="result" title="Result" type="java.lang.String">
                        <description>A message from the component</description>
                        <hint>A message from the component</hint>
                    </output-parameter>
                    <description>A Hello, world component</description>
                </operation>
            </operations>
        </service>
    </services>
</component>

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 be included if you export an archive that uses the component; that is, should the component 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 service once it is deployed
  • auto-deploy: The category-id attribute is the name of the service category in which this component will be deployed.
  • implementation-class: the package and class name of your component
  • operations: These equate to public methods in your class. Any methods you wish to expose need to have their own operation tag.
    • operation name: the name of the method
    • input-parameter: where you list the method's input parameters. Note that the type attribute corresponds to the Java class for that parameter.
    • output-parameter: the object that is returned by the method.

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

Make a JAR file

Now that you have a compiled class file and the proper component.xml file, you can create a Java Archive file that will contain all of the component parts. The JAR file will be imported into LiveCycle ES software using the Workbench tool. You can build the JAR file using a command line tool or using 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, other resources)
• 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 into LiveCycle 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 "Install Component…"
4. Browse to your JAR file and click Open.
5. Expand the Components tree and find your component (the components are listed by package and class name).
6. Right-click the component and choose Start Component.

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

Figure 2: The imported Hello component

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.

This work is licensed under a Creative Commons Attribution-Noncommercial-Share Alike 3.0 Unported License

About the author