Using the XML Translator Plug-In

 

Within most enterprise application integration (EAI) problem domains, data translation is an inherent part of an EAI solution. XML is quickly becoming the standard for exchanging information between applications, and is invaluable in integrating disparate applications. However, most data transformation engines do not support translations between binary data formats and XML. XML Translator Plug-In for WebLogic Process Integrator provides for an exchange of information between applications by supporting data translations between binary formats from legacy systems and XML.

In addition to this data translation capability, the XML Translator Plug-In provides a binary data event handler, in-memory caching of MFL documents and translation object pooling to boost performance, a BinaryData variable type to edit and display binary data, and execution within a WebLogic Server clustered environment.

This section provides information about the following topics:

• Data Translation with the XML Translator Plug-In

• Processing Event Data

• Enhancing Data Translation Performance

• Custom Data Types and the XML Translator Plug-In

• WebLogic Server Clustering Support

 

---

Data Translation with the XML Translator Plug-In

The XML Translator Plug-In provides XML and non-XML translation capabilities from within WebLogic Process Integrator. To perform one of these translation actions, follow the steps below. For more information on the actions specific to WebLogic Process Integrator, refer to the WebLogic Process Integrator documentation.

1. Start WebLogic Process Integrator Server and Studio.

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

   Figure 2-1 Task Properties Dialog

   
    

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

   Figure 2-2 Add Action dialog

   
    

4. Select Integration Actions to expand its action list, then select Data Integration and choose the action you want to perform (Translate XML to Binary or Translate Binary to XML).

Translate XML to Binary

To perform an XML to binary translation:

1. From the Add Action dialog (Figure 2-2), choose XML to Binary Translation. The Translate XML to Binary dialog opens (Figure 2-3).

   Figure 2-3 Translate XML to Binary Dialog

   
    

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

   Field	Description
   Message Format Parameters
   Name	The name of the message format. You can type a name directly in the text box, or click Browse to select the document from the repository.
   Description	Displays the description of the message format. Note: This field is display only. You cannot edit this field.
   Notes	Displays the notes attached to the message format. Note: This field is display only. You cannot edit this field.
   Debug	Enable or disable debug messaging. When you select this option, the translation actions are written to the WebLogic Server log file.
   Message Format Action Buttons
   Browse	Allows you to browse MFL documents in the repository. Refer to "Retrieving and Storing Repository Documents" in the BEA WebLogic XML/Non-XML Translator User Guide for specific instructions.
   View	Displays the items contained in the message format so you can verify that you have selected the correct document type for translation.
   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: Type the name you want to assign to the new variable and click OK. A confirmation message box displays. Click Yes to create the new variable.
   Assign Result To	Displays the Binary Data workflow variables. Select the variable you want to use to store the translated information, or create a new variable as follows: Type the name you want to assign to the new variable and click OK. Click Yes to create the new variable.

   
    

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

Translate Binary to XML

To perform a binary to XML translation:

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

   Figure 2-4 Translate Binary to XML Dialog

   
    

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

   Field	Description
   Message Format Parameters
   Name	The name of the message format. You can type a name directly in the text box, or click Browse to select the message format from the repository.
   Description	Displays the description of the message format. Note: This field is display only. You cannot edit this field.
   Notes	Displays the notes attached to the message format. Note: This field is display only. You cannot edit this field.
   Debug	Enable or disable debug messaging. When you select this option, the translation actions are written to the WebLogic Server log file.
   Message Format Action Buttons
   Browse	Allows you to browse MFL documents in the repository. Refer to "Retrieving and Storing Repository Documents" in the BEA WebLogic XML/Non-XML Translator User Guide for specific instructions.
   View	Displays the items contained in the message format so you can verify that you have selected the correct document type for translation.
   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: Type the name you want to assign to the new variable and click OK. A confirmation message box displays. 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: Type the name you want to assign to the new variable and click OK. Click Yes to create the new variable.

   
    

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

 

---

Processing Event Data

The XML Translator Plug-In provides functionality that allows binary data to trigger WebLogic Process Integrator workflows by converting the binary data to XML, or pre-processing it at the front end of WebLogic Process Integrator event processing. This functionality is referred to as the "event handler." Publishing JMS messages to a topic causes the event handler to run.

There are three JMS properties required for the message to be pre-processed by the XML Translator 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: This MFL document must be stored in the repository.

Listing 2-1 is a sample of the code used to build a message that is to be processed by the XML Translator 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);

This process is illustrated in the servlet sample application (see Running the WebLogic Process Integrator Servlet Sample).

 

