Using the Run-Time Component

WebLogic Integration supports run-time data translation through the com.bea.wlxt class, which we refer to, in this chapter, as the Java class. The Java class provides various methods that can be used to translate data between binary and XML formats. It can be deployed in an EJB using WebLogic Server, invoked from a business process management (BPM) workflow, or integrated into any Java application.

The data translation Java class provides several parse() methods that translate binary data into XML. The data translation run-time component also provides several serialize() methods that translate XML data to a binary format. Binary data formats are described via MFL documents. WebLogic Integration uses MFL documents to read and write binary data to or from XML. MFL documents are specified by a URL in a parse() or serialize() method.

The following sections provide code samples that show how to use the WebLogic Integration run-time data translation tools to parse binary data into XML, and to serialize XML into binary:

• Binary to XML

• XML-to-Binary Conversion

• XML-to-XML Transformation

 

---

Binary to XML

The following code listing uses the parse() method to parse a binary data file into XML.

Listing 6-1 Sample Binary-to-XML Parse() Method

1 import com.bea.wlxt.*;
2 import org.w3c.dom.Document;
3 import java.io.FileInputStream;
4 import java.net.URL;
5 
6 public class Example
7 {
8  public static void main(String[] args)
9  {
10   try
11   {
12    WLXT wlxt = new WLXT();
13    URL mflDocumentName = new URL("file:mymfl.mfl");
14    FileInputStream in = new FileInputStream("mybinaryfile");
15
16    Document doc = wlxt.parse(mflDocumentName, in, null);
17    String xml = wlxt.getXMLText(doc, 0, 2);
18    System.out.println(xml);
19   }
20    catch (Exception e)
21  {
22    e.printStackTrace(System.err);
23  }
24 }
25}

Note the following sequence in this code:

1. In line 12 a new instance of the Java class is instantiated.

2. In line 13 a Uniform Resource Locator (URL) is created for an MFL file that was created earlier with Format Builder.

3. In lines 14 and 15 a FileInputStream is created for binary data in mybinaryfile.

4. In line 16 the URL for the MFL document and the stream of binary data are passed into the parse method.

5. From line 17 the parse method converts the binary data into an instance of a W3C Document object which is then converted to XML text via the getXMLText() method. (As an alternative, the parse method can also convert the binary data into an instance of a W3C Document object and then manipulate that object directly via the W3C DOM API.)

Generating XML with a Reference to a DTD

WebLogic Integration's data translation tools include parse() methods that enable you to include a reference to a Document Type Definition (DTD) or an XML Schema in the XML document generated by either. The following listing illustrates this capability.

Listing 6-2 Example of Generating XML with a DTD Reference

1 import com.bea.wlxt.*;
2 import org.w3c.dom.Document
3 import java.io.FileInputStream;
4 import java.net.URL;
5
6 public class Example2
7 {
8  public static void main(String[] args)
9  {
10   try
11   {
12     WLXT wlxt = new WLXT();
13     URL mflDocumentName = new URL("file:mymfl.mfl");
14     FileInputStream in = new FileInputStream("mybinaryfile");
15
16     Documentdoc=wlxt.parse(mflDocumentName,in,"mydtd.dtd",
17     null);String xml = wlxt.getXMLText(doc, 0, 2);
18     System.out.println(xml);
19   }
20     catch (Exception e)
21   {
22     e.printStackTrace(System.err);
23   }
24  }
25 }

The only difference between Listing  6-1 and Listing  6-2 occurs in line 16: a different parse method is invoked that allows a DTD file (mydtd.dtd) to be specified, so that a reference to it will be included in the resulting XML document. The following example shows the DOCTYPE statement in the resulting XML document that contains the reference to mydtd.dtd:

