Using the Data Integration Plug-In

This section provides information about the following topics:

• Data Translation with the Data Integration Plug-In

• Processing Event Data

• Enhancing Data Translation Performance

• Custom Data Types and the Data Integration Plug-In

• Support for WebLogic Server Clustering

 

---

Data Translation with the Data Integration Plug-In

The data integration plug-in provides capabilities for translating nonXML documents into XML, and vice versa, while executing business process management (BPM) functions. To perform such a translation, complete the following procedure:

1. Start the WebLogic Integration Studio. For instructions on starting and logging on to the Studio, see Using the Studio Interface in Using the WebLogic Integration Studio.

2. Open the desired template definition and double-click a task. The Task Properties dialog box is displayed (Figure  2-1).

   Figure 2-1 Task Properties Dialog Box

   
    

3. If the selected task contains the data translation action, select it again from the list, click Update, and proceed to step 4. Otherwise, click Add to add a new action. The Add Action dialog box is displayed (Figure  2-2).

   Figure 2-2 Add Action Dialog Box

   
    

4. Expand the Integration Actions node; a list of actions is displayed. Expand the Data Integration item in that list. A two-item list of translation actions is displayed: Translate XML to Binary and Translate Binary to XML. Select the type of translation you want to perform.

Translate XML to Binary

To perform an XML-to-binary translation:

1. From the Add Action dialog box (Figure  2-2), select Translate XML to Binary. The Translate XML to Binary dialog box is displayed (Figure  2-3).

   Figure 2-3 Translate XML to Binary Dialog Box

   
    

2. Enter data in the fields, as described in the following table.

   Table 2-1 Translate XML to Binary Dialog Box Fields

   Dialog Box Area	Field	Description
   Message Format Parameters	Name	Name of the message format. You can type a name directly in the text field or click Browse to invoke a list of repository documents from which you can make a selection.
   	Description	Displays the description of the message format. Note: This field is used only for displaying text. You cannot edit text in this field.
   	Notes	Displays the notes attached to the message format. Note: This field is used only for displaying text. You cannot edit text in this field.
   Message Format Action Buttons	Browse	Allows you to browse MFL documents in the repository.
   	View	Displays the items in the Message Format area so you can verify that you have selected the correct document type for translation.
   	Debug	Enables or disables debug messaging. When you select this option, the translation actions are written to the WebLogic Server log file.
   Variable Parameters	Input XML Variable	Displays the XML workflow variables. Select the variable you want to use in the translation, or create a new variable as follows: 1. Type a name for your new variable and click OK. A confirmation message box is displayed. 2. Click Yes to create the new variable.
   	Assign Result To	Displays the binary data workflow variables. Select the variable in which you want to store the translated information or create a new variable as follows: 1. Type a name for your new variable and click OK. 2. Click Yes to create the new variable.

   
    

3. Click OK to save the translation information to your workflow.

Translate Binary to XML

To perform a binary-to-XML translation:

1. In the Add Action dialog box (Figure  2-2), choose Integration Actions—>Data Integration—>Translate Binary to XML. The Translate Binary to XML dialog box is displayed (Figure  2-4).

   Figure 2-4 Translate Binary to XML Dialog Box

   
    

2. Enter data in the fields, as described in the following table.

   Table 2-2 Binary to XML Dialog Box Fields

   Dialog Box Area	Field	Description
   Message Format Parameters	Name	Name of the message format. You can type a name directly in the text field, or click Browse to invoke a list of repository documents from which you can make a selection.
   	Description	Displays the description of the message format. Note: This field is used only for displaying text. You cannot edit text in this field.
   	Notes	Displays the notes attached to the message format. Note: This field is used only for displaying text. You cannot edit text in this field.
   Message Format Action Buttons	Browse	Allows you to browse MFL documents in the repository.
   	View	Displays the items in the Message Format area so you can verify that you have selected the correct document type for translation.
   	Debug	Enables or disables debug messaging. When you select this option, the translation actions are written to the WebLogic Server log file.
   Variable Parameters	Input Binary Variable	Displays the binary workflow variables. Select the variable you want to use in the translation, or create a new variable as follows: 1. Type a name for your new variable and click OK. A confirmation message box displays. 2. Click Yes to create the new variable.
   	Assign Result To	Displays the XML data workflow variables. Select the variable you want to use to store the translated information, or create a new variable as follows: 1. Type a name for your new variable and click OK. 2. Click Yes to create the new variable.

   
    

3. Click OK to save the translation information to your workflow.

 

---

Processing Event Data

The data integration plug-in provides a function that enables binary data to trigger workflows by converting the binary data to XML or by preprocessing it at the front end of event processing. This function is referred to as the event handler. The event handler is executed when JMS messages are published to a topic.

