You can develop components within a Java integrated development
environment (IDE), such as Eclipse, that you can deploy to LiveCycle.
Components are independent units of production that contain operations
that plug into LiveCycle. Components are combined with other components
to build applications using Workbench. By developing components,
you can extend LiveCycle 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, you can build processes
in Workbench 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.
注意: 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.
When a component is deployed to LiveCycle, 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 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.
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.
The Adobe Developer website contains the following articles that
discuss invoking LiveCycle 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 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.
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.
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.
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.
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.