Oracle WebLogic Tuxedo Connector Programmer's Guide

      

Using FML with Oracle WebLogic Tuxedo Connector

The following sections discuss the Field Manipulation Language (FML) and describe how the Oracle WebLogic Tuxedo Connector uses FML.

 

Overview of FML

For more information about using FML, see Programming a Tuxedo Application Using FML.

FML is a set of java language functions for defining and manipulating storage structures called fielded buffers. Each fielded buffer contains attribute-value pairs in fields. For each field:

There are two types of FML:

 

The Oracle WebLogic Tuxedo Connector FML API

The Oracle WebLogic Tuxedo Connector implements a subset of FML functionality. For more information regarding FML32, refer to FML32 Considerations.

The FML application program interface (API) is documented in the weblogic.wtc.jatmi package included in the Javadocs for WebLogic Server Classes.

 

FML Field Table Administration

Field tables are generated in a manner similar to Oracle Tuxedo field tables. The field tables are text files that provide the field name definitions, field types, and identification numbers that are common between the two systems. To interoperate with an Oracle Tuxedo system using FML, the following steps are required:

  1. Copy the field tables from the Oracle Tuxedo system to Oracle WebLogic Tuxedo Connector environment.

    For example: Your Oracle Tuxedo distribution contains a bank application example called bankapp. It contains a file called bankflds that has the following structure: 

    #Copyright (c) 1990 Unix System Laboratories, Inc.

    #All rights reserved

    #ident  “@(#) apps/bankapp/bankflds     $Revision: 1.3 $”

    # Fields for database bankdb

    # name                         number  type    flags   comments

    ACCOUNT_ID                     110     long    -       -       

    ACCT_TYPE                      112     char    -       -       

    ADDRESS                        109     string  -       -       

    .

    .

    .

  2. Converted the field table definition into Java source files. Use the mkfldclass utility supplied in the weblogic.wtc.jatmi package. This class is a utility function that reads a FML32 Field Table and produces a Java file which implements the FldTbl interface. There are two instances of this utility:

    • mkfldclass

    • mkfldclass32

      Use the correct instance of the command to convert the bankflds field table into FML32 java source. The following example uses mkfldclass. 

      java weblogic.wtc.jatmi.mkfldclass bankflds

      The resulting file is called bankflds.java and has the following structure: 


      import java.io.*;

      import java.lang.*;

      import java.util.*;

      import weblogic.wtc.jatmi.*;

      

      public final class bankflds

              implements weblogic.wtc.jatmi.FldTbl

      {

              /** number: 110  type: long */

              public final static int ACCOUNT_ID = 33554542;

              /** number: 112  type: char */

              public final static int ACCT_TYPE = 67108976;

              /** number: 109  type: string */

              public final static int ADDRESS = 167772269;

              /** number: 117  type: float */

      .

      .

      .

  3. Compile the resulting bankflds.java file using the following command: 
    javac bankflds.java

    The result is a bankflds.class file. When loaded, the Oracle WebLogic Tuxedo Connector uses the class file to add, retrieve and delete field entries from an FML32 field.

  4. Add the field table class file to your application CLASSPATH.

  5. Update your WTCServer MBean.

    • Update the WTCResources MBean to reflect the fully qualified location of the field table class file.

    • Use the keywords required to describe the FML buffer type: fml16 or fml32.

    • You can enter multiple field table classes in a comma separated list.

      For example: 

      <wtc-resources>

           <name>BankappResources</name>

           <fld-tbl16-class>my.bankflds</fld-tbl16-class>

           <fld-tbl16-class>your.bankflds</fld-tbl16-class>

           <fld-tbl16-class>more.bankflds</fld-tbl16-class>

      </wtc-resources>

  6. Restart your Oracle WebLogic Server to load the field table class definitions.

 

Using the DynRdHdr Property for mkfldclass32 Class

Oracle WebLogic Tuxedo Connector provides a property that provides an alternate method to compile FML tables. You may need to use the DynRdHdr utility if:

Use the following steps to use the DynRdHdr property when compiling your FML tables:

  1. Convert the field table definition into Java source files. 
    java -DDynRdHdr=Path_to_Your_FML_Table weblogic.wtc.jatmi.mkfldclass32 userTable

    The arguments for this command are defined as follows:

    Attribute Description
    -DDynRdHdr Oracle WebLogic Tuxedo Connector property used to compile an FML table.
    Path_to_Your_FML_Table Path name of your FML table. This may be either a fully qualified path or a relative path that can be found as a resource file using the server's CLASSPATH.
    weblogic.wtc.jatmi.mkfldclass32 This class is a utility function that reads an FML32 Field Table and produces a Java file which implements the FldTbl interface.
    userTable Name of the .java method created by the mkfldclass32 class.

  2. Compile the userTable file using the following command: 
    javac userTable.java

  3. Add the userTable.class file to your application CLASSPATH.

  4. Update the WTCResources MBean to reflect the fully qualified location of the userTable.class file.

  5. Target your WTCServer. The userTable.class is loaded when the WTCServer service starts.

Once you have created the userTable.class file, you can modify the FML table and deploy the changes without having to manually create an updated userTable.class. When the WTC Service is started, Oracle WebLogic Tuxedo Connector will load the updated FML table using the location specified in the Resources tab of your WTC service configuration. If the Path_to_Your_FML_Table attribute changes, you will need to use the preceding procedure to update your userTable.java and userTable.class files.

 

Using TypedFML32 Constructors

Two new constructors for TypedFML32 are available to improve performance. The following topic provides explanation as to when to use these constructors.

The constructors are defined in the Javadocs for WebLogic Server Classes.

 

Gaining TypedFML32 Performance Improvements

To gain TypedFML32 performance improvements, you can choose to give size hints to TypedFML32 constructors. There are two parameters that are available to those constructor:

For instance, a field table used by the buffer contains 20 field IDs, and each field can occur 20 times. In this case, the first parameter should be 400 for the maximum number of fields. The second parameter should be 20 for the total number of field IDs. 

TypeFML32 mybuffer = new TypeFML32(400, 20);

This usually works well with any size of buffer; however, it does not work well with extremely small buffers.

If you have an extremely small buffer, use those constructor without hints. An example of an extremely small buffer is a buffer with less than 16 total occurrences. If the buffer is extremely large, for example contains more than 250000 total field occurrences, then the application should consider splitting it into several buffers smaller than 250000 total field occurrences.

 

tBridge XML/FML32 Translation

The data type specified must be FLAT or NO. If any other data type is specified, the redirection fails.

The TranslateFML element of the WTCtBridgeRedirect MBean is used to indicate if FML32 translation is performed on the message payload. There are two types of FML32 translation: FLAT and NO.

 

FLAT

The message payload is translated using the Oracle WebLogic Tuxedo Connector internal FML32/XML translator. Fields are converted field-by-field values without knowledge of the message structure (hierarchy) and repeated grouping.

In order to convert an FML32 buffer to XML, the tBridge pulls each instance of each field in the FML32 buffer, converts it to a string, and places it within a tag consisting of the field name. All of these fields are placed within a tag consisting of the service name. For example, an FML32 buffer consisting of the following fields: 

NAME          JOE

ADDRESS       CENTRAL CITY

PRODUCTNAME   BOLT

PRICE         1.95

PRODUCTNAME   SCREW

PRICE         2.50

The resulting XML buffer would be: 

<FML32>

  <NAME>JOE</NAME>

  <ADDRESS>CENTRAL CITY</ADDRESS>

  <PRODUCTNAME>BOLT</PRODUCTNAME>

  <PRODUCTNAME>SCREW</PRODUCTNAME>

  <PRICE>1.95</PRICE>

  <PRICE>2.50</PRICE>

</FML32>

 

NO

No translation is used.

For JMS to Oracle Tuxedo, the tBridge maps a JMS TextMessage into an Oracle Tuxedo TypedBuffer (TypedString) and vice versa depending on the direction of the redirection. JMS BytesMessage are mapped into Oracle Tuxedo TypedBuffer (TypedCarray) and vice versa.

For Oracle Tuxedo to JMS, passing an FML/FML32 buffer behaves as if translateFML is set to FLAT. Therefore, in this case, setting translateFML to NO has no effect and if the Oracle Tuxedo buffer is of type FML/FML32, the translation takes place automatically.

 

FML32 Considerations

Remember to consider the following information when working with FML32:

 

Using the XmlFmlCnv Class for XML to and From FML/FML32 Translation

An alternative option to using the tBridge to automatically translate XML buffers to and from FML/FML32 is to use the XmlFmlCnv class which supports ordering, grouping and beautifying functionality. The following code listing is an example that uses the XmlFmlCnv class for conversion to and from XML buffer formats. 


import weblogic.wtc.jatmi.TypedFML32;

import weblogic.wtc.jatmi.FldTbl;

import weblogic.wtc.gwt.XmlFmlCnv;



public class xml2fml

{

public static void main(String[] args) {

    String xmlDoc = "<XML><MyString>hello</MyString></XML>";

    TypedFML32 fmlBuffer = new TypedFML32(new MyFieldTable());

    XmlFmlCnv c = new XmlFmlCnv();

    fmlBuffer = c.XMLtoFML32(xmlDoc, fmlBuffer.getFieldTables());

    String result = c.FML32toXML(fmlBuffer);

    System.out.println(result);

}

}

See Class XmlFmlCnv.

 

Limitations of XmlFmlCnv Class

The FLD_MBSTRING field in FML32 is not supported by the XmlFmlCnv.FML32toXML method in this release.

 

MBSTRING Usage

A TypedMBString object can be used almost identically as a TypedString object in a WTC application code. The only difference is that TypedMBString has a codeset encoding name associated to the string data.

This section includes the following topics.

 

Sending MBSTRING Data to an Oracle Tuxedo Domain

When an Oracle Tuxedo message that contains an MBSTRING data is sent to another Oracle Tuxedo domain, TypedMBString uses the conversion function of java.lang.String class to convert between Unicode and an external encoding. The TypedMBString has a codeset encoding name associated to the string data.

When a TypedMBString object is created by a WTC application code, the encoding name is set to null. The null value of the encoding name means that the default encoding name is used for Unicode string to byte array conversion while sending the MBSTRING data to a remote domain. By default, the Java's default encoding name for byte array string is used for the default encoding name.You can specify encoding or accept the default encoding. The following order defines the order of precedence for TypedMBString.

  1. Specify the encoding name by setMBEncoding() method.

  2. Specify the encoding name through the setDefaultMBEncoding() method of weblogic.wtc.jatmi.MBEncoding class.

  3. Specify the encoding name through the RemoteMBEncoding attribute of the WTCResourcesMBean.

  4. MBENCODINGPROPERTY system property value.

  5. Accept the Java default encoding name.

 

Receiving MBSTRING Data from an Oracle Tuxedo Domain

When an Oracle Tuxedo message that contains an MBSTRING data is received from a remote domain, the following actions take place.

  1. WTC determines the encoding of the MBSTRING data by the codeset tcm in the received message.

  2. WTC creates a TypedMBString object.

    A TypedMBString object can be used almost identically as a TyepdString object in WTC application code. However, the TypedMBString has a codeset encoding name associated to the string data.

  3. WTC passes the TypedMBString object to the WTC application code. The application code knows the encoding of the received MBSTRING data by the instance method getMBEncoding().

 

Using FML with Oracle WebLogic Tuxedo Connector

FLD_MBSTRING is a field type added to TypedFML32. In this case, a TypedMBString object is passed to the TypedFML32 method as the associated object type of FLD_MBSTRING. You can specify the encoding name used for the MBSTRING conversion for a FLD_MBSTRING field.

The following order defines the order of precedence for TypedFML32.

  1. Specify the encoding name by setMBEncoding() method of the TypedMBString object for the field.

  2. Specify the encoding name by setMBEncoding() method of the TypedFML32 object.

  3. Specify the encoding name through the setDefaultMBEncoding() method of weblogic.wtc.jatmi.MBEncoding class.

  4. Specify the encoding name through the RemoteMBEncoding attribute of the WTCResourcesMBean.

  5. MBENCODINGPROPERTY system property value.

  6. Accept the Java default encoding name.

Notes: The following methods must be updated when using FLD_MBSTRING: Fldtype(), Fchg(), Fadd(), Fget(), and Fdel().

Note: The on-demand encoding methods and auto-conversion methods needed in Oracle Tuxedo, such as Fmbpack32() and Fmbunpack32() are not needed by Oracle WebLogic Tuxedo Connector.