<?xml version="1.0"?>
<!DOCTYPE someRootNode SYSTEM `mydtd.dtd'>

A similar parse method allows the resulting XML to refer to an XML Schema.

Specifying a Debug Writer

Every parse() method supported by WebLogic Integration allows a PrintWriter to be passed in as the last parameter. If this parameter is not null, WebLogic Integration prints debug messages to the specified PrintWriter. Such printing is helpful if the MFL document and the binary data do not agree and you need to debug the translation.

If you do not want to print debug messages, pass in null for this parameter, as shown in the previous listings.

Listing 6-3 Example of Passing in a Debug Writer

1 import com.bea.wlxt.*;
2 import org.w3c.dom.Document
3 import java.io.FileInputStream;
4 import java.io.PrintWriter;
5 import java.net.URL;
6 
7 public class Example3
8 {
9  public static void main(String[] args)
10 {
11   try
12   {
13     WLXT wlxt = new WLXT();
14     URL mflDocumentName = new URL("file:mymfl.mfl");
15     FileInputStream in = new FileInputStream
16     ("mybinaryfile");
17     Document doc=wlxt.parse(mflDocumentName,in,new
       PrintWriter(System.out,true));
18     String xml = wlxt.getXMLText(doc, 0, 2);
19     System.out.println(xml);
20   }
21     catch (Exception e)
22   {
23     e.printStackTrace(System.err);
24   }
25  }
26 }

In line 17, as a last parameter to the parse() method, a PrintWriter object is created from the System.out PrintStream. The creation of this object causes debug messages such as the following to be displayed on the console.

Listing 6-4 Debug Output

Parsing FieldFormat NAME at offset 0
  Field NAME Found delimiter [;]
  Field NAME type String offset 0 value=[John Doe]
Done FieldFormat NAME
Group PAYINFO repeat until delim=[*]
  Parsing 1st instance of StructFormat PAYINFO at offset 18
    Parsing FieldFormat PAYDATE at offset 18
.
.
.

 

---

XML-to-Binary Conversion

The following sample code listing shows how to use WebLogic Integration tools to convert XML text to binary format.

Listing 6-5 Sample XML-to-Binary Conversion

1 import com.bea.wlxt.*;
2 import java.io.FileInputStream;
3 import java.io.FileOutputStream;
4 import java.net.URL;
5 
6 public class Example4
7 {
8  public static void main(String[] args)
9  {
10   try
11   {
12    WLXT wlxt = new WLXT();
13    URL mflDocumentName = new URL("file:mymfl.mfl");
14    FileInputStream in = new FileInputStream("myxml.xml");
15    FileOutputStream out = new FileOutputStream("mybinaryfile");
16   
17    wlxt.serialize(mflDocumentName, in, out, null);
18    out.close();
19   }
20   catch (Exception e)
21   {
22       e.printStackTrace(System.err);
23   }
24  }
25 }

Note the following sequence in this code:

1. In line 12 a new instance of the Java class is created.

2. In line 13 a URL is created for an MFL file, and a FileInputStream is created for a file containing XML text.

3. A FileOutputStream is also instantiated to store the binary data that will be produced by the XML-to-binary translation.

4. In line 17 the serialize() method is invoked to translate the XML data in FileInputStream 'in' (myxml.xml) to the binary format described in 'mymfl.mfl'. The resulting binary data is written to the FileOutputStream `out' (which is the file `mybinaryfile').

Converting a Document Object to Binary Format

The following sample listing shows how to convert a W3C Document object to a binary format.

Listing 6-6 Converting a Document Object to Binary Format

1  import com.bea.wlxt.*;
2  import java.io.FileOutputStream;
3  import java.net.URL;
4
5  import org.w3c.dom.Document;
6
7  import org.apache.xerces.parsers.DOMParser;
8
9  public class Example5
10  {
11    public static void main(String[] args)
12    {
13       // Parse XML into a Document object
14       Document doc = null;
15       try
16       {
17         DOMParser parser = new DOMParser();
18         parser.parse("myxml.xml");
19         doc = parser.getDocument();
20       }
21       catch (Exception e)
22       {
23         e.printStackTrace(System.err);
24         System.exit(1);
25       }
26
27       try
28       {
29         WLXT wlxt = new WLXT();
30         URL mflDocumentName = new URL("file:mymfl.mfl");
31         FileOutputStream out = new
           FileOutputStream("mybinaryfile");
32
33         wlxt.serialize(mflDocumentName, doc, out, null);
34         out.close();
35       }
36       catch (Exception e)
37       {
38         e.printStackTrace(System.err);
39       }
40    }
41  }

This example shows how to specify a Document object to the serialize() method of the Java class. This technique is useful when your application already has XML in the form of a Document object, or when it has created a Document object using the DOM API. Lines 14 through 25 convert the XML text in the file myxml.xml to a Document object using an XML parser. This Document object is passed, in line 33, to convert it to the binary format specified by the MFL file mymfl.mfl.

Specifying a Debug Writer

The serialize methods also support specification of a PrintWriter parameter for the logging of debug messages. The following code example shows how to invoke the serialize method with a PrintWriter object:

wlxt.serialize(mflDocumentName, in, out, new
   PrintWriter(System.out, true));

This invocation causes the display, on the console, of debug messages such as the following.

Listing 6-7 Debug Output

Processing xml and mfl nodes tcp1
Processing xml node NAME
Checking MFL node NAME
Found matching MFL node NAME
Writing field NAME value John Doe
Processing xml node PAYINFO
Checking MFL node PAYINFO

 

---

XML-to-XML Transformation

The WebLogic Integration data translation tools also include methods for transforming XML through XSLT, a language designed for such conversions. The Java class provides transform() methods that apply an XSLT stylesheet to an XML document. An XSLT stylesheet is an XML document that describes transformations to be performed on the nodes of an XML document. Using a stylesheet, you can transform an XML document into HTML, PDF, or another XML dialect.

The following sample code listing shows how to transform an XML document using one of the methods provided by the Java class.

Listing 6-8 XML-to-XML Transformation

