## 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

Topic: APLX Help : Interfacing to other languages : Interfacing to Java

[Next | Previous | Contents | Index ]