# Compaq TP Desktop Connector
Getting Started

Previous | Contents | Index

After you perform the link operations and before you run the client, see Section 8.8 for other steps to perform.

# 8.3 Java Classes and STDL Support

The TP Desktop Connector software provides the native runtime environment. The STDL compiler generates Java classes and the Java Native Interface (JNI) for the client. Sections 8.3.1 to 8.3.3 describe the objects and their properties. See Sections 8.3.3 through 8.6 for information on coding the Java client.

## 8.3.1 Einfo Java Class and Access Support

The Java class `Einfo` is supplied for each task group to store STDL status information in a Java environment. The task group class has a property called `einfo` with a property type of `Einfo`.

The support for this class depends on whether you use `java` or `javabeans` as the input adapter in the `-a` flag on the STDL command line.

- For the `java` input adapter, this class has the following public fields:

      public int    eclass
      public int    ecode
      public String eproc
      public String epgroup
      public int    esource
      public String ecgroup

- For the `javabeans` input adapter, this class has the following public accessor methods:

      int getEclass()              void setEclass(int)
      int getEcode()               void setEcode(int)
      String getEproc()            void setEproc(String)
      String getEpgroup()          void setEpgroup(String)
      int getEsource()             void setEsource(int)
      String getEcgroup()          void setEcgroup(String)

See Examples 8_1 and 8-2 for sample code.

## 8.3.2 STDL-Generated Java Classes and Methods

The STDL compiler generates Java classes and methods based on the contents of the task group specification. The Java client maps a task group to Java classes and methods as follows:

- Name conversion (see Section 8.3.2.1)
- One Java class for each task group (called a task group class) and an invocation method for each task (see Section 8.3.2.2).
- Classes for STDL records (data type identifiers) and for STDL arguments (workspaces) used by a task in the task group; and support for accessing the record classes created (see Section 8.3.2.3).
- Support for Java clients to specify call attribute values to pass to communications adapters on each call (see Section 8.5).

### 8.3.2.1 STDL Compiler Name Conversion

When processing the STDL task group specification and related code, the STDL compiler derives the group name and class names from STDL identifiers as follows:

- Changes the task group name (group) or an STDL record name to lowercase. If you are developing a client interface for an ACMS application, the group name prefix is the ACMS application_name prefix (see Section 4.2.3).
- Replaces any hyphen characters (-) with underscore characters (_).
- Changes the first character of the name to uppercase.

### 8.3.2.2 Task Group Class and Methods

Within the Java class generated for a task group, the STDL compiler creates an invocation method for each task in the task group specification. The task group class contains an invocation method to invoke each task in the task group. The name for each invocation method is the same as the corresponding converted task name. The task group class encapsulates an `Einfo` class to process exception information.

### 8.3.2.3 Record Classes and Methods

TP Desktop Connector software uses Java classes to model STDL records. The STDL compiler generates a Java class for each record in a task and a class for each argument to be passed to a task. The Java class for an STDL record has a name in the following format:

`record-name_field-name`

The value record-name is derived from the STDL data type identifier that specifies the record layout according to the conversion rules (see Section 8.3.2.1). The value field-name is derived from the STDL field name according to the conversion rules (see Section 8.3.2.1).

The compiler creates one of these record classes in each of the following cases:

- The STDL data type identifier is used as an argument to a task in the task group.
- The STDL data type identifier is used as a data type for a field within another record object being generated for the task group (X/Open syntax only).
  The value record-name is derived from the STDL data type identifier that specifies the field record layout according to the conversion rules (see Section 8.3.2.1).
- An embedded record is used as a data type for a field within another record class being generated for the task group.

If an STDL data type identifier is used for more than one argument or is included in more than one other STDL record, the compiler generates only one STDL record class.

Support for fields depends on whether you use `java` or `javabeans` as the input adapter in the `-a` flag on the STDL command line.

- For the `java` input adapter, public fields are created, with names in the following format:

  `public data-type field-name`

  The public field name is derived from the STDL field name according to the conversion rules (see Section 8.3.2.1).

- For the `javabeans` input adapter, for each field within the record classes generated, both a `get` and a `set` accessor method are created, with names in the following format:

  `setfield-name(data-type)`

  `data-type getfield-name()`

  The method name is derived from the STDL field name according to the conversion rules (see Section 8.3.2.1).

The data type data-type depends on the STDL field type (see Section 8.3.3).

You can use a class browser in an integrated development environment (IDE) to examine objects defined by the generated Java classes.

## 8.3.3 Java Data Type Support

When the STDL compiler generates Java classes for STDL records (see Section 8.3.2), each field from an STDL record is given a data type as shown in Table 8-4.

