Creating a Component using the Component Development Tool

You can use the component development tool to create a LiveCycle component. The component development tool makes component development more efficient by creating the following component assets:

  • A component.xml file

  • Service interfaces and classes

  • An Ant build that create a JAR file that represents your component

The component development tool provides a wizard that creates a LiveCycle component from scratch, or from an existing component Java project. The tool lets you toggle between the XML view of your component and a graphical view of all its services and operations. The component development tool consists of the following views:

  • Overview

  • Services and Operations

  • Data Types

  • Runtime

  • component.xml

Note: The component that is shown in the following illustrations is the e-mail component created in another section. (See Creating Your First Component.)

Overview view

The Overview view provides information about the component such as the component identifier value, its version number, the Bootstrap class, and the Lifecycle class. The following illustration displays the Overview view.

Services and Operations view

The Services and Operation view provides service details such as the service name, the implementation class, and the configuration parameters. You can also specify whether to auto deploy the service and whether you can use the component within a Workbench ES process. The Orchestratable option controls whether the component can be used within a process. By selecting this option, the component can be used within a process. The following illustration displays the service view. You can view the service view by selecting the service name in the left panel. (Notice that EmailService2 is selected.)

In the previous illustration, notice that the EmailService2 service was selected. If you click the operation below a service, you are able to view operation details. The operation view provides details such as operation name, the hint value (shows up in Workbench as a hint), input parameters, and output parameters. The following illustration displays the operations view. (Notice that the send operation is selected.)

In the previous illustration, notice that all of the input parameters for the e-mail component are listed. Using this view, you can also remove and add input or output parameters.

Note: This view is also available to edit existing input and output parameters by clicking the Properties... button.

Data Types view

The Data Types view lets you specify new data types on which the component depends. For example, if you have to add a new Java class that represents the data type, you can use this view.

Runtime view

The Runtime view lets you import and export packages as well as specify required JAR files to add to your classpath. For example, the e-mail component is dependant upon the mailapi.jar file. The following illustration shows the Runtime view.

Component xml view

The component XML view provides an XML view of the component XML file. If you prefer working in XML as opposed to a GUI, you can work in this view.

Summary of Steps

To demonstrate how to use the component development tool to create a LiveCycle component, the e-mail component developed in Creating your first component is created. However, the difference between this section and Creating your first component is that the component development tool is used in this section. (See Creating Your First Component.)

To develop the e-mail component using the component development tool, perform the following steps:

  1. Install the component development tool.

  2. Create a component project using the component wizard.

  3. Create your application logic for the LiveCycle component.

  4. Add external JAR files to the component classpath by using the Runtime view.

  5. Package the LiveCycle component by using the Ant script.

After you deploy a component to LiveCycle, you can use it to create a process using Workbench. You can also 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 Service container. (See .)

Install the component development tool

To use the component development tool to create a LiveCycle component, install the development tool. The component development tool is an Eclipse plug-in. Ensure that you use Eclipse version 3.4.2 or higher and Java JDK version 1.6. Before using this tool with Eclipse, install and configure the following frameworks in your Eclipse environment.

  • The Eclipse Modeling Framework Project (EMF) version 2.4.2 in your Eclipse environment.

  • The Eclipse Graphical Editing Framework (GEF) version 3.4.2 in your Eclipse environment.

  • The Web Tools Platform (WTP SDK) into your Eclipse environment.

Configure the Eclipse Modeling Framework

Install the Eclipse Modeling Framework project in your Eclipse environment by performing the following tasks:

  1. Click Help, Software Updates, Available Software tab, Add Site.

  2. Add the update site http://download.eclipse.org/modeling/emf/updates/releases.

  3. Select the 2.4.2 version of the EMF libraries from the list.

  4. Click on Install.

  5. Click Next, Select "I accept the terms..." and Finish. This installs the EMF libraries into your existing eclipse and prompts you to restart Eclipse. Ensure that you select Yes.

Configure the Eclipse Graphical Editing Framework

Install the Eclipse Graphical Editing Framework by performing the following tasks:

  1. Click Help, Software Updates, Available Software tab, Add Site.

  2. Add the update site http://download.eclipse.org/tools/gef/updates/releases/.

  3. Choose version 3.4.2 and click Install.

  4. Click Next, Select "I accept the terms..." and Finish. This installs the EMF libraries into Eclipse and prompts you to restart Eclipse. Ensure that you select Yes.

Configure the Eclipse Web Tools Platform

