The APL2 Java Interface

Transcribed from the printed issue; not yet reviewed. Read it in the PDF of the issue, page 101

The IBM APL group is working on an exciting new facility: the APL2-Java™ interface. Through this facility, you will be able to call Java programs and have those programs call back to APL2. The new facility will be available in Workstation APL2 Service Level 4.

Calling Java from APL2¶

The APL2-Java interface includes a new associated processor 14 which is used to call Java from APL2. A processor 14 association looks like this:

('Class' 'Signature') 14 ⎕NA 'Surrogate Member'

Where:

• ‘Class’ is the name of a Java class or an instance returned by a constructor
• ‘Signature’ is a description of a Java field’s datatype or a Java method’s arguments and results.
• Member is the name of the Java field or method
• Surrogate is the name to associate with the member. (A surrogate is required if the member name is not a valid APL2 object name. For example, constructors are always named <init> and so always require a surrogate.)

Note: For those readers who do not know Java, please see the Java Language Overview at the end of this article.

Here is an example of using static members of a Java class named Sample.

('Sample' 'I') 14 ⎕NA 'StaticField'
1
StaticField ← 24
('Sample' '(I)I') 14 ⎕NA 'StaticMethod'
1
Added ← StaticMethod 47

Here is an example of using an instance of the Sample Java class

('Sample' '(I)V') 14 ⎕NA 'Constructor <init>'
1
Object ← Constructor 999
(Object '(I)I') 14 ⎕NA 'InstanceMethod'
1
Result ← InstanceMethod 456

Processor 14 includes several built-in external functions that are used to manage the APL2-Java interface. For example, the DeleteLocalRef function is used to delete objects created through Processor 14:

3 14 ⎕NA 'DeleteLocalRef'
DeleteLocalRef Object

Calling APL2 from Java¶

The APL2-Java interface includes several Java classes that enable Java programs to call APL2. Using these classes, Java programs can start APL2 interpreters, associate and create objects in workspaces, execute APL2 expressions, and call APL2 functions.

The Apl2interp class includes constructors that are used to start new APL2 interpreters. For example, the following Java code starts a slave APL2 interpreter:

Apl2interp Slave = new Apl2interp() ;

The Apl2interp class also contains methods for associating names. For example, if you had packaged the GRAPHPAK workspace, you could use the slave interpreter to associate the names PLOT and VIEW.

Slave.Associate("GRAPHPAK","PLOT") ;
Slave.Associate("GRAPHPAK","VIEW") ;

The Apl2object class is used to create and manipulate APL2 workspace objects. The following code creates an object in the slave interpreter’s workspace from a Java array:

int[] Array = {2,34,6,28,19} ;
Apl2object PlotData = new Apl2object(Slave,Array) ;

The Apl2interp class also contains methods for executing APL2 expressions. This code executes the PLOT and VIEW functions:

Slave.Execute("PLOT",PlotData);
Slave.Execute("VIEW") ;

Calling Back to APL2¶

Java programs called through Processor 14 can also call back to the APL2 interpreter. The Processor 14 built-in function GetApl2interp retrieves the instance of the Apl2interp class associated with the current APL2 interpreter. For example, the following code passes the result of GetApl2interp to a Java method:

3 14 ⎕NA 'GetApl2interp'
Signature ← '(Lcom/ibm/apl2/Apl2interp;)V'
('Sample' Signature) 14 ⎕NA 'CallBack'
CallBack GetApl2interp

The CallBack method might look like this:

   public void CallBack(Apl2interp Apl2) {
      Apl2object Message = new Apl2object(Apl2,"Hello") ;
      Apl2.Assign("VAR",Message) ;
      Return ;
      }

The example assigns the character vector ‘Hello’ to a variable named VAR.

Summary¶

The IBM APL Products and Services group is working to transform APL2. Rather than the traditional stand-alone application environment, the new APL2 will fit seamlessly in modern programming environments. Using the new APL2-Java interface, APL2 application developers will be able to leverage the vast wealth of utility packages available through Java. In addition, developers can call APL2 applications from Java code and deploy their applications using mainstream tools such as WebSphere Application Server.

Java Language Overview¶

Java programs are composed of Java classes. Each class performs a service such as file IO, database access, or user interface services. Some classes are built-in to Java; some are built by application developers.

A Java class is similar to an APL workspace. Like a workspace, a class resides in a single file. Also like a workspace, a class can contain variables and functions. And also like a workspace, variables can be global or local. In addition, functions can also be local or global.

Here is a sample class:

public class Sample
{
   public static int StaticField = 0 ;
   public static int StaticMethod(int Argument) {
      return Argument + StaticField ;
   }

   public int InstanceField ;

   public Sample(int InitialValue) {
      this.InstanceField = InitialValue ;
      return ;
   }

   public int InstanceMethod(int Argument) {
      return Argument + InstanceField ;
   }
}

The Java designers decided to use different words for things than we use in the APL community. In Java,

• Public means global
• Private means local
• Field means variable
• Method means function
• Member means either a field or a method.

The first line of the class definition supplies the name of the class, in this case Sample. Everything within the curly braces constitutes the class’s definition.

The keyword public indicates that a field or method is accessible from outside the class.

The first two members are declared static. This means that they exist as soon as the class is loaded and can always be used. They correspond to global variables and functions in an APL workspace.

The next member, InstanceField, is not declared static; this means that it is an “instance” member and can only be used in the contact of an object. To create an object, you must call a special method called a constructor. Constructors have the same name as the class; the fourth item is a constructor. When you call the Sample constructor, an instance of the Sample class is created. Once you have an instance of the class, you can use the instance, also called an object, to access instance fields and methods.

To illustrate, here is some Java code that uses the Sample class:

//* Set the static field
Sample.StaticField = 24 ;

//* Use the static method
int Added = Sample.StaticMethod(47) ;

//* Create an instance of the Sample class, a Sample object
Sample Object = new Sample(999) ;

//* Call the instance method
int Sum = Object.InstanceMethod(456) ;

Notice for static members, you use the name of the class followed by a period and the member name. For instance members, you use the name of a field containing a reference to the instance followed by a period and the member name.

Trademark attribution statements¶

Java and all Java-based trademarks are trademarks of Sun Microsystems, Inc. in the United States, other countries, or both.

IBM, APL2, and WebSphere are trademarks of International Business Machines Corporation in the United States, or other countries, or both.