Three JMS properties are required for a message to be preprocessed by the data integration plug-in:

• WLPIContentType: "binary/x-application/wlxt"

• WLPIPlugin: "com.bea.wlxt.WLXTPlugin"

• WLPIEventDescriptor: MFL_document_name

The first two JMS message properties are constant for all messages addressed to the event handler. The third property contains the name of the MFL document that describes the binary data in the message.

Note: The MFL document referenced in the WLPI EventDescriptor must be stored in the repository.

Listing  2-1 is a sample of code used to build a message that can be processed by the event handler.

Listing 2-1 Sample Event Handler Code

byte[] bindata = ... the binary data ...
pub = sess.createPublisher(topic);
BytesMessage msg = sess.createBytesMessage();
msg.writeBytes(bindata);
msg.setStringProperty("WLPIPlugin", "com.bea.wlxt.WLXTPlugin");
msg.setStringProperty("WLPIContentType",
 "binary/x-application/wlxt");
msg.setStringProperty("WLPIEventDescriptor", "mymfldoc");
pub.publish(msg);

The servlet sample application shows how the message built by this code is processed by the event handler. See Running the Servlet Sample for information about running the servlet sample.

 

---

Enhancing Data Translation Performance

The data integration plug-in provides a configuration panel for monitoring and administering in-memory cache of the MFL document and for enabling or disabling event handler debugging. Using this panel, you can adjust the in-memory cache and translation object pool to enhance the performance of your data translations.

Note: You must clear the MFL document in-memory cache in order for any updates you make to an MFL document to take effect.

To access the configuration panel, follow the steps below. For more information about the actions specific to business process management, refer to the business process management documentation.

1. Start the WebLogic Integration Studio. For instructions on starting and logging on to the Studio, see Using the Studio Interface in Using the WebLogic Integration Studio.

2. Choose Configuration—>Plugins. The Plugin Configuration dialog box is displayed (Figure  2-5).

   Figure 2-5 Plug-In Configuration Dialog Box

   
    

3. Select the Data Integration Plug-In and click Update. The Configuration dialog box for the data integration plug-in is displayed (Figure  2-6).

   Figure 2-6 Configuration Dialog Box for the Data Integration Plug-In

   
    

4. To monitor and enhance translation performance, enter data in the fields described in the following table.

   Dialog Box Area	Field	Description
   Start Mode	Automatic	Opens the data integration plug-in automatically when the Studio is opened.
   	Manual	Makes the data integration plug-in available from the Studio.
   	Disabled	Disables the use of the data integration plug-in from the Studio.
   Data Integration Object Pool	Preferred Pool Size	Defines the maximum number of permanent objects in the pool. Use the slider to set the pool size to the desired number. Note: The translation engine creates temporary pool objects if the demand exceeds the preferred pool size you have set. These objects are deleted when they are returned to the pool.
   	Current Size	Displays the number of objects currently in the pool.
   	High Water Mark	Displays the largest number of objects in the pool since the server was started.
   MFL Cache	MFL Requests	Displays the total number of requests for translation of MFL documents.
   	Cache Hits	Displays the number of requests made while the necessary MFL document was already in the cache.
   	Hit Ratio	Displays the percentage of requests satisfied by retrieving MFL documents from the cache, rather than from the database.
   MFL Cache Action Buttons	Refresh	Sends a request to the server to update the MFL cache statistics.
   	Clear	Clears the MFL document cache. For all subsequent translation requests, MFL documents must be loaded from the repository.
   Event Handler Options	Enable Debug Messaging	Enables or disables debug messaging for the event handler. If enabled, debug messages are written to the WebLogic Server log file during translation.

The data integration plug-in extends the capabilities for displaying and editing provided by standard BPM functionality. These capabilities are provided by the Hex Editor component of Format Tester for displaying and editing binary data.

 

---

Variable Types and the Data Integration Plug-In

The data integration plug-in provides a BinaryData variable type that you can use to edit and display binary data. The BinaryData variable acts as a container for a logical set of binary data with additional display capabilities. This variable is used by programs that call the actions provided by the data integration plug-in to pass and receive binary data. It is also used by the Workflow Instance Monitor to display and edit the contents of a binary variable.

 

---

Custom Data Types and the Data Integration Plug-In

WebLogic Integration provides a user-defined type feature that allows you to create custom data types that accommodate your unique data type requirements. The user-defined type feature allows these custom data types to be plugged in to the data integration run-time engine. Once a user-defined data type is plugged in, it is indistinguishable from a built-in data type, in terms of both features and functionality.

 