Table 8-4 Java Data Type Mapping
STDL Data Type | Java Data Type | Comment
--- | --- | ---
ARRAY | 1
DATE | Date |
DECIMAL STRING | String |
FLOAT SIZE 4 | float | 32-bit IEEE 754
FLOAT SIZE 8 | double | 64-bit IEEE 754
INTEGER SIZE 1 | byte |
INTEGER SIZE 2 | short |
INTEGER SIZE 4 | int |
OCTET | byte | A signed quantity
RECORD | Record object | 2
TEXT CHARACTER SET ISO-LATIN-1 | String | Unicode characters
TEXT CHARACTER SET ISO-LATIN-2 | String | 3
TEXT CHARACTER SET ISO-UCS-2 | String | 3
TEXT CHARACTER SET KANJI | String | 3
TEXT CHARACTER SET KATAKANA | String | 3
UNSIGNED INTEGER SIZE 1 | byte | Signed value
UNSIGNED INTEGER SIZE 2 | short | Signed value
UNSIGNED INTEGER SIZE 4 | int | Signed value

1Array references are to the base data type starting with an index of zero.
2A Java object for the record is created (see Section 7.2.2).
3This data type support is not implemented.

# 8.4 Calling Tasks from Java Clients

To call tasks within a task group, write the Java client to perform the actions shown in the following examples. Example 8-1 shows a client generated from using the `java` input adapter.

Example 8-1 The Java Adapter Sample add_task Call

    class AddMtsClient
    {
      int add(int x, int y) throws Exception
      {
    (1)  Add_task_group_mts taskGroup = new Add_task_group_mts();
    (2)  Add_number inp1 = new Add_number();
        Add_number inp2 = new Add_number();
        Add_number result = new Add_number();

    (3)  inp1.Data = x;
        inp2.Data = y;
    (4)  taskGroup.add_task(inp1, inp2, result);

    (5)  if (taskGroup.einfo.eclass != 0 || taskGroup.einfo.ecode != 0)
        {
            System.out.println("Einfo error on task call");
            System.out.println("eclass = " + taskGroup.einfo.eclass);
            System.out.println("ecode = 0x" + Integer.toHexString(taskGroup.einfo.ecode));
            System.out.println("eproc = " + taskGroup.einfo.eproc);
            System.out.println("epgroup = " + taskGroup.einfo.epgroup);
            System.out.println("esource = " + taskGroup.einfo.esource);
            throw new Exception("Application error");
        }
    (6)  return result.Data;
      }

      static public void main(String args[]) {
          add_mts_client addMtsClient = new add_mts_client();
          if (args.length != 2) {
              System.out.println("Usage: x y");
          }
          else {
              try {
                  int x = Integer.parseInt(args[0]);
                  int y = Integer.parseInt(args[1]);
                  System.out.println("Answer = " + addMtsClient.add(x, y));
               }
               catch (NumberFormatException e) {
                   System.out.println("Invalid Input");
               }
               catch (Exception e) {
                   System.out.println(e);
               }
            }
        }
    }

The items in the following list correspond to the callouts in Example 8-1.

1. Create the object that represents the task group itself. Use the `new` method and refer to the task group class name `Add_task_group_mts`.
2. Create an object for each record to be used by the `Add_task_group_mts` object. Use the `new` method and refer to the class name. In this example, three `Add_number` objects are created.
3. Fill in the data in the record objects as necessary. Directly access the public fields within the record argument.
4. Call the task. Use the `add_task` invocation method within the `Add_task_group_mts` task group object, and pass the three `Add_number` argument parameters.
5. Directly access the `Einfo` object and its fields in the `Add_task_group_mts` task group object to determine the result of the task call.
6. Obtain the numeric result of the task call by directly accessing the output `Add_number` object.

Example 8-2 shows a client generated from using the `javabeans` input adapter.

