Created

28 January 2008

Requirements

Prerequisite knowledge

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 creating a custom component described in Creating your first LiveCycle ES application.

User level

Intermediate

Setting up your development environment

The first step to create a database component is to set up your development environment by creating a new Eclipse Java project. The version of Eclipse that is supported is 3.2.1 or later.

Like other Java projects, you must add JAR files that your Java business logic depends on to your project's class path. To create an e-mail component, create a new Eclipse project and name it DatabaseComponent. Ensure that you add the mysql-connector-java-3.1.14-bin.jar file to your project's class path.

Creating your application logic

To create application logic for your database component, perform the following tasks:

  1. Define the service interface.
  2. Define the service implementation.

Defining the service interface

A service implementation is essentially a Plain Old Java Object (POJO) that you can develop by creating a Java interface that defines the service's operations (public methods), input values, and return values. The public methods that are defined within the Java interface become operations that are exposed by the service.

The database component that is developed in this section exposes two operations named UpdateApproveTable and UpdateDeclineTable that must be defined in the component interface. Each operation accepts five string parameter values that are used to update the corresponding tables. The following example shows the interface that belongs to the database component.

Example: Defining the DatabaseComponent interface

package com.adobe.sample.database; import java.sql.*; import java.sql.DriverManager.*; public interface DatabaseComponent { public void UpdateApproveTable(String firstName, String lastName, String phone, String mortgage); public void UpdateDeclineTable(String firstName, String lastName, String phone, String mortgage); }

The DatabaseComponent interface belongs to a package named com.adobe.sample.database.

You can create a LiveCycle ES component that performs enterprise database operations such as adding new records or retrieving data sets. By creating a database component, you can implement custom database functionality in processes that you create using Adobe LiveCycle Workbench ES. For example, consider the following example process that extends the process created in Creating your first LiveCycle ES application (see Figure 1).

After the bank manager processes the mortgage application by either accepting it or declining it, the process updates a database by using a custom database component. Therefore, if the bank manager approves the form, the Approve table is updated; otherwise, the Decline table is updated.

Note: The LiveCycle ES software contains a JDBC service that supports various database operations that you can use. However, this topic describes how to create a custom database component in case you want to extend or replace the JDBC service. For example, you can create a component that enables a LiveCycle Workbench ES user to update a database by specifying XPATH expressions that correspond to form fields as opposed to writing SQL statements.

You can create a component that interacts with a relational database that supports either a Java API or a web service. Suppose you want to create a component that updates an enterprise database that does not contain a Java API; however, it exposes a web service. In this situation, you can create Java proxy classes that consumes the database's native soap stack and use these Java proxy classes within a Java project used to create a LiveCycle ES component. For information about creating Java proxy classes, read "Creating Java proxy classes using Apache Axis" in the LiveCycle ES SDK Help.

This article discusses how to create a LiveCycle ES component that updates a relational database named mortgagedb that contains two tables named ApproveTable and DeclineTable. For simplicity, these tables contain five string fields as described in the following list:

  • cust_id – Stores a unique customer identifier (this field functions as the primary key)
  • first_name – Stores the customer's first name
  • last_name – Stores the customer's last name

Note: The component that is created in this section uses the mysql-connector-java-3.1.14-bin.jar file. To follow along with this section, download this JAR file.

To develop a database component, perform the following steps:

  1. Set up your development environment.
  2. Create your application logic that interacts with an enterprise database.
  3. Define the component XML file.
  4. Package the database component into a JAR file.
  5. Deploy the component.
  6. Test your component.

After you deploy a component to the LiveCycle ES software, you can use it to create a process using LiveCycle Workbench ES, or you can invoke the component's service(s) by using an invocation method, such as the Java API, LiveCycle Remoting, or web services. For information about invoking services, see the LiveCycle ES SDK Help.

Defining the service implementation

You must create a service implementation class that implements the DatabaseComponent interface. A service implementation must conform to the following restrictions:

  • The implementation class must have a public no-argument constructor.
  • The service implementation class must be stateless.
  • Input parameters, output parameters, and exceptions must be serializable.

The business logic that is executed by the LiveCycle ES software when the operations are invoked must be specified in the corresponding methods. For example, the UpdateApproveTable method that is defined in the DatabaseComponent interface must contain Java application logic that adds a record to the Approve table (the example in this section shows Java API application logic that updates the database).

The UpdateApproveTable method requires the following arguments:

firstName: Specifies mortgage applicant's first name.

lastName: Specifies mortgage applicant's last name.

phone: Specifies mortgage applicant's phone number.

mortgage: Specifies the mortgage amount.

The implementation class also contains a method named getPrimaryKey that is reponsible for generating a primary key for both the Approve and Decline tables. The following Java code shows the DatabaseComponentImpl class that implements the DatabaseComponent interface.

