![]() |
Copyright © TIBCO Software Inc. All Rights Reserved |
If the corresponding Java argument is a one-dimensional array of type byte, the following takes place:
2. The bytes in the TIBCO Object Service Broker string argument are used to populate the array.
1. A String class object is created and initialized using a constructor that accepts a byte array and a code page indicator. The constructor interprets the TIBCO Object Service Broker string passed as a byte array as a single-byte character string in the code page indicated by the String argument and causes the value of the String object to become the result of converting the single-byte character string to UNICODE.
4. The String class object and other intermediate objects are released for garbage collection when the routine returns.A TIBCO Object Service Broker string is returned from a Java external routine as a return value in one of two ways:
• If the corresponding Java return value is a one-dimensional array of type byte, the bytes of that array are extracted and used to form the characters of the string returned to the calling TIBCO Object Service Broker rule.
• If the corresponding Java return value is of class String, a single-byte character string in the Execution Environment code page is extracted from the String using a method that returns a byte array containing the character string converted from UNICODE using the code page designation passed to it.If a Java external routine raises a Java exception, the TIBCO Object Service Broker JAVAFAIL exception is raised upon return from the external routine. This exception can be caught in rules code and the error message and logs generated by the Java exception can be checked.When these tasks are completed, a TIBCO Object Service Broker rule can invoke the external routine.
If your Execution Environment is multi-threaded (that is, the MAXSESSION Execution Environment parameter is greater than 1), your external routines must be reentrant and thread-safe.A Java Virtual Machine (JVM) must be invoked and attached to an Execution Environment before a rule can execute a Java external routine. Each Execution Environment can specify which JVM to attach, allowing different Java routines to use different versions of JVM.You specify the JVM and the options to pass to it in the @JAVAOPTIONS table, which is parameterized by EENAME:
When the first Java external routine is called after Execution Environment start-up, by default the system searches for the EENAME instance that matches the Execution Environment in use. If this instance does not exist, the instance with EENAME equal to “*DEFAULT*” is used instead.The SEQ# key field of @JAVAOPTIONS indicates the sequence in which the occurrences are processed. The values of the SEQ# field do not have to be contiguous.There must be one and only one location occurrence in each instance of the table. The VALUE field in this occurrence contains the path to the JVM to be started. If the path is longer than this 64‑character field, one or more continuation occurrences follow, containing the remainder of the path in their VALUE fields.There can be zero or more parameter occurrences in each instance of the table. A parameter occurrence contains a command line parameter that must be passed to the JVM. Such parameters can be used to specify storage allocations or debugging options to the JVM. The options are specific to the implementation of the JVM and their names, form and meaning are specified in the documentation of the JVM in question.SEQ# TYPE VALUE------ - ------------------------------------------------------------10 L E:\jdk1.6.0_30\jre\15 C bin\server\jvm.dll20 P -Djava.class.path=e:\testjava30 P -verbose:class,gcWhen an Execution Environment calls a Java external routine by using this instance to determine the JVM to start, it attempts to load the following DLL:which, in the case of the Sun JVM for Windows cause it to use a CLASSPATH variable value of e:\testjava and runtime options that indicate tracing output of class loading and garbage collection is required.The JVM remains attached to the Execution Environment until the Execution Environment terminates.The external routine and its load module name are identified to TIBCO Object Service Broker through an entry in the ROUTINES table. If the routine has arguments, these are specified in a table instance of the ARGUMENTS table. Ensure that you have adequate security to insert data into these tables before editing them.Use the Table Editor to add information to these tables. To use this option, enter the required table name beside the ED edit table option on the workbench and press Enter to display the table.The following illustration shows an extract of the ROUTINES table. You must scroll right using PF11 to see additional fields.
Type the appropriate information about your external routine in fields of the ROUTINES table, as described:
The name used to invoke the external routine.
Syntax: C, Length: 16 The language in which the external routine is written, in this case JAVA.
Syntax: C, Length: 16 Whether the external routine returns a value (Y or N).
Syntax: C, Length: 1 If the external routine is a function, specify the TIBCO Object Service Broker semantic type of the value returned.
Syntax: C, Length: 1 If the external routine is a function, specify the TIBCO Object Service Broker syntax of the value returned.
Syntax: C, Length: 1 If the external routine is a function, specify the length of the value returned.
Syntax: B, Length: 2 If the external routine is a function, specify the value zero, because Java does not support packed decimal values as a basic type.
Syntax: B, Length: 2 Leave this field empty.
Syntax: C, Length: 8 The point when the external library is unloaded. At present the only valid value is SESSION (that is, the external library must be unloaded when the session ends). Leave this field empty.
Syntax: V, Length: 255 Specify the name of the Java class containing the routine, the name of the routine (that is, the method within the class), and the Java type of the arguments and the return value (if any).
Syntax: V, Length: 255{ <package name> "/" } <class name> "." <method name> "(" <argument types> ")" <return type>where <package name>, <class name> and <method name> are the ASCII equivalents of the UNICODE names of the package, class and method, <argument types> is a (possibly empty) character sequence encoding the Java types of the arguments, and <return type> is an encoding of the return value. The string beginning with left parenthesis and spanning the rest of the specification is called the signature of the method.
This is the standard Java encoding of the signature of a method. Thus, a method taking a Java int as arguments and returning a double could be encoded as shown here:A method taking a character and a double as an argument and returning no value could be encoded as shown here:In the standard encoding of signatures, a character encoding of a Java type can be prefixed by one or more left square brackets ([), which indicate an array of the Java type of dimensions equal to the number of brackets. As TIBCO Object Service Broker does not support array type, the only Java type that can be prefixed in this manner in a LIBNAME value is B (for byte) and then only with at most one occurrence of the bracket. A one-dimensional byte array corresponds to the characters of a TIBCO Object Service Broker string value passed to or from a Java routine.A class type can be encoded with the letter L followed by the fully qualified class name, followed by a semicolon. The only class type supported is the Java class String, which corresponds to TIBCO Object Service Broker strings when passed to or from a Java routine.The Execution Environment uses the value of LIBNAME to instruct the JVM to load the class containing the method, locate the method within the class, and invoke the method, passing arguments to the method and returning a result (if any) to the calling TIBCO Object Service Broker rule.The call of the routine fails if the routine specification in field LIBNAME does not conform to those rules.The single occurrence from the ROUTINES table for the routine ABC follows. In this example USERFUNJ is called as a function.
If your external routine has arguments, to identify the arguments to TIBCO Object Service Broker add a table instance to the ARGUMENTS table. The parameter value for the table instance of the ARGUMENTS table must be the name of the external routine (that is, the value in the NAME field of the ROUTINES table). You can have a maximum of 16 arguments.
The position of the argument in the argument list. The positions must be sequential and start at 1. Also, it must correspond to the sequence of the encoded arguments in the corresponding LIBNAME field.
Syntax: B, Length: 2 The argument name. This is used only by the call-by-name version of the TIBCO Object Service Broker CALL statement, except in the following case: The string “@THIS” has a special meaning if it appears in this field in the first occurrence. The presence of this string indicates that the Java routine is not a static method of its class, that is, it has an implied “this” argument.
Syntax: C, Length: 16 Whether the value of the argument can be changed by the external routine. Must have the value N as Java supports only call-by-value parameter passing.
Syntax: C, Length: 1 The argument semantic data type.
Syntax: C, Length: 1 The argument syntax.
Syntax: C, Length: 1 The argument length.
Syntax: B, Length: 2 The number of digits to the right of the decimal, if any. Must contain zero.
Syntax: B, Length: 2There must be exactly one occurrence (in an instance of table ARGUMENTS corresponding to a Java routine) for each argument encoded in the field LIBNAME of the corresponding occurrence in the ROUTINES table.The data in the occurrences of ARGUMENTS and the arguments encoded in the LIBNAME field must correspond in the following manner:
A valid string field length A valid string field lengthSimilarly, if the return value encoded is not Z, it must match the same fields in the ROUTINES occurrence describing the routine.The call of the routine fails if the routine specification in field LIBNAME and the information in the parameter instance of ARGUMENTS do not conform to these rules.TIBCO Object Service Broker Managing Data for information about how to use the Table Editor.TIBCO Object Service Broker Programming in Rules for information about valid TIBCO Object Service Broker syntax and semantic data types.
![]() |
Copyright © TIBCO Software Inc. All Rights Reserved |