Developing Adapters

Creating a Custom Development Environment

Warning: We strongly recommend that you do not alter the sample adapter directly. Instead, use the GenerateAdapterTemplate utility described in this chapter to make a copy of the adapter, and then make any changes you want to your copy. Modifying the sample adapter itself (or trying to create a copy of it without using GenerateAdapterTemplate) might result in unexpected and unsupported behavior.

To facilitate the use of the sample adapter (see Sample Adapter), the ADK provides GenerateAdapterTemplate, a command-line utility you can use to create a new adapter development tree by cloning the sample tree.

This section provides information about the following subjects:

Adapter Setup Worksheet

The adapter setup worksheet is a questionnaire designed to help you identify and collect critical information about the adapter you are developing. You can find this questionnaire in Adapter Setup Worksheet.

This worksheet is a set of 20 questions that can help you identify critical adapter information, such as EIS type, vendor, and version, locale and national language of the deployment, the adapter logical name, and whether or not the adapter supports services. When you run GenerateAdapterTemplate, you are prompted to enter this information. When the information is processed, a custom development tree for your adapter is created.

Using GenerateAdapterTemplate

This section explains how to use GenerateAdapterTemplate. You must perform the following steps:

Step 1. Execute GenerateAdapterTemplate

To use this tool, do the following:

Open a command line from the WLI_HOME/adapters/utils directory and execute one the following commands:

For Windows NT: GenerateAdapterTemplate.cmd
For UNIX: GenerateAdapterTemplate.sh

The system responds:

***************************************************************
Welcome! This program helps you generate a new adapter development tree by cloning the ADK's sample adapter development tree.
Do you wish to continue? (yes or no); default='yes':
For Windows systems, proceed to step 2. After completing step 2, the system displays the prompt shown in step 3.
For non-Windows systems, proceed to step 3.

Select yes by pressing Enter. For Windows systems only, select your console's codepage value from the following codepage list:

Cp437 - United States
Cp850 - Multilingual (Latin I)
Cp852 - Slavic (Latin II)
Cp855 - Cyrillic (Russian)
Cp857 - Turkish
Cp860 - Portuguese
Cp861 - Icelandic
Cp863 - Canadian-French
Cp865 - Nordic
Cp866 - Russian
Cp869 - Modern Greek
MS932 - Japanese
Enter your console's codepage; default='Cp437':

If you do not know your codepage, launch a new DOS console prompt and enter chcp at your console prompt. Depending on the Windows version, this command displays your console's codepage value.

Select yes by pressing Enter.

The system responds: Please choose a name for the root directory of your adapter development tree (NOTE: this directory will be created under WLI_HOME/adapters):

Enter a unique, easy-to-remember directory name (dir_name) and press Enter.

The system responds: created directory WLI_HOME/adapters/dir_name Enter the EIS type for your adapter:
In the pathname specified in the system output, dir_name is the name of the new directory.

Note: If you enter the name of an existing directory, the system responds:

WLI_HOME/adapters/dir_namealready exists, please choose a new directory that does not already exist!
Please choose a name for the root directory of your adapter development tree:

Enter an identifier for the EIS type to which your adapter will connect. Press Enter.

The system responds: Enter a short description for your adapter:

Enter a short, meaningful description of the adapter you are about to develop and press Enter.

The system responds: Enter the major version number for your adapter; default='1':

Either press Enter to accept the default, or enter the appropriate version number and then press Enter.

The system responds: Enter the minor version number for your adapter; default='0':

Either press Enter to accept the default, or type the appropriate minor version number and then press Enter.

The system responds: Enter the vendor name for your adapter:

Enter the vendor's name and press Enter.

The system responds: Enter an adapter logical name; default='default_name':

Either press Enter to accept the default or type the adapter logical name you want to use. Press Enter. The default adapter logical name (`default_name') is based on the format recommended for WebLogic Integration:
vendor name_EIS-type_version-number.

The system responds: Enter the Java package base name for your adapter (e.g. sample adapter's is sample): Java package base name

Enter the base name of the Java package, in package format, and press Enter. A name in package format consists of the following strings, separated by dots:

The extension used in the URL for your organization's Web site (such as .com, .org, or.edu)
The name of your company
Additional adapter identifiers. For example: com.your_co.adapter.EIS.

The system responds: The following information will be used to generate your new adapter development environment: EIS Type = 'SAP R/3' Description = 'description' Major Version = '1' Minor Version = '0' Vendor = 'vendor_name' Adapter Logical Name = 'adapter_logical_name' Java Package Base = 'com.java.package.base' Are you satisfied with these values? (enter yes or no or q to quit); default='yes':

To confirm the information, press Enter.

The system responds by displaying the appropriate build information.

Note: If you enter no, you are routed back to step 4. If you enter q (quit), the application terminates.

Step 2. Rebuild the Tree

After completing the clone process, go to the new directory and use Ant, the ADK's build tool, to rebuild the entire tree. For more information about Ant, see Ant-Based Build Process.

Note: You must explicitly enter the file extension when running Ant commands on UNIX systems. For example, enter ant.sh release. Entering ant release on UNIX systems does not locate ant.sh.

To rebuild the tree by using Ant, do the following:

Edit antEnv.cmd (Windows) or antEnv.sh (UNIX) in WLI_HOME/adapters/ADAPTER/utils.

Set the following variables to valid paths:

BEA_HOME - The top-level directory for your BEA products, such as c:/bea.
WLI_HOME - The location of your WebLogic Integration directory.
WL_HOME - The location of your WebLogic Server directory.
JAVA_HOME - The location of your Java Development Kit.
ANT_HOME - The location of your Ant directory, typically WLI_HOME/adapters/utils.

Note: The installer performs this step for you, but you should be aware that these settings control the Ant process.

On a UNIX system, execute permission for all must be set for the Ant file in WLI_HOME/adapters/utils. To add execute permission, enter the following command:chmod u+x ant.sh

Execute antEnv.cmd (Windows) or antEnv.sh (UNIX) from the command line to set the necessary environment variables for your shell.

Execute ant.cmd release (Windows) or ant.sh release (UNIX) from the WLI_HOME/adapters/ADAPTER/project directory to build the adapter. (Replace ADAPTER with the name of the new adapter development root.)

When you execute ant release, Javadoc is generated for the adapter. You can view the Javadoc by going to:
WLI_HOME/adapters/ADAPTER/docs/overview.html
This file provides environment-specific instructions for deploying your adapter in a WebLogic Integration environment. Specifically, it provides config.xml entries and replacements for the path already created. In addition, the file provides mapping information.
To facilitate adapter deployment, as described in Step 4. Deploy the Adapter to WebLogic Integration, you can copy the contents of overview.html directly into config.xml.

Step 3. Test the Adapter

Before deploying the adapter, you should test the behavior of the adapter. Create a service and an event and test them. You can use the steps described in Learning to Develop Adapters Using the DBMS Sample Adapters as a guide to using the adapter. Once testing is successfully complete, you are ready to customize the cloned adapter to meet the needs of the EIS.

Step 4. Deploy the Adapter to WebLogic Integration

You can deploy the adapter either manually or from the WebLogic Server Administration Console. See Deploying Adapters, for complete information.