1  import com.bea.wlxt.*;
2  import java.io.FileInputStream;
3  import java.io.FileOutputStream;
4  import java.net.URL;
5
6  import org.xml.sax.InputSource;
7
8  public class Example7
9  {
10    public static void main(String[] args)
11    {
12
13       try
14       {
15         WLXT wlxt = new WLXT();
16         URL stylesheet = new URL("file:mystylesheet.xsl");
17         FileInputStream in = new FileInputStream("myxml.xml");
18         FileOuputStream out = new FileOutputStream
19         ("myoutputfile")
20
21         wlxt.transform(new InputSource(in), out, stylesheet);
22
23         out.close();
24       }
25       catch (Exception e)
26       {
27         e.printStackTrace(System.err);
28       }
29    }
30  }

Note the following sequence in this code:

1. In line 15 an instance of WLXT is created.

2. In line 16 a URL is created for an XSLT stylesheet created earlier.

3. In line 17 a FileInputStream is created for a file containing XML text.

4. A FileOutputStream is also created for the text that results from the XSLT transformation.

5. In line 21 a transform() method of the Java class is invoked to transform the XML in the file myxml.xml, according to the mystylesheet.xsl stylesheet. The output of the transformation is written to the myoutputfile file.

Initialization Methods

The Java class provides several methods to preprocess MFL documents and XSLT stylesheets. Once these documents are preprocessed, they are cached internally and reused when referenced in a parse(), serialize(), or transform() method. Preprocessing greatly improves the performance of these methods, because the MFL document or XSLT stylesheet has already been processed and cached. This technique is particularly useful when data translation is used in an EJB or servlet in which the same MFL documents or XSLT stylesheets are used repeatedly.

The Java class provides two init() methods that take either a java.util.Properties object or the filename of a Properties file as a parameter. These init() methods retrieve the WLXT.stylesheets and WLXT.MFLDocuments properties from the Properties object. Each property is expected to contain a comma-delimited list of documents to be preprocessed and cached. When these documents are later referenced in a parse(), serialize(), or transform() method, the preprocessed version is retrieved from the cache.

The following sample listing shows how to use an init() method to initialize an instance of the Java class.

Listing 6-9 myconfig.cfg Properties File

WLXT.MFLDocuments=file:mymfl.mfl
WLXT.stylesheets=file:mystylesheet.xsl

Listing 6-10 Sample Source Code for init() Method Using myconfig.cfg File

1  import com.bea.wlxt.*;
2  import java.io.FileInputStream;
3  import java.io.FileOutputStream;
4  import java.net.URL;
5
6  import org.xml.sax.InputSource;
7  import org.w3c.dom.Document;
8
9  public class Example8
10  {
11    public static void main(String[] args)
12    {
13
14      WLXT wlxt = null;
15
16      // Initialize WLXT with a properties file
17      try
18      {
19        wlxt = new WLXT();
20        wlxt.init("myconfig.cfg");
21      }
22      catch (Exception e)
23      {
24        e.printStackTrace(System.err);
25      }
26
27      // Parse binary data into XML
28      Document doc = null;
29      try
30      {
31        URL mflDocumentName = new URL("file:mymfl.mfl");
32        FileInputStream in = new FileInputStream("mybinaryfile");
33
34        doc = wlxt.parse(mflDocumentName, in, null);
35      }
36      catch (Exception e)
37      {
38        e.printStackTrace(System.err);
39      }
40
41      try
42      {
43        URL stylesheet = new URL("file:mystylesheet.xsl");
44        FileOutputStream out = new FileOutputStream
45        ("myoutputfile")
46
47        wlxt.transform(doc, out, stylesheet);
48
49        out.close();
50      }
51      catch (Exception e)
52      {
53        e.printStackTrace(System.err);
54      }
55    }
56  }

In line 20 the init() method causes the object to preprocess the documents listed in the myconfig.cfg file. Therefore two documents, the MFL document and the stylesheet, are processed and cached inside the object before being specified as follows:

• The MFL document is preprocessed before being specified in the parse() method in line 34.

• The stylesheet is preprocessed before being specified in the invocation of the transform() method in line 46.

Java API Documentation

For complete reference information about using the Java class, see com.bea.wlxt in the WebLogic Integration Javadoc. The Javadoc can also be found in the docs\apidocs subdirectory of your WebLogic Integration installation.

Run-Time Plug-In to Business Process Management

The data integration plug-in for business process management (BPM) facilitates the exchange of information between applications by supporting translations of data from binary formats used on legacy systems to XML, and vice versa. In other words, the BPM actions provided by the data integration plug-in allow you to access XML-to-binary and binary-to-XML translation capabilities.

In addition, the data integration plug-in provides the following features:

• Event data processing in binary format

• In-memory caching of MFL documents and translation object pooling (both of which boost performance)

• BinaryData variable type that can be used to edit and display binary data

• Export of entirely self-contained workflow definition packages

• Execution in a clustered WebLogic Server environment

The following illustration shows the relationship between the WebLogic Integration data integration tools and BPM.

Figure 6-1 Run-Time Plug-In to BPM