Example 8-2 The JavaBeans Adapter Sample add_number Call

    (1)import java.beans.*;
      import java.io.*;
      class AddMtsClient {
        int add(int x, int y) throws Exception {
            try {
    (2)  Add_task_group_mts addTaskGroupMts =
              (Add_task_group_mts) Beans.instantiate(null, "Add_task_group_mts");
    (3)  Einfo einfo             = (Einfo) Beans.instantiate(null, "Einfo");
        Add_number inp1 =
            (Add_number) Beans.instantiate(null, "Add_number");
        Add_number inp2 =
            (Add_number) Beans.instantiate(null, "Add_number");
        Add_number result =
            (Add_number) Beans.instantiate(null, "Add_number");

    (4)  inp1.setData(x);
        inp2.setData(y);
    (5)  addTaskGroupMts.add_number(inp1, inp2, result);

    (6)  einfo = addTaskGroupMts.getEinfo();
    (7)  if (einfo.getEclass() != 0 || einfo.getEcode() != 0) {
            System.out.println("Einfo error on task call");
            System.out.println("Einfo.eclass = " + einfo.getEclass());
            System.out.println("Einfo.ecode = 0x" + Integer.toHexString(einfo.getEcode()));
            System.out.println("Einfo.eproc = " + einfo.getEproc());
            System.out.println("Einfo.epgroup = " + einfo.getEpgroup());
            System.out.println("Einfo.esource = " + einfo.getEsource());
            throw new Exception("Application error");
        }
    (8)  return result.getData();
      }
      catch (UnsatisfiedLinkError e)
      {
          System.out.println("Unable to locate matching DLL add_task_group_mts_java_mts[_g].dll");
          throw e;
      }
      catch (ClassNotFoundException e) {
          System.out.println("Unable to locate an application class");
          throw e;
      }
      catch (IOException e) {
          System.out.println("Unable to load an application class");
          throw e;
      }
      }

      static public void main(String args[]) {
          add_mts_client addMtsClient = new add_mts_client();
          if (args.length != 2) {
              System.out.println("Usage: x y");
          }
          else {
              try {
                  int x = Integer.parseInt(args[0]);
                  int y = Integer.parseInt(args[1]);
                  System.out.println("Answer = " + addMtsClient.add(x, y));
              }
              catch (NumberFormatException e) {
                  System.out.println("Invalid Input");
              }
              catch (Exception e) {
                  System.out.println(e);
              }
            }
        }
    }

The items in the following list correspond to the callouts in Example 8-2.

1. Import the classes.
2. Create the object that represents the task group itself. Use the `Beans.instantiate` method and refer to the task group class name `Add_task_group_mts`.
3. Create an object for each record to be used by the `Add_task_group_mts` object. This includes the implicitly used `einfo` object and objects that are explicitly passed as arguments to the `Add_task_group_mts.add_number` method. Use the `Beans.instantiate` method and refer to the class name. In this example, three `Add_number` class objects and one `Einfo` class object are created.
4. Fill in the data in the record objects as necessary. The fields within the record argument and `Einfo` objects are accessed through their get and set accessor methods.
5. Call the task. Use the `add_number` invocation method within the `Add_task_group_mts` task group object, and pass the three `Add_number` argument parameters.
6. Obtain the contents of the `Einfo` object from the `Add_task_group_mts` object through the `getEinfo` accessor method and update the local `einfo` object with the returned information.
7. Examine the `einfo` object using its accessor methods to determine the result of the task call.
8. Obtain the numeric result of the task call by accessing the output `return` object using its `getData` accessor method.

# 8.5 Specifying the Call Attributes in Java

A Java client can specify call attributes using one of the following techniques depending on whether you use `java` or `javabeans` as the input adapter in the `-a` flag on the STDL command line.

- If you use `java` as the input adapter, directly set the `call_attributes` field.
- If you use `javabeans` as the input adapter, refer to a String property in the task group class named `call_attributes`. The `call_attributes` property has the following accessor methods:

  `setCall_attributes(String)`

  `String getCall_attributes()`

When a new group object is created, the call attributes are null. Using the group object, the client can set the call attributes value for use on subsequent method invocations. If the client provides a new call attributes value, the new value overwrites the old value. If the client sets the call attributes value to null, subsequent method invocations on that object have no call attributes value.

The input adapter does not interpret the contents of the call attributes value. Any error in the value is not returned until the next invocation on that group object.

For more information on call attributes support for each output adapter, see Section 3.3.

# 8.6 Java Runtime Errors

Java-related runtime error values are returned by one of the following techniques.

- Throwing an exception
- Throwing an error

TP Desktop Connector native environment errors or errors returned from the application server are returned in the `Einfo` class (see Section 8.3.1). STDL `ecode` error codes that can be returned and their corresponding messages are described in Section 3.4.6. The STDL eclass codes are specified in the `eclass.h` file.

# 8.7 IDE Interaction with a Java Adapter

If you use `javabeans` as the input adapter with the `-a` flag, the generated classes provide a partial implementation of the JavaBeans standard. The Java input adapter defines the Java classes that the client uses. Discover these classes by using one of the following:

- A Java-aware IDE environment
- The normal JDK BeanBox

The extent of introspection support depends on the capabilities of the development environment that you use. Default discovery is provided by the STDL compiler naming conventions for methods and properties. Simple

BeanInfo classes provide introspection support for the classes generated for the following items:

- One for each task group class
- One for each `Einfo` class
- One for each record class

These BeanInfo classes are additional files in the STDL-generated Java archive.

The following are `javabeans` adapter restrictions:

- No graphic representation of the adapter classes is provided.
- No additional development objects for property editors are provided.
- No additional Bean customizers are provided.
- No implementation of Bean serialization is provided.

Previous | Next | Contents | Index