invoke()

The javaLib.invoke() system function invokes a method on a local Java™ object or class in the EGL Java object space, and can return a value.

For more about the EGL Java object space in which javaLib.invoke() and similar functions operate, see Java access functions. EGL maintains this method of Java access for compatibility with earlier versions. For new code, use the more powerful ExternalType syntax; for more information, see ExternalType part.

Syntax

  javaLib.invoke(
    identifierOrClass javaObjIdOrClass in,
    method STRING in
    {, argument anyEglPrimitive in})
  returns (result anyJavaPrimitive)
identifierOrClass
Any of the following entities can serve as this argument:
  • A Java objID, to call a method on an object in the Java object space.
  • A string, to call a method on a class (a static method). EGL strips single- and double-byte blanks from the beginning and end of the argument value, which is case sensitive.

Your code cannot invoke a method on an object until you have created an identifier for the object. A later example illustrates this point with java.lang.System.out, which refers to a PrintStream object.

method
The case-sensitive name of the method to invoke.

Input can be any variable or expression that is assignment compatible with the STRING type. Single- and double-byte blanks are stripped from the beginning and end of the string.

argument
A value passed to the method.

The Java type-conversion rules are in effect. A cast might be required; see Passing arguments to Java types. To avoid losing precision, use an EGL FLOAT variable for a Java double, and an EGL SMALLFLOAT variable for a Java float. Using one of the other EGL types can result in a rounding error.

The memory area in the invoking program does not change regardless of what the method does.

result
The result field, if present, receives a value from the local Java method.

If the local Java method returns a value, the result field is optional.

The following cases apply:

  • If the returned value is a BigDecimal, BigInteger, byte, short, int, long, float, or double, the result field must be a numeric data type. The characteristics do not need to match the value; for example, a float can be stored in a result field that is declared with no decimal digits. For details on handling overflow, see handleOverflow and overflowIndicator.
  • If the returned value is a Boolean, the result field must be of a numeric primitive type. The value is 1 for true, 0 for false.
  • If the returned value is a byte array, the result field must be of type HEX. For details on mismatched lengths, see Assignments.
  • If the returned value is a String or char, the result field must be of type CHAR, DBCHAR, MBCHAR, STRING, or UNICODE:
    • If the result field is of type MBCHAR, STRING, or UNICODE, the returned value is always appropriate
    • If the result field is of type CHAR, problems can arise if the returned value includes characters that correspond to DBCHAR characters
    • If the result field is of type DBCHAR, problems can arise if the returned value includes Unicode characters that correspond to single-byte characters

    For details on mismatched lengths, see Assignments.

  • If the local Java method does not return a value or returns a null, the following cases apply:
    • No error occurs in the absence of a result field
    • An error occurs at run time if a result field is present; the error is 00001004, as listed later

Example

In the following example, the cast to the Java objID type (via the "as" operator) is required except as noted:
  // invoke the constructor of the Java Date class and
  // assign the new object to the identifier "date"
  javaLib.storeNew("date" as "objID:java", "java.util.Date");

  // invoke the toString method of the new Date object
  // and assign the output (today's date) to the charVar
  charVar = javaLib.invoke("date" as "objID:java", "toString" );

  // assign the standard output stream of the 
  // Java System class to the identifier "systemOut"
  javaLib.storeField("systemOut" as "objID:java", "java.lang.System", "out" );

  // invoke the println method of the output 
  // stream and print today's date
  javaLib.invoke("systemOut" as "objID:java", "println", charVar );
The use of "java.lang.System.out" as the first argument in the previous line is not valid, as the argument must either be an identifier already in the object space or a class name. The argument cannot refer to a static field.

Error considerations

If the v60ExceptionCompatibility program property is not set or set to NO, an exception causes EGL to throw a JavaObjectException. Other errors cause EGL to throw a RuntimeException.

If the v60ExceptionCompatibility program property is set to YES, an error during processing of javaLib.invoke() can set sysVar.errorCode to a value listed in the next table.

Table 1. errorCode values for invoke()
Value in sysVar.errorCode Description
00001000 An exception was thrown by an invoked method or as a result of a class initialization
00001001 The object was null, or the specified identifier was not in the object space
00001002 A public method, field, or class with the specified name does not exist or cannot be loaded
00001003 The EGL primitive type does not match the type expected in Java
00001004 The method returned null, the method does not return a value, or the value of a field was null
00001005 The returned value does not match the type of the return variable
00001006 The class of an argument cast to null could not be loaded
00001007 A SecurityException or IllegalAccessException was thrown during an attempt to get information about a method or field; or an attempt was made to set the value of a field that was declared final
00001009 An identifier rather than a class name must be specified; the method or field is not static

Feedback