Configure the Eclipse Web Tools Platform (WTP SDK):

  1. Using your Browser, open the Eclipse Web Tools Platform Project download site at http://archive.eclipse.org/webtools/downloads/drops/R3.0/R-3.0.5-20090521045405/.

  2. Under "Web Tools Platform", locate the link for "wtp-sdk" and download the file, "wtp-sdk-R-3.0.5-20090521045405.zip."

  3. Exit Eclipse.

  4. The file wtp-sdk-R-3.0.5-20090521045405.zip contains updates to the "features" and "plug-ins" folder in your Eclipse installation. Unzip the file in the same root folder where you have already installed Eclipse (typically the folder that contains your "eclipse" folder).

  5. Restart Eclipse after you finish unzipping.

Setting up the component development tool

After you install and configure the required frameworks in your Eclipse environment, set up the component development tool by performing the following tasks:

  1. Retrieve the adobe-tools.zip file from the following location: <Workbench_Install_Directory>\sdk\tools.

  2. In Eclipse, click Help, Software Updates.

  3. Select the Available Software Tab.

  4. Select Add Site.

  5. Select Archive.

  6. Browse and open the component development tool file in your download folder (from step 1).

  7. Select OK.

  8. Click Install.

  9. Accept the license agreement and click Finish.

  10. Restart Eclipse.

Create a component project using the component wizard

After you install the component development tool, you can create a component project in Eclipse. When you create a project, a wizard prompts you for the service name, the Java package, the component identifier value, and so on. The following illustration shows the component wizard.

The project includes files such as the component.xml file, Java source files (class and interface files), and an Ant build script named build.xml. The Java source files are placed in a Java package that corresponds to the Java package specified in the component wizard. For example, in the previous illustration, com.adobe.sample is specified. The name of the Java interface corresponds to the service name. The Java interface also contains methods that correspond to operations that you specify in the wizard.

Note: When you create a LiveCycle component without the assistance of the component development tool, you manually create the required files. In contrast, when using the component development tool, the files are created. However, you add Java application logic to the service method(s) in the implementation class.

The following illustration shows the project files after you create the project using the component tool. The name of the service specified in the wizard is EmailService5.

Note: To view the different views of the component development tool, such as the Overview, select the component XML file in your Eclipse project.

Create a component development tool project for the e-mail component by performing the following tasks:

  1. Start Eclipse.

  2. Select File, New, Other, Adobe LiveCycle, Component Project.

  3. In the Java Project Name field, specify a name for your project.

  4. If desired, change the package name. By default, the package is named com.adobe.sample.

  5. Click Add to create a service for the component.

  6. In the Create a new Service dialog box, specify a service name. For example, specify EmailService5. (EmailService5 was used because if you followed the instructions specified in Developing your first component, you will have a service named EmailService.)

  7. In the Category field, specify a category name.

  8. If desired, select an icon for the service.

  9. Click Add to create an operation for the service. For example, specify SendMail.

  10. In the Define the Service Operations dialog box, click Add to add a parameter. Modify the parameter name, the data type, and title to meet your business requirements. Repeat this step for each parameter to add. The parameter that you specify is automatically added to the Java source files and the component XML file. The Title column lets you specify a value that is displayed in Workbench. Add the following parameter values for SendMail (these values become parameters for the SendMail method that is located in the implementaion class):

    • ToAddress: A string value that represents to e-mail addresses to where the e-mail message is sent.

    • CCAddress: A string value that specifies the e-mail recipient who receives a copy of the e-mail message.

    • BCCAddress: A string value that specifies the hidden e-mail recipient who receives a copy of the e-mail message.

    • Subject: A string value that specifies the subject of the e-mail message.

    • MimeType: A string value that specifies the MIME type of the file attachment.

    • Message: A string value that specifies the e-mail body of the e-mail message.

    • AttachmentName: A string value that specifies the name of the file attachment.

    • docAttachment: A com.adobe.idp.Document value that specifies the file attachment that is sent with the e-mail message.

    Note: The Define the "Returned output data type" dropdown lets you specify the data type for the operation’s return value. By default, this dropdown is empty. If you leave this dropdown empty, then the method’s return value is void. That is, the method does not have a return value. Likewise, if you select a data type, such as String, the return value’s data type corresponds to the value that you select. For the SendMail operation, leave the dropdown empty.
  11. When done entering parameter values, click OK.

  12. In the Create a new Service dialog box, click Configuration Parameters to add the required configuration values.

  13. In the Service Configuration Definitions dialog box, click Add for each configuration value to add. Specify a name, the data type, and the default value. When you add a configuration value, it is automatically added to the component XML file. For this example, add the following three configuration values that the e-mail message component requires:

    • smtpHost: A string value that specifies the IP address of the SMTP server that sends e-mail messages.

    • smtpUser: A string value that specifies the user name that is used to connect to the SMTP server.

    • smtpPassword: A string value that specifies the corresponding password of the user.

  14. Click OK.

  15. Click Finish to create your component project.

