Programming with LiveCycle ES2.5

Developing Components

You can develop components within a Java integrated development environment (IDE), such as Eclipse, that you can deploy to LiveCycle ES2.5. Components are independent units of production that contain operations that plug into LiveCycle ES2.5. Components are combined with other components to build applications using LiveCycle Workbench ES2. By developing components, you can extend LiveCycle ES2.5 by adding functionality to meet your business requirements.

You can, for example, create an e-mail component that can send e-mail messages that contain file attachments. After you create a component and deploy it to LiveCycle ES2.5, you can build processes in Workbench ES2 that use the component's operations. For example, you can develop a process that retrieves a PDF document, applies usage rights, and sends the document as a file attachment.

Note: Sections within this document discuss how to create an e-mail component as an example of how to create a component. However, if you want to use an e-mail component, it is recommended that you use the e-mail component that is available with LiveCycle ES2.5.

When a component is deployed to LiveCycle ES2.5, the services contained within the component are stored within the service container. Services require a service container to run, similar to how Enterprise JavaBeans (EJBs) require a J2EE container. LiveCycle ES2.5 has a service container, which is responsible for managing the life cycle of services, and routing interactions between clients and services. For more information, see Service container.

Before creating components, it is recommended that you have a good understanding of invoking services within LiveCycle ES2.5. It is assumed that you understand concepts such as invocation requests, long-lived and short-lived processes.

For information about creating a component, see Creating Your First Component.

For information about invoking a process, see Invoking Human-Centric Long-Lived Processes.

Adobe Developer website

The Adobe Developer website contains the following articles that discuss invoking LiveCycle ES2.5 services using the Java API:

Creating enterprise database components

Invoking web services using custom components

Component architecture

A component consists of resources, metadata, and binary implementations of one or more services packaged together as a Java Archive (JAR) file.

The following list explains the entities in the above illustration:

        Service: Contains business logic that consists of Java classes and interfaces. Service operations are specified by creating a Java interface that contains public methods. Each method defined within the interface becomes a service operation. For information, see Defining the service implementation.

        Property Editor: Exposed in Workbench ES2 and enables process authors to specify input values required by the service as well as handle output values. Default property editors allow process authors to work with basic data types, such as integers and strings. For information, see Property editors.

        Component XML file: Exists for each component and specifies information such as the component's services, service operations, and other metadata related to the component, such as the component's identifier value. For more information about the component XML file, see the Component XML Reference.

        Resources: Includes external libraries, icons, and other resources that the component requires. Resources must be packaged within the component's JAR file. For information, see Deploying your component.

The following illustration describes the relationship between components, services, and other component entities.

The following list explains the entities in the above illustration:

        Component: The packaged set of classes, resources, and metadata that are installed into the component registry for supporting the deployment and execution of one or more services.

        Service: Contains business logic that LiveCycle ES2.5 executes.

        Endpoint: Associates a service with an available connector mechanism for invoking its operations. An administrator sets endpoints by using LiveCycle Administration Console.

        Version: Both a service name and service version identifies the service. What can change from version to version is the service's configuration values, its input values, its output values, and so on. Client applications can bind to a particular version of a service or to simply allow for the default behavior. The default behavior routes invocation requests to the latest service version.

        Operation: A service consists of one or more operations with each operation performing a specific action. For example, sending an e-mail message represents an operation.

        Input parameter: An operation contains zero-to-many input values, with each input value representing an expected data element that an operation requires. Input values are specified either in Workbench ES2 or by passing parameter values to an API method.

        Output parameter: An operation contains zero-to-many output parameters, with each output value representing an expected data value.

        Configuration values: A service contains zero-to-many configuration values, with each configuration value representing an expected data element that an administrator configures. Configuration values correspond to properties that belong to the service's implementation class (for example, have setter and getter methods). An administrator can also amend a configuration value by using LiveCycle Administration Console.

        Property editor: A graphical user interface (GUI) that is available within Workbench ES2 and allows users to specify required input and output values.

Component states

A component can exist in one of several states, as shown by the following illustration.

After a component is created and deployed, it is not in a running state. While in a stopped state, an administrator can either start the component or uninstall it. However, while in a stopped state, services that belong to the component cannot receive invocation requests. When a component is started and is in a running state, its services can accept invocation requests. An administrator can stop the component, which prevents the component's services from accepting invocation requests.

Class loading

For class loading, LiveCycle ES2.5 uses methodology specified by the OSGi Alliance, which specifies a mechanism for sharing classes among components within the service container. For information, see http://www.osgi.org/.

A class-loader object is responsible for loading classes into the Java Virtual Machine (JVM™). When classes reference other classes or resources, the referenced classes and resources are found through the same class loader. A class loader loads a dependant class itself or delegates the loading to another class loader. This approach effectively creates a namespace for classes. A class name is uniquely identified in the JVM by its fully qualified name and the class loader that created or loaded it. This behavior implies that classes can be loaded multiple times from different class loaders.

Although these classes are the same, they are not compatible. The service container must ensure that classes are loaded onto different class loaders when those classes are isolated. Similarly, the service container ensures that classes are only loaded once when they are shared among multiple components.

