Programming an Oracle Tuxedo Application Using Java

     Previous  Next    Open TOC in new window    View as PDF - New Window  Get Adobe Reader - New Window
Content starts here

Reference

This topic includes the following sections:

 


Using FML with Oracle Tuxedo Java Server

Overview of 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:

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

The Oracle WebLogic Tuxedo Connector FML API

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 Tuxedo Java server environment.
  2. For example: Your Oracle Tuxedo distribution contains a bank application example called bankapp. It contains a file called bankflds that has the following structure:

    # name number type flags comments

    ACCOUNT_ID 110 long - -

    ACCT_TYPE 112 char - -

    ADDRESS 109 string - -

  3. Converted the field table definition into Java source files. Use the mkfldclass/mkfldclass32 utility supplied in the weblogic.wtc.jatmi package. This class is a utility function that reads a FML/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 */

      .

      .

      .

      }

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

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

  6. Add the field table class to <Resources> section in Tuxedo Java server's configuration file (Also make sure it is also included in <ClassPath> of Tuxedo Java server's configuration file).
  7. For example:

    <Resources>

    <FieldTable16Classes>bankflds</FieldTable16Classes>

    </Resources>

  8. Restart your Tuxedo Java server to load the field table class definitions.

Using the DynRdHdr Property for mkfldclass32 Class

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.
  2. java -DDynRdHdr=Path_to_Your_FML_Table
  3. weblogic.wtc.jatmi.mkfldclass32 userTable

The arguments for this command are defined as follows:

Table 5-1 Arguments for the Commend to Use the DynRdHdr Property
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.

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

  3. Add the field table class to <Resources> section in Tuxedo Java server's configuration file(Also make sure it is also included in <ClassPath> of Tuxedo Java server's configuration file).
  4. For example:

    <Resources>

    <FieldTable32Classes>userTable</FieldTable32Classes>

    </Resources>.

  5. Restart your Tuxedo Java server to load the field table class definitions.

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 Java server is started, Java server will load the updated FML table.

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.

Gaining TypedFML32 Performance Improvements

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".

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);

Note: This usually works well with any size of buffer; however, it does not work well with extremely small buffers.
Note: 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.

 


Using VIEW with Oracle Tuxedo Java Server

Overview of VIEW Buffers

Oracle Tuxedo Java server allows you to use a Java VIEW buffer type analogous to an Oracle Tuxedo VIEW buffer type derived from an independent C structure. This allows Oracle Tuxedo Java server classes and Oracle Tuxedo applications to pass information using a common structure.

For more information on Oracle Tuxedo VIEW buffers, see "Using a VIEW Typed Buffer" in Programming a Tuxedo ATMI Application Using C.

How to Create a VIEW Description File

Your Oracle Tuxedo Java server class and your Oracle Tuxedo application must share the same information structure as defined by the VIEW description. The following format is used for each structure in the VIEW description file:

$ /* VIEW structure */

VIEW viewname

type cname fbname count flag size null

where

Example VIEW Description File

The following provides an example VIEW description which uses VIEW buffers to send information to and receive information from an Oracle Tuxedo application. The file name for this VIEW is infoenc.

Listing 5-1 Example VIEW Description
VIEW infoenc
#type    cname    fbname  count flag size null
float    amount   AMOUNT  2     -    -    0.0
short    status   STATUS  2     -    -    0
int      term     TERM    2     -    -    0
char     mychar   MYCHAR  2     -    -    -
string   name     NAME    1     -    16   -
carray   carray1  CARRAY1 1     -    10   -
dec_t    decimal  DECIMAL 1     -    9    - #size ignored by viewj/viewj32
END
Note: fbname and null fields are not relevant for independent Java and C structures and are ignored by the Java and C VIEW compiler. You must include a value (for example, a dash) How to Use the viewj CompilerHow to Use the viewj Compileras a placeholder in these fields.

How to Use the viewj Compiler

To compile a VIEW typed buffer, run the viewj command, specifying the package name and the name of the VIEW description file as arguments. The output file is written to the current directory.

To use the viewj compiler, enter the following command:

java weblogic.wtc.jatmi.viewj [options] [package] viewfile

To use the viewj32 compiler, enter the following command:

java weblogic.wtc.jatmi.viewj32 [options] [package] viewfile

The arguments for this command are defined as follows:

Table 5-3 Arguments for the Commands for viewj Compiler
Argument
Description
options
  • -associated_fields:
Use to set AssociatedFieldHandling to true. This allows set and get accessor methods to use the values of the associated length and count fields if they are specified in the VIEW description file. If not specified, the default value for AssociatedFieldHandling is false.
  • -bean_names:
Use to create set and get accessor names that follow JavaBeans naming conventions. The first character of the field name is changed to upper case before the set or get prefix is added. The signature of indexed set accessors for array fields changes from the default signature of void setAfield (T value, int index) to void setAfield (int index, T value).
  • -compat_names:
Use to create set and get accessor names that are formed by taking the field name from the VIEW description file and adding a set or get prefix. Provides compatibility with releases prior to WebLogic Server 8.1 SP2. Default value is -compat_names if -bean_names or -compat_names is not specified.
  • -modify_strings:
Use to generate different Java code for encoding strings sent to Oracle Tuxedo and decoding strings received from Oracle Tuxedo. Encoding code adds a null character to the end of each string. Decoding code truncates each string at the first null character received.
  • -xcommon:
Use to generate output class as extending TypedXCommon instead of TypedView.
  • -xtype:
Use to generate output class as extending TypedXCType instead of TypedView.

Note: -compat_names and -bean_names are mutually exclusive options.

package
The package name to be included in the .java source file.
Example: examples.wtc.atmi.simpview
viewfile
Name of the VIEW description file.
Example: Infoenc

For example:

java weblogic.wtc.jatmi.viewj -compat_names examples.javaserver.atmi.simpview infoenc

java weblogic.wtc.jatmi.viewj32 -compat_names -modify_strings

examples.javaserver.atmi.simpview infoenc

How to Pass Information to and from a VIEW Buffer

The output of the viewj and viewj32 command is a .java source file that contains set and get accessor methods for each field in the VIEW description file. Use these set and get accessor methods in your Java applications to pass information to and from a VIEW buffer.

The AssociatedFieldHandling flag is used to specify if the set and get methods use the values of the associated length and count fields if they are specified in the VIEW description file.set methods set the count for an array field and set the length for a string or carray field.

Use one of the following to set or get the state of the AssociatedFieldHandling flag:

How to Use VIEW Buffers in JATMI Applications

Use the following steps when incorporating VIEW buffers in your JATMI applications:

  1. Create a VIEW description file for your application as described above.
  2. Compile the VIEW description file as described above.
  3. Use the set and get accessor methods to pass information to and receive information from a VIEW buffer as described above.
  4. Import the output class of the VIEW compiler into your source code.
  5. If necessary, compile the VIEW description file for your Oracle Tuxedo application and include the output in your C source file as described in "Using a VIEW Typed Buffer" in Programming a Tuxedo ATMI Application Using C.
  6. Configure the fully qualified class name of the compiled Java VIEW description file in <Resources> section in Tuxedo Java server configuration. The class of the compiled Java VIEW description file should also be included in <ClassPath> of your configuration file.
  7. For example: (for VIEW32)

    <Resources>

    <ViewFile32Classes> examples.javaserver.atmi.simpview</ViewFile32Classes>

    </Resources>

  8. Launch your Oracle Tuxedo Java Server.

How to Get VIEW32 Data In and Out of FML32 Buffers

A helper class is available to add and get VIEW32 data in and out of an FML32 buffer. The class name is wtc.jatmi.FViewFld. This class assists programmers in developing JATMI-based applications that use VIEW32 field type for FML32 buffers.

No change to configuration is required. You still configure the VIEW32 class using the ViewFile32Classes attribute in the <Resources> section of the Tuxedo Java server configuration file.

The following access methods are available in this helper class.

The following code listing is an example FML Description (MyFieldTable) related to the example in Listing 5-2.

Listing 5-3 Example FML Description
*base 20000 
#name    number  type   flags   comments
FLD0     10      string -       -
FLD1     20      long   -       -
FLD2     30      float  -       -
myview   50      view32 -       defined in View description file

  Back to Top       Previous  Next