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

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.

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

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.

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.