Note: After you create a project using the component development wizard, you can change project values such as a parameter value, or a configuration parameter by using the component development tool views. For example, you can modify a parameter value in the operations view.

Create your application logic for the LiveCycle component

Create Java application logic for the component. Ensure that you add JAR files on which your application logic is dependent to your Eclipse project’s classpath. To create an e-mail component (the example e-mail component), add the following JAR files to your project’s class path:

  • mailapi.jar

  • activation.jar

Both of these JAR files are available with JavaMail API at http://java.sun.com/products/javamail/.

Because the component’s application logic uses a com.adobe.idp.Document object, add the adobe-livecycle-client.jar file to your project’s class path. For information about the location of this JAR file, see Including LiveCycle Java library files.

Add the following Java application logic to the implementation of the EmailService5Impl class.

package com.adobe.sample; 
 
import java.util.Properties; 
 
import javax.activation.DataHandler; 
import javax.activation.FileDataSource; 
import javax.mail.BodyPart; 
import javax.mail.Message; 
import javax.mail.Multipart; 
import javax.mail.Session; 
import javax.mail.Transport; 
import javax.mail.internet.InternetAddress; 
import javax.mail.internet.MimeBodyPart; 
import javax.mail.internet.MimeMessage; 
import javax.mail.internet.MimeMultipart; 
import com.adobe.idp.Document; 
 
public class EmailService5Impl implements EmailService5{ 
 
protected java.lang.String smtpHost; 
protected java.lang.String smtpUser; 
protected java.lang.String smtpPassword; 
 
public void setsmtpHost(java.lang.String smtpHost){ 
this.smtpHost=smtpHost; 
} 
public java.lang.String getsmtpHost(){ 
return this.smtpHost; 
} 
public void setsmtpUser(java.lang.String smtpUser){ 
this.smtpUser=smtpUser; 
} 
public java.lang.String getsmtpUser(){ 
return this.smtpUser; 
} 
public void setsmtpPassword(java.lang.String smtpPassword){ 
this.smtpPassword=smtpPassword; 
} 
public java.lang.String getsmtpPassword(){ 
return this.smtpPassword; 
} 
public void SendMail(java.lang.String ToAddress, 
        java.lang.String CCAddress, 
        java.lang.String BCCAddress, 
        java.lang.String Subject, 
        java.lang.String MimeType, 
        java.lang.String Message, 
        java.lang.String AttachmentName, 
        com.adobe.idp.Document docAttachment){ 
     
 
    try { 
          
        Properties _props = new Properties(); 
        if (getsmtpHost() != null) { 
           _props.put("mail.smtp.host", getsmtpHost()); 
          } 
         
        if (getsmtpUser() != null) { 
           _props.put("mail.smtp.user", getsmtpUser()); 
          } 
         
        // Setup mail server if authentication used 
        if (!(isEmpty(smtpHost) || !(isEmpty(smtpPassword))))  
          { 
            _props.put("mail.smtp.auth", "true"); 
          } 
 
        //Get the default Session and add the new properties to it. 
         Session _session = Session.getInstance(_props, null); 
     
        //Create a message 
        MimeMessage _msg = new MimeMessage(_session); 
 
        //Set the sent from address 
        InternetAddress fromIntenetAddress = new InternetAddress(getsmtpUser()); 
        _msg.setFrom(fromIntenetAddress); 
 
        InternetAddress[] toInternetAddresses =   InternetAddress.parse(ToAddress); 
        _msg.setRecipients(Message.RecipientType.TO, toInternetAddresses); 
         
        if (!isEmpty(CCAddress)) { 
            InternetAddress[] toCCInternetAddresses = InternetAddress.parse(CCAddress); 
            _msg.setRecipients(Message.RecipientType.CC,toCCInternetAddresses); 
           } 
 
        if (!isEmpty(BCCAddress)) { 
          InternetAddress[] toBCCInternetAddresses = InternetAddress.parse(BCCAddress); 
          _msg.setRecipients(Message.RecipientType.BCC,toBCCInternetAddresses); 
           } 
 
        if (!isEmpty(Subject)) { 
           _msg.setSubject(Subject); 
         } 
 
        if (!isEmpty(aMessage)) { 
          if (!isEmpty(MimeType)) { 
               _msg.setContent(aMessage, MimeType); 
         } else { 
               _msg.setText(aMessage); 
          } 
         } 
 
        Multipart multipart = new MimeMultipart(); 
        BodyPart messageBodyPart = new MimeBodyPart(); 
     
       if (docAttachment != null){ 
          BodyPart _bodyPartAttachment = new MimeBodyPart(); 
          FileDataSource fileSource =  new FileDataSource(docAttachment.getFile()); 
          _bodyPartAttachment.setDataHandler( new DataHandler(fileSource)); 
         
          if (!isEmpty(aAttachmentName)){ 
              _bodyPartAttachment.setFileName(aAttachmentName.trim()); 
          } else { 
              _bodyPartAttachment.setFileName("attachment.pdf");    
          } 
 
      multipart.addBodyPart(_bodyPartAttachment); 
     _msg.setContent(multipart); 
       } 
     
      //Send the email message 
     _msg.saveChanges(); // implicit with send() 
     messageBodyPart.setContent(aMessage, "text/html; charset=utf-8"); 
     multipart.addBodyPart(messageBodyPart); 
     
     //Set the sent date for the email 
     _msg.setSentDate(new java.util.Date()); 
     
     //Send the message 
     Transport _transport =_session.getTransport("smtp"); 
     _transport.connect(getsmtpHost(), getsmtpUser(), getsmtpPassword()); 
     _transport.sendMessage(_msg, _msg.getAllRecipients()); 
 
    }catch (Exception e) { 
        e.printStackTrace(); 
    } 
 
} 
 
 
//check If passed in string contains only non whitespace 
public static boolean isEmpty(String aValue) { 
       return (aValue == null || aValue.trim().length() == 0); 
} 
}

