======Java Objects======

Version 1.1 introduced direct support for creating native Java Objects, invoking both static and instance methods, storing Java Objects in [[Variables]] and passing object references through [[CommandExecution Command Execution]] and [[SyntaxFunctionCall Function Calls]].

Java Objects can be created in xmlsh scripting language or passed in externally via one of the integration API's.
Java Objects may be passed to commands and functions (including user defined modules) as well as set into variables accessible by any xmlsh script code, functions, commands or modules.

All java commands and functions are in the "jnew" commands package. You need to import this package to use the java commands. You can import to the global namespace or choose a namespace.
%%
import commands java
%%

====Creating a Java Object====

To create a Java Object use either the [[FunctionJnew Function jnew]] or the [[CommandJset Command jset]].

For example, to create a Date object and assign it to variable "date" you can either

%%
date=jnew(java.util.Date)
%%

or
%%
jset -v date -c java.util.Date
%%

To see the object has been created properly and of the right type, use the [[CommandXtype Commmand xtype]].

%%
xtype $date
%%

Result
%%
java.util.Date
%%

With jnew you can create Java Objects with non-default constructors.
Example: create an Integer with the value 123

%%
i=jnew(java.lang.Integer 123)
xtype $i
echo $i
%%

Result
%%
java.lang.Integer
123
%%


====Converting To Strings====

To convert an object to a String, simply use it in any string context or pass it as an argument to a command that accepts strings.
( Note this actually converts the object to an XDM string type, not the java String type.
%%
xtype $date
echo $date
xtype "$date"
echo "The date is $date"

%%

Result
%%
Thu Nov 18 16:40:58 EST 2010
xs:string
echo "The date is $date"
%%


To get a real Java java.lang.String object you can use the toString() method ( using the Method Call syntax below)

%%
xtype date.toString()
%%

Result:
%%
java.lang.String
%%

For most uses, xs:string and java.lang.String are interchangable.




====Calling Instance Methods====

Instance methods of a java object in a variable may be called using the instance method syntax.
variable.methodName( [args ...] )

This is similar to the [[SyntaxFunctionCall Function Call Synatx]] except that it calls java instance methods on any object.
The arguments (if any) are expanded identically to function or command calls and the parameter list is then matched against public methods of the object's class to determine a "best match". If more then one matching method is found a method is chosen 'at random'. Method matching follows these rules

* Get a list of methods with the same number of parameters as arguments
* For each method compare the list of actual arguments against the method signature and determine the 'Best Match' by adding the conversions required for each argument.
* If an arguments' class is an exact match for the expected class, add 0
* If an arguments' class can be cast to the expected class, add 1
* If an arguments' class can be "boxed" to the expected class add 2
* If an argument is an XDM value then attempt matching with the Java primitive class coercion of XDM Value (example, an xs:string's Java primitive class is a String)
* The method(s) with the lowest total from the above conversion rules are candidates for invocation
* If more then one method has the same lowest score then pick one method.

After matching methods, a similar process is performed to convert the actual arguments to the expected type for each expected type and the method is called.
The resulting object is returned (or null if void).


Instance methods can also be called using the [[CommandJset jset Command]].

Example
%%
# Create a String object with "Hi There"
s1=jnew(java.lang.String "Hi There")
# Get a substring - use <[ number ]> to force arguments to be xs:integer which is convertable to int
s2=s1.substring( <[3]> <[6]> )
echo $s2
%%

Result
%%
The
%%





----
[[Functions]]
[[Commands]]
[[FunctionJnew jnew Command]]
[[CommandJset jset Command]]