Interfacing to Java

Specifying a call to the Java environment

You can interface to Java by supplying 'java' as the environment string (left argument) for ⎕NEW, ⎕GETCLASS, or ⎕CALL. These system functions will allow you to create an instance of a Java class, or to call a Java static mathod.

Setting Java options

You can set various options for the Java virtual machine by using the system function ⎕SETUP. For example, you can specify a particular Java Virtual Machine should be used, and set the class library path.

See the documentation on ⎕SETUP for details on controlling the Java environment.

Conversion of Java data types to APL data

APLX by default applies the following data conversion rules to data returned from Java:

• Any Java numeric types (byte, int, long, float, double, etc) are converted to APL integers or floats. 64-bit integers are converted to APL floats on 32-bit platforms, to APL integers on 64-bit platforms.

• Java booleans are converted to APL binary values 0 or 1

• Java Strings and Chars are converted to APL character arrays, translated from Unicode to APLX internal representation. (Any characters which do not appear in the APLX character set are converted to question marks.)

• Simple Java arrays are converted to APL arrays, with individual elements converted as above.

Anything else is left as an object in the Java environment, and a reference to the object is returned to APL.

There are some special cases to consider. The data might not be convertible at all, or it might lose precision in the conversion. To handle cases like this, APLX provides the ⎕REF system method. This forces the data to remain as a Java object. You can then call Java methods appropriate to the data type.

An example which cannot be represented at all is where a Java Double contains a NaN (Not A Number). APL does not handle NaNs, so it cannot be converted to an APL floating-point value. Instead, NaNs are left as Java objects. If you try to use the data in an APL expression, you will get a DOMAIN ERROR, but you can see that it is a NaN and use Java methods on it.

Using the Java interface from multiple APL tasks

Because it is not safe to call the Java virtual machine from multiple threads, you cannot use the Java interface from more than one APL task at a time. If you try to do so, you will get an error message and a DOMAIN error:

      'java' ⎕NEW 'java.util.Date'
Java Virtual Machine (JVM) is already in use by another APL task
DOMAIN ERROR
      'java' ⎕NEW 'java.util.Date'
      ^

The lock will be cleared when the APL task which has been accessing Java executes a )CLEAR, )LOAD, or )OFF.

Example

      ∇DEMO_TimeZone;date;tzclass;tz;dateFormat;dateList
[1]  ⍝ Demonstration of using a TimeZone object in Java
[2]  ⍝
[3]  ⍝ First create a date
[4]   date←'java' ⎕NEW 'java.util.Date'
[5]  ⍝
[6]  ⍝ What is the date?
[7]   'Result of date.toString: ',date.toString
[8]   ''
[9]  ⍝ To create a TimeZone object we need to call a static
[10] ⍝ method in the TimeZone class
[11]  tzclass←'java' ⎕GETCLASS 'java.util.TimeZone'
[12]  tz←tzclass.getTimeZone 'America/Los_Angeles'
[13] ⍝
[14] ⍝ Could also call the static method directly...
[15]  tz←'JAVA' ⎕CALL 'java.util.TimeZone.getTimeZone' 'America/Los_Angeles'
[16] ⍝
[17] ⍝ Does this time zone use daylight savings time?
[18]  'Result of tz.useDaylightTime: ',tz.useDaylightTime
[19]  ''
[20] ⍝ What is the time zone called with and without daylight savings time?
[21]  'Result of tz.getDisplayName: ',tz.getDisplayName 1(tz.LONG)
[22]  'Result of tz.getDisplayName: ',tz.getDisplayName 0(tz.LONG)
[23]  ''
[24] ⍝ What is the current date/time in our local time zone?
[25] ⍝ We create a SimpleDateFormat object to format the date
[26]  dateFormat←'java' ⎕NEW 'java.text.SimpleDateFormat' 'EEE, d MMM yyyy HH:mm
      :ss, zzzz'
[27]  'Today''s local date/time is: ',dateFormat.format date
[28] ⍝
[29] ⍝ What's the same date/time in Los Angeles?
[30]  dateFormat.setTimeZone tz
[31]  'In Los Angeles, that''s: ',dateFormat.format date
[32]  ''
[33] ⍝
[34] ⍝ Let's make 12 dates with different months
[35]  dateList←date.⎕CLONE 12
[36]  dateList.setMonth((⍳12)-⎕IO)
[37] ⍝
[38] ⍝ Format each of these dates for Los Angeles time
[39]  'Here are some more dates with the month changed:'
[40]  12 1⍴dateFormat.format¨dateList
[41]  ∇

This produces the following output:

Result of date.toString: Tue Nov 20 14:37:36 GMT 2007

Result of tz.useDaylightTime:  1

Result of tz.getDisplayName: Pacific Daylight Time
Result of tz.getDisplayName: Pacific Standard Time

Today's local date/time is: Tue, 20 Nov 2007 14:37:36, Greenwich Mean Time
In Los Angeles, that's: Tue, 20 Nov 2007 06:37:36, Pacific Standard Time


Here are some more dates with the month changed:
 Sat, 20 Jan 2007 06:37:36, Pacific Standard Time
 Tue, 20 Feb 2007 06:37:36, Pacific Standard Time
 Tue, 20 Mar 2007 07:37:36, Pacific Daylight Time
 Fri, 20 Apr 2007 06:37:36, Pacific Daylight Time
 Sun, 20 May 2007 06:37:36, Pacific Daylight Time
 Wed, 20 Jun 2007 06:37:36, Pacific Daylight Time
 Fri, 20 Jul 2007 06:37:36, Pacific Daylight Time
 Mon, 20 Aug 2007 06:37:36, Pacific Daylight Time
 Thu, 20 Sep 2007 06:37:36, Pacific Daylight Time
 Sat, 20 Oct 2007 06:37:36, Pacific Daylight Time
 Tue, 20 Nov 2007 06:37:36, Pacific Standard Time
 Thu, 20 Dec 2007 06:37:36, Pacific Standard Time