ExternalType for Java code

An ExternalType part with the JavaObject stereotype defines how you can access an external Java™ class or interface from your EGL code. The part typically identifies all the public fields, methods, and constructors of the class or interface, but might identify a subset of interest.

Syntax

Syntax diagram for the external type
name
The name of the external type
ExternalType
An external type that the current one extends or implements, depending on whether ExternalType represents a Java class or interface. The external type being defined includes the fields and function prototypes from ExternalType, but not the constructor prototypes.

EGL predefines the Serializable external type, which you can reference if you are defining an external type that is based on a Java class that itself implements the java.io.Serializable interface. If the external type that you are defining does not extend the EGL Serializable external type, any EGL variables that are based on that external type are marked as transient in the generated Java code. Transient variables are not preserved when a Java object is serialized by a runtime platform such as an application server. For example, serialization might occur when the server creates a backup copy of the object in response to a shut down.

property
The following part-level properties are available:
packageName
A string that holds the package name for the external Java class.
javaName
A string that holds the Java class name. This property is optional and defaults to the name of the external type. However, you must specify a custom type name in some cases (for example, if the class name is an EGL reserved word), and in those cases, you must specify the javaName property.
static
An indicator to state that the variable or function is global to the class and is independent of whether the class has any objects. You can access a static variable or function by referencing the external type without referencing an object (for example, MyType.theStaticVariable), or by referencing an object (for example, MyObject.theStaticVariable).
constructorPrototype
An EGL function prototype that corresponds to a Java constructor. You can pass the following kinds of parameters:
  • A primitive-type value. You must specify the in modifier.
  • A dynamic array. You can specify the in, out, or inout modifier.
  • A structured record. You must specify the inout modifier.
functionPrototype
An EGL function prototype that corresponds to a Java method. You can pass the following kinds of parameters:
  • A primitive-type value. You must specify the in modifier.
  • A dynamic array. You can specify the in, out, or inout modifier.
  • A structured record. You must specify the inout modifier.

The function can return a primitive-type value, an array, or no value at all. The function cannot return a record.

variableList
An EGL variable or comma-separated list of EGL variables. Each EGL variable corresponds to a Java field and might be based on a Java primitive, an EGL external type, or an array of primitives or external types.
Variable or function declarations can include the following property:
JavaName
A string that contains the name of the related field or method in the Java class. This property is optional and defaults to the name of the variable or function in the external type. However, you must specify a custom name in some cases (for example, if the field name is an EGL reserved word), and in those cases, you must specify the JavaName property. Here is an example:
Function nextElement() { JavaName = "next" };

Variable declarations can also include the following properties:

@JavaProperty
@JavaProperty indicates that field access in the generated code is provided by method calls, not by direct access to the field. You can use this property without specifying function names if the names of the functions are built with the word “get” or “set” followed by the variable name. For example, if the variable is UpperLimit and the Java class includes functions named getUpperLimit and setUpperLimit, you only need to add the complex property, as in this example:
UpperLimit INT { @JavaProperty{} };
The property fields in @JavaProperty are as follows:
getMethod
A string that contains the name of the get method for the specified variable (do not include parentheses). The method has no parameters, and its return value has the same type as the field.
setMethod
A string that contains the name of the set method for the specified variable (do not include parentheses). The method has one parameter that has the same type as the field. By convention the set method does not have a return value, but no error condition results if the method returns a value.

A field is read only if getMethod is specified but setMethod is not, and a field is write-only if setMethod is defined but getMethod is not. An error occurs if you try to set the value of a read-only field or to get the value of a write-only field.

@eventListener
The @eventListener complex property lets you or your colleagues write an event handler for a Java environment, giving the EGL generator the information needed to create code that conforms to the Java event-listener pattern.

For example, consider the java.beans package, which a Java developer uses to code a kind of Java class typically known as a Java bean or, more simply, a bean. Among its capabilities, a bean can invoke a method of a Java object in response to a runtime event. The rest of this description assumes that the runtime event is a change of a property value in the bean. .

The Java developer registers that type of event by invoking the addPropertyChangeListener method of the bean and by passing a PropertyChangeListener object. In general terms, the PropertyChangeListener object is an event listener.

After a property value changes, the bean calls the event listener. Specifically, the bean calls the propertyChange method of the PropertyChangeListener object and passes a PropertyChangeEvent object that gives details about the change.

A further detail is that the event listener is based on a Java interface, and the propertyChange method is specific to a business application. The EGL developer's use of the @eventListener property means that the EGL-generated propertyChange method invokes logic that is derived from a developer-coded EGL function.

In view of these details, consider the property fields of the @eventListener property:
addMethod
A string that contains the name of the Java method that registers an event listener. Do not include parentheses when identifying the method.

In the current example, the value of addMethod is “addPropertyChangeListener”.

listenerType
A string that contains the name of a Java class that acts as a listener. Include the package name for that class.

In the current example, the value of listenerType is “java.beans.PropertyChangeListener”.

method
A string that contains the name of a Java method that is in the listener and that is invoked when the event occurs.

In the current example, the value of method is “propertyChange”.

Now consider EGL code that defines an external type for a bean named MyBean. The external type includes a field named onPropertyChange, which is based on a Delegate part shown later:
ExternalType MyBean type JavaObject
   onPropertyChange PropertyChangeDelegate
      { @eventListener{ addMethod = "addPropertyChangeListener", 
                        listenerType = "java.beans.PropertyChangeListener", 
                        method = "propertyChange" } };
end

The onPropertyChange field is not in the bean, but is present so that the listener pattern is available in your EGL code, where you assign that EGL function that will be invoked when an event occurs.

In keeping with the propertyChange method, the PropertyChangeDelegate Delegate part has a single parameter, which is an external type that is based on the PropertyChangeEvent object.
Delegate PropertyChangeDelegate( evt PropertyChangeEvent in ) 
end

ExternalType PropertyChangeEvent type JavaObject { packageName = "java.beans" }
   function getPropertyName() returns ( string );
   // You might make available other methods of java.beans.PropertyChangeEvent.
end
To see the use of the MyBean external type, consider the following EGL program:
program MyEGLProgram
   function main()
      mb MyBean{ onPropertyChange = propChange };
   end

   function propChange( evt PropertyChangeEvent in )
      writeStdout( "Property " :: evt.getPropertyName() :: " has changed." );
   end
end

The program creates a variable of type MyBean, assigns a function to the onPropertyChange field of that type, and defines the function itself. When a property value changes in the bean, the function is invoked and uses getPropertyName, which is the one method that was made available from the PropertyChangeEvent object.

Always assign the @eventListener property to a variable that is based on a Delegate part. The characteristics of the Delegate part must conform to an event-handling method such as propertyChange, which is in a specific Java event listener such as PropertyChangeListener.

When you reference Java field and method names in the code, remember that they are case sensitive, even though the equivalent EGL names are not.


Feedback