Example: Defining the DatabaseComponentImpl class

package com.adobe.sample.database; import com.mysql.jdbc.*; import java.sql.*; import java.sql.Connection; import java.io.*; import java.sql.DriverManager; public class DatabaseComponentImpl implements DatabaseComponent { public void UpdateApproveTable(String firstName, String lastName, String phone, String mortgage) { //This method will update the ApproveTable try{ Class.forName("com.mysql.jdbc.Driver"); // Specify an URL to MySQL String url = "jdbc:mysql://localhost:3306/mortgagedb"; // Create a Connection object java.sql.Connection con = DriverManager.getConnection(url,"root", "root"); //Create the primary key value int pKey = getPrimaryKey(con,"ApproveTable"); pKey ++; String numRec = Integer.toString(pKey ); // Add a record to the ApproveTable table java.sql.Statement st = con.createStatement(); st.executeUpdate( "INSERT INTO ApproveTable(cust_id, first_name, last_name, phone, mortgage) VALUES("+numRec+",'"+firstName+"','"+lastName+"','"+phone+"',"+mortgage+")"); con.close(); } catch (Exception ee) { ee.printStackTrace(); } } public void UpdateDeclineTable(String firstName, String lastName, String phone, String mortgage) { //This method will update the DeclineTable try{ Class.forName("com.mysql.jdbc.Driver"); // Specify an URL to MySQL String url = "jdbc:mysql://localhost:3306/mortgagedb"; // Create a Connection object java.sql.Connection con = DriverManager.getConnection(url,"root", "root"); //Create the primary key value int pKey = getPrimaryKey(con,"DeclineTable"); pKey ++; String numRec = Integer.toString(pKey); //Add a record to the ApproveTable table java.sql.Statement st = con.createStatement(); st.executeUpdate( "INSERT INTO DeclineTable(cust_id, first_name, last_name, phone, mortgage) VALUES("+numRec+",'"+firstName+"','"+lastName+"','"+phone+"',"+mortgage+")") ; con.close(); } catch (Exception ee) { ee.printStackTrace(); } } private int getPrimaryKey(java.sql.Connection con, String tableName){ //This method determines the number of records in the specified table int numRecs = 0 ; try{ java.sql.Statement st = con.createStatement(java.sql.ResultSet.TYPE_SCROLL_INSENSITIVE, java.sql.ResultSet.CONCUR_READ_ONLY); java.sql.ResultSet rs = st.executeQuery("SELECT * from "+tableName); while(rs.next()){ numRecs++; } } catch (Exception ee) { ee.printStackTrace(); } return numRecs; } }

Defining the component XML file for the database component

You must create a component XML file to deploy a component to the LiveCycle ES software. A component XML file exists for each component and provides metadata about the component. You can use the component XML file to customize your component to meet your requirements. For example, you can specify an icon that is visible to LiveCycle Workbench ES users who build processes by using the component. For information about the schema of a component XML file, see "Component XML Elements" in the LiveCycle ES SDK Help.

The component XML file that is used for the database component contains the following XML elements:

component-id: Specifies a unique identifier for the component.

version: Specifies the component version.

class-path: Specifies JAR files that are required by the component. For JAR files to be used by the component, they must be specified within this element.

services: Specifies the services that are part of this component. This element can contain one or many service elements. For a single service component, specify one service element.

service: Specifies the name of the service. Specify DatabaseComponent.

implementation-class: Specifies the name of the implementation class for the service. Specify com.adobe.sample.database.DatabaseComponentImpl (this is the fully-qualified name).

small-icon: Specifies the small icon that is used to display the service in the tool bar and in LiveCycle Workbench ES.

large-icon: Specifies the large icon that is used to display the service.

operations: Specifies the operations that are part of this service. This element can contain one or many operation elements.

operation: Specifies the operation name. For this component created in this article, specify UpdateApproveTable and UpdateDeclineTable.

input-parameter: Specifies the name and type of the input parameter for this specified operation. An input parameter element must exist for each parameter that corresponds to the operation. Also, each parameter's data type must be specified using the type attribute.

The following component.xml file is used for the database component.

Example: Defining the component XML file for the database component

<component xmlns="http://adobe.com/idp/dsc/component/document"> <!-- Unique id identifying this component --> <component-id>com.adobe.sample.database.DatabaseComponent</component-id> <!-- Version --> <version>1.0</version> <class-path>mysql-connector-java-3.1.14-bin.jar</class-path> <!-- bootstrap implementation class --> <bootstrap-class>com.adobe.sample.database.BootstrapImpl</bootstrap-class> <!-- lifecycle implementation class --> <lifecycle-class>com.adobe.sample.database.LifeCycleImpl</lifecycle-class> <!-- Start of the Service definition --> <services> <!-- Unique name for service descriptor. The value is used as the default name for deployed services --> <service name="DatabaseComponent"> <!-- service implementation class definition --> <implementation-class>com.adobe.sample.database.DatabaseComponentImpl</implementation-class> <!-- description --> <description>Enables you to update the Mortgage DB</description> <!-- You can provide your own icons for a distinct look --> <small-icon>icons/db.gif</small-icon> <large-icon>icons/db.gif</large-icon> <!-- automatically deploys the service and starts it after installation --> <auto-deploy service-id="DatabaseComponent" /> <operations> <operation name="UpdateApproveTable"> <!-- input parameters to the "UpdateApproveTable" method --> <input-parameter name="firstName" title="First Name" type="java.lang.String"> </input-parameter> <input-parameter name="lastName" title="Last Name" type="java.lang.String"> </input-parameter> <input-parameter name="phone" title="Phone" type="java.lang.String"> </input-parameter> <input-parameter name="mortgage" title="Mortgage" ype="java.lang.String"> </input-parameter> <faults> <fault name="Exception" type="java.lang.Exception"/> </faults> </operation> <operation name="UpdateDeclineTable"> <!-- input parameters to the "UpdateDeclineTable" method --> <input-parameter name="firstName" title="First Name" type="java.lang.String"> </input-parameter> <input-parameter name="lastName" title="Last Name" type="java.lang.String"> </input-parameter> <input-parameter name="phone" title="Phone" type="java.lang.String"> </input-parameter> <input-parameter name="mortgage" title="Mortgage" type="java.lang.String"> </input-parameter> <faults> <fault name="Exception" type="java.lang.Exception"/> </faults> </operation> </operations> </service> </services> </component>

Packaging the database component into a JAR file

To deploy the component to the LiveCycle ES software, you must package your Eclipse project into a JAR file. Ensure that the mysql-connector-java-3.1.14-bin.jar file that the component's business logic depends on is also included in the component JAR file. As well, the component XML file must be present. The component.xml file and external JAR file must be located at the root of the JAR file.

It is recommended that you include only the JAR files that are required to execute the Java application logic located in your component. That is, if a JAR file is not required by your component, do not include it in the component JAR file. Although you must include adobe-livecycle-client.jar in your project's class path in order to use a com.adobe.idp.Document object in your application logic, it is not necessary to include this JAR file in the component JAR file because this data type is already part of the service container.

The following illustration shows the Eclipse project's content, which is packaged into the databse component's JAR file (see Figure 2).

Note: Package the database component into a JAR file named adobe-dbSample-dsc.jar. In the previous illustration, notice that JAVA files are listed. After the database component is packaged into a JAR file, the corresponding CLASS files will also be part of the component JAR file. Without the CLASS files, the component will not work.

Deploy the component

Deploy the component to the LiveCycle ES software so that you can use it within LiveCycle Workbench ES to build processes. You can use LiveCycle Workbench ES to deploy the database component.

Note: You can also deploy the database component programmatically by using the LiveCycle ES API. For information, see the LiveCycle ES SDK Help.

To deploy the database component:

  1. Start LiveCycle Workbench ES.
  2. Log in to LiveCycle Workbench ES.
  3. Select Window > Show Views > Components. This action adds the Components view to LiveCycle Workbench ES.
  4. Right-click the Components icon and select Install Component.
  5. Select the adobe-dbSample-dsc.jar file through the file browser and click Open.
  6. Select Service Descriptors, and then right-click DatabaseComponent and select Activate Service.
  7. Right-click DatabaseComponent and select Start Component. A green arrow appears next to the name if it succeeds. Notice that DatabaseComponent is automatically deployed and has a green arrow next to it if it succeeds.

Testing your component

After you deploy the database component to the LiveCycle ES software, you can create a new process that uses it. Likewise, you can programmatically invoke its operations. Although this section does not explain all the concepts involved in creating a process, it provides the basic concepts that let you create a simple process that uses the e-mail component. For information about creating a process, see Creating your first LiveCycle ES application.

When you drag the database component onto the process editor, you can specify input values, during design time, that are required by the component. The following illustration shows the property editor that lets you specify the input values.

Notice that these input values correspond to the parameters that belong to the UpdateApproveTable method that is defined in the DatabaseComponent interface. Each input value is defined as an XPATH expression that retrieves the value of the form field. The form is used in the process that is created in Creating your first LiveCycle ES application.

This database component enables a process author to update a database table without specifying SQL commands or having other database knowledge. Even the primary key value is hidden from the process author (the primary key is generated by the database component and is hidden from the process author).

Where to go from here

For more information about creating components for the LiveCycle ES software, see the LiveCycle ES SDK Help on the Adobe LiveCycle ES Documentation page.