Add external JAR files to the component classpath by using the Runtime view

If your component depends on third-party JAR files, ensure that you include them to the component’s classpath by using the Runtime view. Before you can add JAR files to the component’s classpath by using the Runtime view, import them into the following Eclipse project folder:

lib/internal 

Because the e-mail component depends on the mailapi.jar and activation.jar files, import these JAR files into the Eclipse project folder. After you import the JAR files, you can add them to your component’s classpath by using the Runtime view. Once you successfully add a JAR file to your component’s classpath, the class-path element in the component XML file is automatically updated. That is, you do not have to manually update the class-path element in the component XML file. For example, after you add the mailapi.jar and activation.jar files, the following XML element is part of your component XML file.

<class-path> 
        lib/internal/activation.jar lib/internal/mailapi.jar 
</class-path>

In addition, the JAR files are displayed in the Runtime view.

To add JAR files to the component’s classpath by using the Runtime view, perform the following tasks:

  1. Within your Eclipse project, select the component XML file.

  2. Select the Runtime tab that is located near the bottom of your development environment.

  3. Click the Add button.

  4. In the JAR selection dialog box, select the JAR files located in the lib/internal folder.

  5. Click OK.

Package the LiveCycle component by using the Ant script

You can package a LiveCycle component into a JAR file by using the ANT script that is available with your Java component project. By default, the filename of the Ant script is build.xml and it is located in the project root. You can run the Ant script from your Eclipse environment.

Before running the Ant script, check the build.properties settings to ensure that your environment is set correctly. You can modify the build.properties by using its build view or the build.properties view. The build.properties view represents the source code, as shown in the following example.

install.dir ./lib 
src.dir ./src 
lib.dir ./lib 
classes.dir ./classes 
deploy.dir    ./deploy 
bin.includes = src/ 
src.includes = src/

The build view is a graphical view of the build properties, as shown in the following illustration.

Using this view, you can specify the files to include in the component JAR file, such the component XML file, the source files, and so on. After you set the build properties, run the Ant script from your Eclipse project. This script produces the JAR file that represents your LiveCycle component. The Ant script logs messages to the Console view while it is generating the component JAR file. The Console view specifies the location of the component JAR file after a successful build occurs, as shown in the following illustration. Notice that the path where the component JAR file exists is highlighted.

Note: By default, the directory where the component JAR is placed is specified in the build.properties deploy directory.

To package the LiveCycle component by using the Ant script, perform the following tasks:

  1. In your Package Explorer, select build.properties.

  2. Select the Build tab located at the bottom of the Build Configuration view.

  3. Modify the build properties to meet your business requirements. Ensure that the required files such as the component XML file and the class files located in the bin folder are selected.

  4. In your Package Explorer, select the build.xml file.

  5. Right click and select Run As, Ant Build.

Deploy the component

After the Ant script builds the component JAR file, you deploy it to LiveCycle using Workbench. (See Deploying your component.)

Testing the component

After you deploy your LiveCycle component, you can test it. (See Testing your component.)

// Ethnio survey code removed