Each installed component has its own class loader associated with it. This class loader provides a component with its own namespace, to avoid name conflicts, and allow package-sharing between components. The class loader finds classes and resources in the component by searching the component's class path.

Exception handling

There are two types of exceptions, checked and unchecked. Checked exceptions, which are used when a method makes its clients aware of the known exceptional states, are declared in method signatures. Unchecked exceptions are not declared. Checked exceptions do not cause an action to stall in a process. An unchecked exception stall an action within a process.

As a component developer, you do not need to subclass any particular class to throw checked exceptions. Checked exceptions are derived from the implementation being used. That is, all checked exceptions defined in the signature of the implementation class are passed to the invoker of the operation.

Transactions

LiveCycle ES2.5 supports the following transaction types for transaction management:

        Container Managed Transactions (CMT): Component developers declaratively specify the transactional behavior of the operations on a component within the component.xml descriptor.

        Service Managed Transactions (SMT): Component developers programmatically specify their transaction usage as part of their implementation code.

        No Managed Transactions: No transaction management is available and therefore transaction infrastructure is required.

Note: For information about creating service managed transaction components, see Creating Service Managed Transaction Components.

Property editors

A property editor is an entity within a component that is used to create and manipulate an object to and from its string representation. A process author uses a property editor within Workbench ES2 to specify input and output values for an operation. That is, property editors assist process authors when creating processes.

The UI component of a property editor is rendered to users within a property sheet, which combines one or more property editors for a specific context: configuring a service, referencing it at design time, and when invoking a service through a UI. The following illustration shows a basic property editor that is available in Workbench ES2 and can handle basic data types.

Serialization and coercion

A property editor is bound to a single Value object, which it uses to both store its information and make it available to the service container at runtime for invoking services. Typically, the Value object that is serialized and deserialized at configuration and design time is not of the same type that is expected by the input and configuration parameter it is ultimately bound to at runtime. As a result, the Value object used by the property editor has to be coerced into a form that can be used at runtime.

For applications, such as LiveCycle Administration Console and Workbench ES2, the property sheet implementation makes use of a com.adobe.idp.dsc.datatype.TextSerializer object. This object is optionally provided by the property editor component to serialize the object value, created and manipulated by the UI component, into a string representation. The string representation is stored in the Service Registry for configuration information or inside a process definition. At runtime, values that had been stored as strings are deserialized back to their original object form and made available to the target service to be invoked.

System property editors

A system property editor can be reused and referenced across multiple components and can support common use cases. The following table lists the data types that a system property editor supports.

Property editor

Data type

Description

TextField

com.adobe.idp.dsc.propertyeditor.
system.TextpropertyEditorComponent

Allows for basic text entry.

Text Area

com.adobe.idp.dsc.propertyeditor.
system.
TextAreaPropertyEditorComponent

Allows for basic text entry across multiple lines.

CheckBox

com.adobe.idp.dsc.propertyeditor.
system.
CheckBoxPropertyEditorComponent

Allows for true and false selections.

Calendar

com.adobe.idp.dsc.propertyeditor.
system.
CalendarPropertyEditorComponent

Used to select Date and DateTime values.

Spinner

com.adobe.idp.dsc.propertyeditor.
system. SpinnerPropertyEditorComponent

Used for entry of numeric data types (has buttons for spinning a numeric value up or down).

ComboBox

com.adobe.idp.dsc.propertyeditor.
system.ComboBox

Allows for a set of items specified as part of a component.xml file to be selected from at design and configuration time.

Enum

com.adobe.idp.dsc.propertyeditor.system.EnumPropertyEditorComponent

Allows the user to specify a specific enum value.

Password

com.adobe.idp.dsc.propertyeditor.
system.
PasswordPropertyEditorComponent

Lets users enter encrypted characters into a text box.

RadioButton

com.adobe.idp.dsc.propertyeditor.
system.
RadioButtonPropertyEditorComponent

Lets users select one among many choices.

List

com.adobe.idp.dsc.propertyeditor.
system.
ListPropertyEditorComponent

Lets users enter data as a list of items.

Document Picker

com.adobe.idp.dsc.propertyeditor.
system.
DocumentPropertyEditorComponent

Lets users select a local file from their file system and store it inside a com.adobe.idp.Document object at run time.

If a property editor is not explicitly specified in the component.xml file for a parameter value, the property sheet implementation in which the corresponding parameter is bound locates the default property editor. The default property editors are implicitly mapped and rendered for standard data types according to the following table.

Data type

Property editor

java.lang.String

com.adobe.idp.dsc.propertyeditor.system. TextPropertyEditorComponent

com.adobe.idp.
Document

com.adobe.idp.dsc.propertyeditor.system.
DocumentPropertyEditorComponent

Java.lang.Number (or numeric primitives)

com.adobe.idp.dsc.propertyeditor.system.
SpinnerPropertyEditorComponent

Composite editors

When creating a component that uses custom data types, you define the component's composite editor so that the component can handle custom data types. For information, see Creating Components That Use Custom Data Types.