💾 Archived View for blitter.com › apl-books › APLX50 › APLX-manual › www.microapl.com › apl_help › c… captured on 2023-01-29 at 14:37:59.
⬅️ Previous capture (2022-07-17)
-=-=-=-=-=-=-
<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.0 Transitional//EN">
<HTML>
<HEAD>
<TITLE>Using External Classes</TITLE>
<META NAME="DESCRIPTION" CONTENT="APL language help page: Using External Classes">
<META NAME="KEYWORDS" CONTENT="classes,.Net,Java,Ruby,external classes,apl,aplx,apl help">
<!-- %%COMMON_HEAD%% -->
<META http-equiv="Content-Type" content="text/html; charset=utf-8">
<LINK rel="stylesheet" type="text/css" href="http://www.microapl.com/styles_apl_help.css">
<!-- %%END%%-->
</HEAD>
<body>
<table>
<tr>
<td width="800" valign="top" colspan="2">
<center>Topic: <A HREF="ch.htm">APLX Help</A> : <A HREF="ch_070.htm">Interfacing to other languages</A> : <A HREF="ch_070_020.htm">Using external classes</A>
</center>
<center>
[<A HREF="ch_070_030.htm">Next</A> | <A HREF="ch_070_010.htm">Previous</A> | <A HREF="ch.htm">Contents</A> | <A HREF="help_index.htm">Index</A> | <A HREF="http://www.microapl.co.uk/apl/index.html">APL Home</A> ]</center>
<br></td>
</tr>
<tr>
<td width="120">
<a href="http://www.microapl.co.uk/apl/index.html"><img height="68" border="0" width="119" src="MicroAPL_logo.gif" alt="www.microapl.co.uk"></a>
</td>
<td align="left" valign="bottom">
<h1>Using External Classes</h1>
</td>
</tr>
<tr>
<td width="800" valign="top" colspan="2">
<hr>
<H2>Introduction</H2>
<p>Modern object-oriented language frameworks such as Java, .Net and Ruby provide a consistent mechanism for exploring class libraries, discovering what classes are defined in the library, and detailing the class methods and properties. This allows objects to be created and used from outside the specific environment in which they were written. (These facilities, which provide so-called <i>metadata</i> about a given class together with the ability to create new classes at runtime, are sometimes described by the term <i>Reflection</i>.)</p>
<p>The underlying object-oriented model in APLX is broadly similar to that of the .Net languages, Java, or Ruby. This makes it possible to access all the powerful facilities of the .Net and Java class libraries, as well as custom software written in the mainstream object-oriented languages in use today, directly from APLX.</p>
<H2>Creating instances of external classes</H2>
<p>You can create instance of external classes in much the same way as you create instances of APL (user-defined) classes, by means of the system function <A HREF="ch_020_070_505.htm"><code>⎕NEW</code></A>. The right argument of <code>⎕NEW</code> can be either a class reference (which is typically the case when an APL user-defined class is being used), or a class name as a character vector. In the latter case, the optional left argument of <code>⎕NEW</code> determines the environment in which the class is to be found. For example:</p>
<p>Create an instance of the .Net <tt>DateTime</tt> class, defined in the .Net class libraries, specifying the initial date to the constructor of that class:</p>
<pre> NETDATE←'.net' ⎕NEW 'System.DateTime' 2007 6 20 9 32 3
</pre>
<p>Create an instance of the Ruby DateTime class, defined in the Ruby class libraries:</p>
<pre> RUBYDATE←'ruby' ⎕NEW 'DateTime' 2007 6 20 9 32 3</pre>
<p>Create an array of complex numbers in the R statistical language:</p>
<pre> C←'r' ⎕NEW 'complex' (3 2⍴(1 2) (3 4) (5 6) (7 8) (9 10) (11 12))</pre>
<p>The left argument to <code>⎕NEW</code> is the environment identifier. For external classes, it corresponds to a shared library or DLL, as follows:</p>
<H3>For 32-bit implementations of APLX:</H3>
<table border="1">
<tr>
<td><b><i>Left arg</i></b></td>
<td><b><i>Environment</i></b></td>
<td><b><i>Windows DLL</i></b></td>
<td><b><i>Macintosh bundle</i></b></td>
<td><b><i>Linux shared library</i></b></td>
</tr>
<tr>
<td>(Omitted)</td>
<td>User-defined APL class</td>
<td>None</td>
<td>None</td>
<td>None</td>
</tr>
<tr>
<td><code>'⎕'</code></td>
<td>System class</td>
<td>None</td>
<td>None</td>
<td>None</td>
</tr>
<tr>
<td><code>'.net'</code></td>
<td>Microsoft .Net</td>
<td><tt>aplxobj_net.dll</tt></td>
<td>Not supported</td>
<td>Not supported</td>
</tr>
<tr>
<td><code>'java'</code></td>
<td>Java</td>
<td><tt>aplxobj_java.dll</tt></td>
<td><tt>aplxobj_java.bundle</tt></td>
<td><tt>aplxobj_java.so</tt></td>
</tr>
<tr>
<td><code>'r'</code></td>
<td>R</td>
<td><tt>aplxobj_r.dll</tt></td>
<td><tt>aplxobj_r.bundle</tt></td>
<td><tt>aplxobj_r.so</tt></td>
</tr>
<tr>
<td><code>'ruby'</code></td>
<td>Ruby</td>
<td><tt>aplxobj_ruby.dll</tt></td>
<td><tt>aplxobj_ruby.bundle</tt></td>
<td><tt>aplxobj_ruby.so</tt></td>
</tr>
<tr>
<td>Other</td>
<td>Customized environment</td>
<td><tt>aplxobj_XXX.dll</tt></td>
<td><tt>aplxobj_XXX.bundle</tt></td>
<td><tt>aplxobj_XXX.so</tt></td>
</tr>
</table>
<H3>For 64-bit implementations of APLX:</H3>
<table border="1">
<tr>
<td><b><i>Left arg</i></b></td>
<td><b><i>Environment</i></b></td>
<td><b><i>Windows DLL</i></b></td>
<td><b><i>Linux shared library</i></b></td>
</tr>
<tr>
<td>(Omitted)</td>
<td>User-defined APL class</td>
<td>None</td>
<td>None</td>
</tr>
<tr>
<td><code>'⎕'</code></td>
<td>System class</td>
<td>None</td>
<td>None</td>
</tr>
<tr>
<td><code>'.net'</code></td>
<td>Microsoft .Net</td>
<td><tt>aplx64obj_net.dll</tt></td>
<td>Not supported</td>
</tr>
<tr>
<td><code>'java'</code></td>
<td>Java</td>
<td><tt>aplx64obj_java.dll</tt></td>
<td><tt>aplx64obj_java.so</tt></td>
</tr>
<tr>
<td><code>'r'</code></td>
<td>R</td>
<td><tt>aplx64obj_r.dll</tt></td>
<td><tt>aplx64obj_r.so</tt></td>
</tr>
<tr>
<td><code>'ruby'</code></td>
<td>Ruby</td>
<td><tt>aplx64obj_ruby.dll</tt></td>
<td><tt>aplx64obj_ruby.so</tt></td>
</tr>
<tr>
<td>Other</td>
<td>Customized environment</td>
<td><tt>aplx64obj_XXX.dll</tt></td>
<td><tt>aplx64obj_XXX.so</tt></td>
</tr>
</table>
<p>What actually happens 'under the hood' here is that user-defined and system classes are handled directly by the APLX interpreter. Operations to create and use object classes written in other environments are passed to the external library (Windows dynamic link library, Macintosh bundle, or Linux shared library) whose name is given in the table. This provides an extensible interface, allowing further environments to be added in the future. For example, to add an interface to Mono (the open-source equivalent of .Net) it would not be necessary to change the APLX interpreter at all; all that would be required is to supply a new interface library <tt>aplxobj_mono.dll</tt>.</p>
<p>It is also possible to create instances of external classes by using a class reference rather than a character vector as the right argument to <code>⎕NEW</code>, but first you need to obtain the reference from the external system using the <A HREF="ch_020_070_345.htm"><code>⎕GETCLASS</code></A> system function:</p>
<pre> NETDATECLASS←'.net' ⎕GETCLASS 'System.DateTime'
NETDATE←⎕NEW NETDATECLASS 2007 6 20 9 32 3
</pre>
<p>Obtaining and using a class reference can be much more efficient than supplying a class name to <code>⎕NEW</code> if you need to create a large number of objects.</p>
<H2>Customized interfaces</H2>
<p>As well as being extensible to further public object-oriented environments, the mechanism also allows the same APL syntax to be used for accessing custom class libraries written in languages (such as C++) which do not support metadata and Reflection. For example, if a financial institution wanted to make use of a timeseries analysis class library written in C++, it could write a simple interface DLL <tt>aplxobj_ts.dll</tt> which would allow classes contained in that library to be used from APL:</p>
<pre> TS←'ts' ⎕NEW 'TimeSeries'
</pre>
<p>The APLX interpreter, seeing this line, would pick up the environment identifier <tt>'ts'</tt> which would cause it to search for <tt>aplxobj_ts.dll</tt> to handle the creation and use of the classes within the custom library. Unlike the generalized interfaces to .Net, Java, and Ruby, this custom interface would of course support only the specific set of classes for which it had been written, with the names and other details of the supported classes and their methods hard-coded into the interface DLL rather than being obtained at runtime. Nonetheless, it is a powerful extension of the ability of APL to use external code.</p>
<H2>Calling methods and accessing properties</H2>
<p>Once you have a reference to an object, you can use a consistent syntax to access its methods and properties. It makes no difference whether the object is an instance of an internal APL class, or of an external Ruby, Java, or .Net class. For external calls, the APL interpreter automatically marshals any parameters supplied to the form required by the external class method (assuming that such a conversion is possible). For example, if the method requires a parameter which is of type signed 16-bit integer, the APL interpreter will convert any supplied binary, integer, or floating-point data type to the required 16-bit form, provided that the number is integral and is in range. Where the required parameter is a string, APLX will automatically convert from an APL character vector. Where the required parameter is itself an object reference, the user can supply an APL reference to an object (in the same environment, of course - you cannot pass a Ruby object reference to a .Net method).</p>
<p>The information which allows this conversion to happen successfully is the metadata which describes the external class. Depending on the external environment, you can see this metadata in human-readable form by using the system method <A HREF="ch_020_080_060.htm"><code>⎕DESC</code></A>, which is like <code>⎕NL</code> except that it returns types for properties, and the prototypes of methods: </p>
<pre> NETDATE.⎕DESC 3
System.String ToString()
System.String ToString(System.String)
System.String ToString(System.IFormatProvider)
System.String ToString(System.String, System.IFormatProvider)
System.Type GetType()
System.DateTime Add(System.TimeSpan)
System.DateTime AddDays(Double)
System.DateTime AddHours(Double)
... etc</pre>
<p>This means, for example, that the AddDays method of the .Net <tt>System.DateTime</tt> class takes a double-precision floating point value as an argument, and returns a new <tt>DateTime</tt> object which represents the original date-time value plus the number of days (or parts of days). We can see this by calling the method with a suitable parameter, but without assigning the result:</p>
<pre> NETDATE.AddDays 1
[.net:DateTime]</pre>
<p>What has happened here is that the .Net class library has created a new <tt>DateTime</tt> object, and a reference to it has been passed back to APL. Because we have not assigned or used the object reference, the default display form of the object has been written to the session window, and the object has then been deleted.</p>
<p>To display the date/times for exactly one, two, and three days following, we can use the APL 'each' operator to run the <tt>AddDays</tt> method three times, with three separate arguments, and then run the <A HREF="ch_020_080_080.htm"><code>⎕DS</code></A> method on each of the three new temporary <tt>DateTime</tt> objects which will be returned:</p>
<pre> (NETDATE.AddDays¨⍳3).⎕DS
21/06/2007 09:32:03 22/06/2007 09:32:03 23/06/2007 09:32:03
</pre>
<p>Properties are handled in a similar way to methods, although not all external classes really have properties as such; some only have 'getter' and 'setter' functions. You can read properties back directly, and assign to them using the normal APL assignment arrow.</p>
<H2>Calling 'static' methods</H2>
<p>Object-oriented languages like C# and Java include support for so-called <i>static</i> or <i>shared</i> class methods. These are methods which belong to a class but which do not manipulate an individual object. You can call these static methods from APLX in one of two ways:</p>
<ul>
<li><p>If you have an object of the appropriate class, or a reference to the class, you can call the static method as though it were a normal object method. The object is just ignored when the call is made.</p></li>
<li><p>Alternatively, you can use the <A HREF="ch_020_070_095.htm"><code>⎕CALL</code></A> system function. As an example, consider the Java class 'java.lang.Integer', which includes a static method to convert an integer into a binary string. You can call it from APLX as follows:</p>
<pre> 'java' ⎕CALL 'java.lang.Integer.toBinaryString' 37
100101</pre>
</li>
</ul>
<H2>Overloaded methods and syntactic ambiguity</H2>
<p>One common feature of modern object-oriented languages is that they support <i>overloaded</i> methods, that is to say the same method name is used for more than one method, but with different numbers or types of arguments. An example is shown above in the <code>⎕DESC</code> listing of methods for the .Net <tt>System.DateTime</tt> object; there are four versions of <tt>ToString()</tt>, one of which takes no arguments, two of which take a single argument of different types, and one of which takes two arguments.</p>
<p>Normally, APLX is able to handle this unambiguously by examining the parameters supplied, and choosing the correct match amongst the possible overloaded methods. Ambiguities are sometimes possible, however. The most important of these is the use of strand notation with niladic methods.</p>
<p>Consider the following line of traditional APL:</p>
<pre> FORMAT 'THIS STRING'</pre>
<p>It is impossible, looking at this line in isolation, to know whether this is a call to a monadic function <tt>FORMAT</tt> with <tt>'THIS STRING'</tt> as the argument, or is a reference to a variable <tt>FORMAT</tt>, or is a call to a niladic function <tt>FORMAT</tt>. In the latter two cases, the returned data would be joined with the character vector <tt>'THIS STRING'</tt> to produce a length-2 nested vector.</p>
<p>In traditional APL, the interpreter is able to resolve this ambiguity by looking at the type of the symbol <tt>FORMAT</tt>. The same name cannot simultaneously refer both to a monadic function, and to a niladic function or a variable. </p>
<p>When calling an external method, it would in many cases be possible to resolve the ambiguity in the same way. However, if the method is overloaded and exists in a form which take no arguments as well as in a form which takes arguments, it may not be possible to know which was intended.</p>
<p>APLX therefore assumes that <b><i>if an external method call syntactically could take arguments, then it does take arguments</i></b>. Hence, the line:</p>
<pre> NETDATE.ToString TEXT</pre>
<p>(where <tt>TEXT</tt> is a character vector) is always assumed to be a call to the version of <tt>ToString()</tt> which takes a <tt>String</tt> argument (the second form in the list), not to any niladic version of <tt>ToString()</tt>.</p>
<p>If you really want to call the niladic version of the method, and join the result to the variable <tt>TEXT</tt>, then you can force this behavior by using parentheses:</p>
<pre> (NETDATE.ToString) TEXT
</pre>
<p>Note that you cannot, in APL, tell the difference syntactically between a call to a niladic function or method, and a reference to a variable or property. The interface code will examine the metadata to make the right call. Note also that only internal APL user-defined methods can be dyadic functions, or APL operators.</p>
<H2>Object lifetimes and garbage collection</H2>
<p>Internally, APLX uses a reference-count method to ensure that objects are deleted when they are no longer needed (this is supplemented by special code to handle the problem of circular references, which might otherwise make it impossible to delete certain objects). Most of the external object-oriented environments which APLX interfaces to, including .Net, Ruby and Java, use a mark-and-sweep garbage collect system. In this system, a periodic sweep through memory is carried out to find all objects which are no longer referenced, and which therefore can be deleted.</p>
<p>The approach taken is for APLX to be the arbiter of object lifetimes. When an external object is created (either explicitly using <code>⎕NEW</code>, or as a result of some other operation), a reference to the external object is retained in the external environment (for example, the .Net runtime), and a copy of this reference is passed back to the APL interpreter. Because there is a reference to the object held in memory in the external environment, it will not be deleted by the mark-and-sweep garbage collect.</p>
<p>When APL's own reference count for the object falls to zero, APL deletes from the workspace its own data structure which describes the external object. Just before doing this, it calls the external sub-system to indicate that the object is no longer needed. Any cleaning-up required before deletion is then done, and the local reference to the object is deleted or replaced by a NULL. As a result, when the next garbage collect takes place in the external system, the memory used by the object will be reclaimed (unless of course there is another reference to the same object somewhere else in the external system).</p>
<p>For cases where the external environment does not use a garbage-collect system (for example, a custom interface to a class library in C++), the mechanism is similar; the only difference is that when APL notifies the external interface that the object is no longer needed, the external interface carries out an explicit delete rather than relying on replacing the reference with a NULL.</p>
<p>A special case arises if a reference to an external object is saved, for example when you <tt>)SAVE</tt> the workspace. When you re-load the workspace, the saved reference is no longer valid. APLX will issue a warning and set it to NULL.</p>
<H2>Issues with naming conventions</H2>
<p>One problem which arises with trying to unify the way in which external classes are accessed is that of naming conventions. For example, Ruby allows question marks and exclamation marks in method names. To work around this problem, the $ character can be used as an escape character in external names. It has the effect of treating the next character as part of the name. (If you are interfacing to a language in which $ itself is a valid character in a name, you can escape the dollar itself by writing $).</p>
<H2>Errors reported from the external environment</H2>
<p>If the external environment raises an error (or <i>exception</i>), APLX will normally try to print the error message or exception text on the session window, and then raise an APL error (typically DOMAIN ERROR). For example:</p>
<pre> f←'ruby' ⎕new 'ftp'
#<NameError: uninitialized constant ftp>
DOMAIN ERROR
f←'ruby' ⎕new 'ftp'
^
f←'.net' ⎕NEW 'ftp'
Class ftp not found in current search list
DOMAIN ERROR
f←'.net' ⎕NEW 'ftp'
^
dt←'.net' ⎕NEW 'DateTime' 'Bastille day'
Constructor on type 'System.DateTime' not found.
DOMAIN ERROR
dt←'.net' ⎕NEW 'DateTime' 'Bastille day'
^
</pre>
<p>For most external environments, you can find out more about what caused the the exception by using the <A HREF="ch_020_070_405.htm"><code>⎕LE</code> Last Exception</A> system function.</p>
<H2>Inheriting from external classes</H2>
<p>Your own classes (written in APL) cannot inherit directly from an external class. However, you can achieve much the same result by using <A HREF="ch_020_010_162.htm"><code>mixins</code></a>, which allow you to 'mix in' the properties and methods of one or more external classes into your APL objects.</p>
<hr>
</td>
</tr>
<tr>
<td width="800" valign="top" colspan="2">
<center>Topic: <A HREF="ch.htm">APLX Help</A> : <A HREF="ch_070.htm">Interfacing to other languages</A> : <A HREF="ch_070_020.htm">Using external classes</A>
</center>
<center>
[<A HREF="ch_070_030.htm">Next</A> | <A HREF="ch_070_010.htm">Previous</A> | <A HREF="ch.htm">Contents</A> | <A HREF="help_index.htm">Index</A> | <A HREF="http://www.microapl.co.uk/apl/index.html">APL Home</A> ]</center>
<br></td>
</tr>
</table>
<!-- %%COMMON_BODY_TAIL%% -->
<p class="copyright">Copyright © 1996-2010 MicroAPL Ltd</p>
<!-- %%END%% -->
</body>
</html>