---

Configuring User-Defined Data Types

User-defined types used by the data integration plug-in are stored in the WebLogic Integration repository as CLASS documents. At run time, the data integration plug-in loads user-defined type classes from the repository as required. In addition, the data integration plug-in exports the MFL and class files required to support the active template, allowing a template to be imported, intact, on another business process management instance. Class documents may be placed in the repository using either of two methods. The following sections describe those methods:

• Using the Format Builder

• Using the Repository Import Utility

Using the Format Builder

To publish a user-defined type to the repository using the Format Builder, complete the following procedure:

1. Start the Format Builder by choosing Start—>Programs—>BEA WebLogic Platform 7.0—>WebLogic Integration 7.0—>Format Builder. The Format Builder main window is displayed.

2. Choose Repository—>Log In. The WebLogic Integration Repository Login window is displayed.

   
    

3. Enter the user ID specified for the server users in the User Name field.

4. Enter the password specified for the server users in the Password field.

   Note: For default users and passwords, see "WebLogic Integration Users and Passwords" in Getting Started in Starting, Stopping, and Customizing BEA WebLogic Integration.

5. Enter the name of the server and the number of the associated port in the Server[:port] field.

   Note: The WebLogic Integration Repository Login window allows you to make up to three login attempts. If you are unsuccessful after three attempts, a login failure message is displayed. If you fail to log in three times, choose Repository—>Log In to repeat the login procedure.

6. Click Connect. If your login attempt is successful, the Login window is closed and the Format Builder Title bar displays the server name and port number entered in the WebLogic Integration Repository Login window. A menu of active repository items is displayed. Select the one you want to access.

7. Choose Tools—>User Defined Types. The Add/Remove User Defined Types dialog box is displayed.

   
    

   Once a connection to the repository is established, the Add/Remove User Defined Types dialog box displays the status of each registered user-defined type and allows for the publication of each such type to the repository. The status of each user-defined type in the repository is indicated by an icon, in the form of a ball, before each entry in the Installed Types area of the dialog box.

   The color of the icon before each name of a user-defined type indicates the status of that type:

   • Green—The user-defined type has been published to the repository.

   • Yellow—The user-defined type has been published to the repository, but the local version of the class differs from the repository version.

   • Red—The user-defined type does not exist in the repository.

8. From the list of installed types, select the class you want to publish and click Publish. The icon for the selected entry should become green, indicating that the class was successfully placed in the repository.

Using the Repository Import Utility

To use the repository import utility to import Java class files (including user-defined types), complete the following procedure:

1. Create a wlxt-repository.properties file in the CLASSPATH. The content of this file should be as follows:

   wlxt.repository.url=server_URL

   For example:

   wlxt.repository.url=t3://localhost:7001

2. Type the following command to pass the class filename on the Import command line:

   java com.bea.wlxt.repository.Import filename

   For example, the following command imports all the class files in the current directory:

   java com.bea.wlxt.repository.Import *.class

Note: Any Java class file may be imported into the repository using the repository import utility, as well as User Defined Types. This capability is useful if a user-defined type relies on additional class files that do not extend the com.bea.wlxt.bintype.Bintype class.

 

---

Support for WebLogic Server Clustering

The data integration plug-in can operate successfully in a clustered WebLogic Server environment. In a clustered environment, the plug-in administrator is connected to only one node of the cluster at any given time. Any commands issued by the administrator must be propagated to the other nodes in the cluster.

Communication among the various servers in a cluster is handled through a JMS topic. The topic is used for communication to different nodes in a cluster in a WebLogic Integration environment.

Configuring the Data Integration Plug-In for Clustering

If you want to take advantage of the clustering capability, you must configure the data integration plug-in as follows:

1. Create a JMS topic on one of the servers in the cluster. The JNDI name of this topic must be as follows:

   com.bea.wlxt.cluster.BroadcastTopic

   Note: For more information about creating JMS topics, see the WebLogic Server documentation.

2. Open the config.xml file in a text editor. This file can be found in the SAMPLES_HOME\integration\config\samples\ directory. (In this pathname, SAMPLES_HOME represents the directory of your WebLogic Platform installation in which your samples are installed.)

   Note: The config directory contains separate subdirectories for each domain you have created. Each subdirectory contains its own config.xml file. Make sure you open the correct file.

3. Locate the <Application> section for business process management and add the following lines anywhere in this section:

   <EJBComponent Name="wlxt-cluster"
    DeploymentOrder="99"
    Targets="[server_name]"
    URI="wlxtmb.jar"
   />

4. Save the config.xml file.

Note: You must restart the server in order for the change to the config.xml file to be recognized.