---

Enhancing Data Translation Performance

The XML Translator Plug-In provides a configuration panel to administer and monitor the MFL document in-memory cache and enable or disable 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 on the actions specific to WebLogic Process Integrator, refer to the WebLogic Process Integrator documentation.

1. Start WebLogic Process Integrator Studio.

2. Choose Configuration—>Plugins. The Plugin Configuration dialog opens (Figure 2-5).

   Figure 2-5 Plugin Configuration Dialog

   
    

3. Choose XML Translator Plug-in and click Update. The Configuration dialog for the XML Translator Plug-in opens (Figure 2-6).

   Figure 2-6 Configuration Dialog for XML Translator Plug-In

   
    

4. Use the fields as described in the table below to monitor and enhance translation performance.

   Field	Description
   XML Translator 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 where the MFL document needed 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. This requires all future translation requests to load MFL documents 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 XML Translator Plug-in provides additional display and edit capabilities over the standard WebLogic Process Integrator functionality. These capabilities are provided by the Hex Editor component of Format Tester for displaying and editing binary data.

 

---

Variable Types and the XML Translator Plug-In

The XML Translator 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 group of binary data with additional display capabilities. The BinaryData variable is used by programs that call the actions provided by the XML Translator 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 XML Translator Plug-In

XML Translator includes a User Defined Type feature that allows you to create custom data types specific to your unique data type requirements. The User Defined Type feature allows these custom data types to be plugged in to the XML Translator runtime engine. Once a user defined data type is plugged-in, it is indistinguishable from a built-in data type in both features and function.

Configuring User Defined Data Types

User Defined data types used by the XML Translator Plug-In are stored in the XML Translator repository as CLASS documents. At runtime, the XML Translator Plug-In loads user defined type classes from the repository as required. In addition, the XML Translator Plug-In will export the MFL and class files required to support the active template allowing a template to be imported on another Process Integrator instance intact. Class documents may be placed in the repository using one of the following methods:

• Using Format Builder

• Using the Repository Import Utility

Using Format Builder

Perform the following steps to publish a user defined type to the repository using Format Builder.

1. Start Format Builder by clicking Start—>Programs—>BEA WebLogic E-Business Platform—>WebLogic Integration 2.0—>xmltranslator—>Format Builder. The Format Builder main window displays.

2. Choose Repository—>Log In. The Process Integrator Repository Login window opens.

   Figure 2-7 Login Window

   
    

3. Enter the userid specified for the server in the User Name field.

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

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

   Note: The Process Integrator Repository Login window allows up to three unsuccessful login attempts, after which, a login failure message is displayed. If you experience three login failures, choose Repository—>Log In to repeat the login procedure.

6. Click Connect. If your login is successful, the Login window disappears and the Format Builder Title bar displays the server name and port number entered on the Process Integrator Repository Login window. You may now choose any of the active repository menu items to access.

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

   Figure 2-8 Add/Remove User Defined Types Dialog

   
    

   With a repository connection established, the Add/Remove User Defined Types dialog box displays the status of each registered user defined type and allows for its publication to the repository. The user defined type repository status is reflected by an icon of a ball preceding the type name of each installed user defined type.

   The color of the icon associated with each user defined type indicates its status:

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

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

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

8. Select the class you want to publish from the list of Installed Types and click Publish. The icon for the selected entry should become green indicating the class was successfully placed in the repository.

Using the Repository Import Utility

Perform the following steps to use the repository import utility to import Java class files, including XML Translator user defined types.

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 file name on the Import command line.

   java com.bea.wlxt.repository.Import <file name>

   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 to the repository using the Repository Import utility, not just user defined types. This is useful if a user defined type relies on additional class files that do not extend the com.bea.wlxt.bintype.Bintype class.

 

---

WebLogic Server Clustering Support

The XML Translator Plug-in can operate successfully in a WebLogic Server clustered 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 the use of a JMS topic. The topic is used for communication between XML Translator components on different nodes in a cluster.

Configuring the XML Translator Plug-in for Clustering

If you want to take advantage of the clustering capability, you must configure the XML Translator Plug-In as follows:

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

   com.bea.wlxt.cluster.BroadcastTopic

   Note: Refer to the WebLogic Server documentation for more information on creating JMS topics.

2. Open the config.xml file in a text editor. This file can be found in the config directory where you have WebLogic Process Integrator installed.

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

3. Locate the <Application> section for WebLogic Process Integrator and add the following anywhere within 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.