Developing Components for LiveCycle

Component architecture

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

View full size graphic

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

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

View full size graphic

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

• Endpoint: Associates a service with an available connector mechanism for invoking its operations. An administrator sets endpoints by using 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 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 Administration Console.

• Property editor: A graphical user interface (GUI) that is available within Workbench 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.

View full size graphic

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

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 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 and can handle basic data types.

View full size graphic

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 Administration Console and Workbench, 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.

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.

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.