expecco Wiki (Version 25.x) - Benutzerbeiträge [de]

DOT NET Interface Library v2

2017-03-15T13:28:27Z

Javogel:

== Overview ==

The .NET Interface Library (".NET Bridge") contains a mechanism to access Microsoft .NET (CLR) objects of a local or remote .NET application (a so-called .NET bridge), and an API for elementary blocks and a library of blocks to interact with these objects.

== Programmatic Interface ==

Access to .NET objects, classes and programs is done via a framework called "dotNET-Bridge". This framework implements transparent forwarding of expecco messages (virtual function calls) from either Smalltalk or JavaScript code to .NET objects as existent in a local or remote .NET virtual machine. Also, return values, callBacks and exception information are passed back from the .NET program to expecco. A proxy-object mechanism which catches all function calls, wraps the arguments and sends a datagram to the other bridge side is used for this to be almost completely transparent to the Smalltalk/JavaScript code inside expecco.

In addition to existing blocks of the .NET Interface Library, programmatic access to dotNET objects is sometimes useful or required. So the following information is useful if you want to write your own elementary .NET-blocks, or if you have to enhance the existing library by adding application-specific interface blocks.

=== Initializing / Releasing the Bridge ===

Before any communication can take place between expecco and any dotNet object, the .NET side of the bridge has to be started, and a communication path to be setup.
All of the bridges classes are in the <CODE>DOTNET</CODE> namespace; the main interface class is <CODE>DotNet</CODE>, in this namespace:

<CODE><PRE>
dotNetHandle := DOTNET::DotNet newWithServer.
</PRE></CODE>
or (in JavaScript):
<CODE><PRE>
dotNetHandle = DOTNET::DotNet.newWithServer();
</PRE></CODE>

This starts the .NET-side of the bridge (the executable named "DotNetBridge.Server.exe"),
and waits for a connection request from this program.

When finished, release the bridge with:
<CODE><PRE>
dotNetHandle.close();
</PRE></CODE>
which shuts down the connection and terminates the executable.

=== Loading Assemblies ===
Using the "loadLibrary"-function, wellknown assemblies can be loaded:
<CODE><PRE>
dotNetHandle.loadLibrary("System.Windows.Forms");
</PRE></CODE>
or:
<CODE><PRE>
dotNetHandle.loadLibrary("user32.dll");
</PRE></CODE>

Arbitrary files which contain assemblies are loaded with:
<CODE><PRE>
dotNetHandle.loadFile(pathToDLL);
</PRE></CODE>
or:
<CODE><PRE>
dotNetHandle.loadExtension(pathToDLL);
</PRE></CODE>
the former loads an assembly from the machine running the bridge server (DotNetBridge.Server.exe), the latter loads it from the machine running expecco.
loadExtension also makes loaded assemblies available to dynamically compiled VB/C# compilation units.

=== Accessing Globals ===

Globals, nameSpaces and members of a namespace are accessed using message sends to the dotNet handle, where the message name is the name of the global, namespace or interface.
These messages can be chained, to access a hierarchy of namespaces.
For example:
<CODE><PRE>
dotNetHandle.System.Reflection.Assembly.LoadFile("c:\foo\bar\myAssembly.dll");
</PRE></CODE>

=== Instantiating a Class ===

Object instances are created via the "new"-message, sent to a global:
<CODE><PRE>
b = dotNetHandle.Button.new();
f = dotNetHandle.Form.new();
</PRE></CODE>
once instanciated, any message can be sent transparently to such an .NET object, as if it was an expecco object:
<CODE><PRE>
b.text("Hello World");
f.controls.add(b);
f.showDialog();
</PRE></CODE>

=== Callbacks ===

Callbacks from .NET back into expecco are implemented via Smalltalk blocks (JavaScript anonymous functions).
The bridge automatically installs an appropriate callback, whenever a block/function is given to a .NET component as a callback or hook.

Here is a complete example for creating a .NET form with a callback into expecco. This code could be put into an EB (Elementary Block) of an expecco activity diagram:
<CODE><PRE>
var dotNet, form, button;

// called when the .NET button is clicked
function callBack() {
dotNet.MessageBox.show("Hello from expecco");
};

dotNet = DOTNET::DotNet.newWithServer();
dotNet.loadLibrary("System.Windows.Forms");

button = dotNet.Button.new();
button.text("Hello");
button.click.add( callBack );

form = dotNet.Form.new();
button.dock( dotNet.DockStyle.fill );
form.controls.add( button );

form.showDialog();

dotNet.close();
</PRE></CODE>

=== Remote Dynamic Code Injection ===

C# and VB code can be dynamically loaded and compiled:

C#:
<CODE><PRE>
typeCode := '
using System;

namespace SomeNamespace
{
class SomeClass
{
public static void ConsoleWrite(string text)
{
Console.Write(text)
}
}
}
'.
typeObject := dotnet getDotNetType:'SomeNamespace.SomeClass' fromCSharpSource:typeCode.
typeObject ConsoleWrite:'Hello, World!'.
</PRE></CODE>

VB:
<CODE><PRE>

moduleCode := '
Imports System

Namespace SomeNamespace
Public Module SomeModule
Sub ConsoleWrite(ByVal text As String)
Console.WriteLine (text)
End Sub
End Module
End Namespace
'.
moduleObject := dotnet getDotNetType:'SomeNamespace.SomeModule' fromVBSource:moduleCode.
moduleObject ConsoleWrite:'Hello, World!'.
</PRE></CODE>

=== Calling ActiveX/COM Objects===

It's possible to make calls to ActiveX/COM Objects through the bridge.

To do this, you need to create a dotNet Assembly with the types from a .tlb or .ocx file.

This can be done with the tlbimp utility which is part of VisualStudio (reachable through the VS Dev CMD Shell...)

In this shell, you can e.g. execute

tlbimp c:\windows\system32\wshom.ocx

which will create a file called IWshRuntimeLibrary.dll for the Windows Script Host Runtime Library in the current directory. This can then be used to automate the Windows Script Host Runtime Library Object.

Here an example howto use this in code:

<CODE><PRE>

|dotNet shell buttonPressed|

dotNet := DotNet singletonInstance.
dotNet loadFile:'C:\Temp\IWshRuntimeLibrary.dll'.
shell := dotNet WshShellClass new.
buttonPressed := shell popup:'Hello from Micha' secToWait:15 title:'.NET Bridge Com Demo' type:0.
buttonPressed inspect

</PRE></CODE>

to be continued

== See Also==
The [[Java Interface Library v2| Java Interface Plugin & Library]], which implements a likewise interface for Java applications/libraries.

<hr>
Back to [[Plugins]] 
Back to [[OnlineDocumentation#Library and Plugin Overview|Online Documentation]].

DOT NET Interface Library v2

2017-03-15T13:19:09Z

Javogel:

== Overview ==

The .NET Interface Library (".NET Bridge") contains a mechanism to access Microsoft .NET (CLR) objects of a local or remote .NET application (a so-called .NET bridge), and an API for elementary blocks and a library of blocks to interact with these objects.

== Programmatic Interface ==

Access to .NET objects, classes and programs is done via a framework called "dotNET-Bridge". This framework implements transparent forwarding of expecco messages (virtual function calls) from either Smalltalk or JavaScript code to .NET objects as existent in a local or remote .NET virtual machine. Also, return values, callBacks and exception information are passed back from the .NET program to expecco. A proxy-object mechanism which catches all function calls, wraps the arguments and sends a datagram to the other bridge side is used for this to be almost completely transparent to the Smalltalk/JavaScript code inside expecco.

In addition to existing blocks of the .NET Interface Library, programmatic access to dotNET objects is sometimes useful or required. So the following information is useful if you want to write your own elementary .NET-blocks, or if you have to enhance the existing library by adding application-specific interface blocks.

=== Initializing / Releasing the Bridge ===

Before any communication can take place between expecco and any dotNet object, the .NET side of the bridge has to be started, and a communication path to be setup.
All of the bridges classes are in the <CODE>DOTNET</CODE> namespace; the main interface class is <CODE>DotNet</CODE>, in this namespace:

<CODE><PRE>
dotNetHandle := DOTNET::DotNet newWithServer.
</PRE></CODE>
or (in JavaScript):
<CODE><PRE>
dotNetHandle = DOTNET::DotNet.newWithServer();
</PRE></CODE>

This starts the .NET-side of the bridge (the executable named "DotNetBridge.Server.exe"),
and waits for a connection request from this program.

When finished, release the bridge with:
<CODE><PRE>
dotNetHandle.close();
</PRE></CODE>
which shuts down the connection and terminates the executable.

=== Loading Assemblies ===
Using the "loadLibrary"-function, wellknown assemblies can be loaded:
<CODE><PRE>
dotNetHandle.loadLibrary("System.Windows.Forms");
</PRE></CODE>
or:
<CODE><PRE>
dotNetHandle.loadLibrary("user32.dll");
</PRE></CODE>

Arbitrary files which contain assemblies are loaded with:
<CODE><PRE>
dotNetHandle.loadFile(pathToDLL);
</PRE></CODE>
or:
<CODE><PRE>
dotNetHandle.loadExtension(pathToDLL);
</PRE></CODE>
the former loads an assembly from the machine running the bridge server (DotNetBridge.Server.exe), the latter loads it from the machine running expecco.

=== Accessing Globals ===

Globals, nameSpaces and members of a namespace are accessed using message sends to the dotNet handle, where the message name is the name of the global, namespace or interface.
These messages can be chained, to access a hierarchy of namespaces.
For example:
<CODE><PRE>
dotNetHandle.System.Reflection.Assembly.LoadFile("c:\foo\bar\myAssembly.dll");
</PRE></CODE>

=== Instantiating a Class ===

Object instances are created via the "new"-message, sent to a global:
<CODE><PRE>
b = dotNetHandle.Button.new();
f = dotNetHandle.Form.new();
</PRE></CODE>
once instanciated, any message can be sent transparently to such an .NET object, as if it was an expecco object:
<CODE><PRE>
b.text("Hello World");
f.controls.add(b);
f.showDialog();
</PRE></CODE>

=== Callbacks ===

Callbacks from .NET back into expecco are implemented via Smalltalk blocks (JavaScript anonymous functions).
The bridge automatically installs an appropriate callback, whenever a block/function is given to a .NET component as a callback or hook.

Here is a complete example for creating a .NET form with a callback into expecco. This code could be put into an EB (Elementary Block) of an expecco activity diagram:
<CODE><PRE>
var dotNet, form, button;

// called when the .NET button is clicked
function callBack() {
dotNet.MessageBox.show("Hello from expecco");
};

dotNet = DOTNET::DotNet.newWithServer();
dotNet.loadLibrary("System.Windows.Forms");

button = dotNet.Button.new();
button.text("Hello");
button.click.add( callBack );

form = dotNet.Form.new();
button.dock( dotNet.DockStyle.fill );
form.controls.add( button );

form.showDialog();

dotNet.close();
</PRE></CODE>

=== Remote Dynamic Code Injection ===

C# and VB code can be dynamically loaded and compiled:

C#:
<CODE><PRE>
typeCode := '
using System;

namespace SomeNamespace
{
class SomeClass
{
public static void ConsoleWrite(string text)
{
Console.Write(text)
}
}
}
'.
typeObject := dotnet getDotNetType:'SomeNamespace.SomeClass' fromCSharpSource:typeCode.
typeObject ConsoleWrite:'Hello, World!'.
</PRE></CODE>

VB:
<CODE><PRE>

moduleCode := '
Imports System

Namespace SomeNamespace
Public Module SomeModule
Sub ConsoleWrite(ByVal text As String)
Console.WriteLine (text)
End Sub
End Module
End Namespace
'.
moduleObject := dotnet getDotNetType:'SomeNamespace.SomeModule' fromVBSource:moduleCode.
moduleObject ConsoleWrite:'Hello, World!'.
</PRE></CODE>

=== Calling ActiveX/COM Objects===

It's possible to make calls to ActiveX/COM Objects through the bridge.

To do this, you need to create a dotNet Assembly with the types from a .tlb or .ocx file.

This can be done with the tlbimp utility which is part of VisualStudio (reachable through the VS Dev CMD Shell...)

In this shell, you can e.g. execute

tlbimp c:\windows\system32\wshom.ocx

which will create a file called IWshRuntimeLibrary.dll for the Windows Script Host Runtime Library in the current directory. This can then be used to automate the Windows Script Host Runtime Library Object.

Here an example howto use this in code:

<CODE><PRE>

|dotNet shell buttonPressed|

dotNet := DotNet singletonInstance.
dotNet loadFile:'C:\Temp\IWshRuntimeLibrary.dll'.
shell := dotNet WshShellClass new.
buttonPressed := shell popup:'Hello from Micha' secToWait:15 title:'.NET Bridge Com Demo' type:0.
buttonPressed inspect

</PRE></CODE>

to be continued

== See Also==
The [[Java Interface Library v2| Java Interface Plugin & Library]], which implements a likewise interface for Java applications/libraries.

<hr>
Back to [[Plugins]] 
Back to [[OnlineDocumentation#Library and Plugin Overview|Online Documentation]].

DOT NET Interface Library v2

2017-03-15T13:18:18Z

Javogel: Die Seite wurde neu angelegt: „== Overview == The .NET Interface Library (".NET Bridge") contains a mechanism to access Microsoft .NET (CLR) objects of a local or remote .NET application (a…“

== Overview ==

The .NET Interface Library (".NET Bridge") contains a mechanism to access Microsoft .NET (CLR) objects of a local or remote .NET application (a so-called .NET bridge), and an API for elementary blocks and a library of blocks to interact with these objects.

== Programmatic Interface ==

Access to .NET objects, classes and programs is done via a framework called "dotNET-Bridge". This framework implements transparent forwarding of expecco messages (virtual function calls) from either Smalltalk or JavaScript code to .NET objects as existent in a local or remote .NET virtual machine. Also, return values, callBacks and exception information are passed back from the .NET program to expecco. A proxy-object mechanism which catches all function calls, wraps the arguments and sends a datagram to the other bridge side is used for this to be almost completely transparent to the Smalltalk/JavaScript code inside expecco.

In addition to existing blocks of the .NET Interface Library, programmatic access to dotNET objects is sometimes useful or required. So the following information is useful if you want to write your own elementary .NET-blocks, or if you have to enhance the existing library by adding application-specific interface blocks.

=== Initializing / Releasing the Bridge ===

Before any communication can take place between expecco and any dotNet object, the .NET side of the bridge has to be started, and a communication path to be setup.
All of the bridges classes are in the <CODE>DOTNET</CODE> namespace; the main interface class is <CODE>DotNet</CODE>, in this namespace:

<CODE><PRE>
dotNetHandle := DOTNET::DotNet newWithServer.
</PRE></CODE>
or (in JavaScript):
<CODE><PRE>
dotNetHandle = DOTNET::DotNet.newWithServer();
</PRE></CODE>

This starts the .NET-side of the bridge (the executable named "DotNetBridge.Server.exe"),
and waits for a connection request from this program.

When finished, release the bridge with:
<CODE><PRE>
dotNetHandle.close();
</PRE></CODE>
which shuts down the connection and terminates the executable.

=== Loading Assemblies ===
Using the "loadLibrary"-function, wellknown assemblies can be loaded:
<CODE><PRE>
dotNetHandle.loadLibrary("System.Windows.Forms");
</PRE></CODE>
or:
<CODE><PRE>
dotNetHandle.loadLibrary("user32.dll");
</PRE></CODE>

Arbitrary files which contain assemblies are loaded with:
<CODE><PRE>
dotNetHandle.loadFile(pathToDLL);
</PRE></CODE>
or:
<CODE><PRE>
dotNetHandle.loadExtension(pathToDLL);
</PRE></CODE>
the former loads an assembly from the machine running the bridge server (DotNetBridge.Server.exe), the latter loads it from the machine running expecco.

=== Accessing Globals ===

Globals, nameSpaces and members of a namespace are accessed using message sends to the dotNet handle, where the message name is the name of the global, namespace or interface.
These messages can be chained, to access a hierarchy of namespaces.
For example:
<CODE><PRE>
dotNetHandle.System.Reflection.Assembly.LoadFile("c:\foo\bar\myAssembly.dll");
</PRE></CODE>

=== Instantiating a Class ===

Object instances are created via the "new"-message, sent to a global:
<CODE><PRE>
b = dotNetHandle.Button.new();
f = dotNetHandle.Form.new();
</PRE></CODE>
once instanciated, any message can be sent transparently to such an .NET object, as if it was an expecco object:
<CODE><PRE>
b.text("Hello World");
f.controls.add(b);
f.showDialog();
</PRE></CODE>

=== Callbacks ===

Callbacks from .NET back into expecco are implemented via Smalltalk blocks (JavaScript anonymous functions).
The bridge automatically installs an appropriate callback, whenever a block/function is given to a .NET component as a callback or hook.

Here is a complete example for creating a .NET form with a callback into expecco. This code could be put into an EB (Elementary Block) of an expecco activity diagram:
<CODE><PRE>
var dotNet, form, button;

// called when the .NET button is clicked
function callBack() {
dotNet.MessageBox.show("Hello from expecco");
};

dotNet = DOTNET::DotNet.newWithServer();
dotNet.loadLibrary("System.Windows.Forms");

button = dotNet.Button.new();
button.text("Hello");
button.click.add( callBack );

form = dotNet.Form.new();
button.dock( dotNet.DockStyle.fill );
form.controls.add( button );

form.showDialog();

dotNet.close();
</PRE></CODE>

=== Remote Dynamic Code Injection ===

C# and VB code can be dynamically loaded and compiled:

C#:
<CODE><PRE>
typeCode := '
using System;

namespace SomeNamespace
{
class SomeClass
{
public static void ConsoleWrite(string text)
{
Console.Write(text)
}
}
}
'.
typeObject := dotnet getDotNetType:'SomeNamespace.SomeClass' fromCSharpSource:typeCode.
typeObject ConsoleWrite:'Hello, World!'.
</PRE></CODE>

VB:
<CODE><PRE>

moduleCode := '
Imports System

Namespace SomeNamespace
Public Module SomeModule
Sub ConsoleWrite(ByVal text As String)
Console.WriteLine ("Hello World using Visual Basic!")
End Sub
End Module
End Namespace
'.
moduleObject := dotnet getDotNetType:'SomeNamespace.SomeModule' fromVBSource:moduleCode.
moduleObject ConsoleWrite:'Hello, World!'.
</PRE></CODE>

=== Calling ActiveX/COM Objects===

It's possible to make calls to ActiveX/COM Objects through the bridge.

To do this, you need to create a dotNet Assembly with the types from a .tlb or .ocx file.

This can be done with the tlbimp utility which is part of VisualStudio (reachable through the VS Dev CMD Shell...)

In this shell, you can e.g. execute

tlbimp c:\windows\system32\wshom.ocx

which will create a file called IWshRuntimeLibrary.dll for the Windows Script Host Runtime Library in the current directory. This can then be used to automate the Windows Script Host Runtime Library Object.

Here an example howto use this in code:

<CODE><PRE>

|dotNet shell buttonPressed|

dotNet := DotNet singletonInstance.
dotNet loadFile:'C:\Temp\IWshRuntimeLibrary.dll'.
shell := dotNet WshShellClass new.
buttonPressed := shell popup:'Hello from Micha' secToWait:15 title:'.NET Bridge Com Demo' type:0.
buttonPressed inspect

</PRE></CODE>

to be continued

== See Also==
The [[Java Interface Library v2| Java Interface Plugin & Library]], which implements a likewise interface for Java applications/libraries.

<hr>
Back to [[Plugins]] 
Back to [[OnlineDocumentation#Library and Plugin Overview|Online Documentation]].

Java Interface Library v2

2016-06-01T12:39:04Z

Javogel: /* boxedDo:aBlock */

== Introduction ==

This article discusses version 2 of the Java Bridge (which is as of expecco v2.9 still experimental).
The article for version 1 can be found [[Java Interface Library | here]].

The Java Interface library ("Java Bridge") is used to interact with Java objects inside an external Java Virtual Machine (JVM).

The access to Java objects, classes and programs is done via a framework called "''Java-Bridge''", which is similar in operation to the [[DOT NET Interface Library| dotNET bridge]]. This framework implements transparent forwarding of method (virtual function) calls to Java objects, which exist in a local or remote Java Virtual Machine (JVM). Also, return values, callBacks and exception information are passed back from the Java program to expecco. This is done by a proxy-object mechanism, which catches all function calls, wraps the arguments, sends a datagram to the other bridge side, awaits the reply and returns the result to the original caller. Thus, remote procedure calls are almost completely transparent to the Smalltalk/JavaScript code inside expecco. In your elementary code, you can write remote function calls as if they were to local objects.

Notice that this document describes the low level framework, which implements the bridge communication. A much easier to use high level interface (called "Groovy Blocks") exists and should normally be used, if you need access to a java application's internals during testing.
Please take a look at
[[Expecco_API#Groovy_Elementary_Blocks | "Groovy Block API"]]
and [[Testing Java Applications using Groovy blocks/en | "Testing Java Applications using Groovy blocks"]].

== Architecture ==

On the expecco side, the bridge consists of a number of Proxy objects,
which behave like regular Smalltalk objects as seen from elementary expecco code.
However, instead of performing an action when one of their methods (virtual functions) is called,
they send a message over a socket connection to the Java VM (actually: to a bridge software inside the
Java application) which decodes the message and sends it to the destination Java object.
The same is done in reverse direction with the return value.

+---------------------+ +----------+ +----------------+ +----------------+ +---------+
| | | | | | | | | Java |
| expecco |---->| Proxy |---->| Bridge |==>>==| Bridge |---->| Object |
| (elementary code) |<----| |<----| (expecco side) |==<<==| (Java side) |<----| |
+---------------------+ +----------+ +----------------+ +----------------+ +---------+

This setup allows for transparent communication with objects inside a local or remote Java VM. This may be either utility functions which happen to be convenient for the test application (for example: file parsing, syntax analysis, protocol implementaitons or access to specific hardware via driver libraries), or the tested application in the system under test itself.

Especially, it allows for the objects of the tested application to be looked into, manipulated and for functions of it or underlying frameworks to be called.

For expecco code, we tried to make this as transparent as possible, however there are a few exceptions, when function names need to be translated (for example, because the function naming syntax is different) or due to the fact that for some operations no corresponding name exists in Smalltalk (array access, for example).

Of course, multiple such connections can coexist and be served/handled in parallel. This enables an expecco test suite to communicate with both sides of a tested client-server Java application, for example.

Notice that a similar mechanism is used in expecco to communicate with DOTNET, Qt (C++) and C applications.

 

== Activating the new Java Bridge ==
To activate the new bridge in expecco navigate to ''Extras'' ► ''Settings'' ► ''Plugins'' ► ''Java Bridge'' and tick the ''Use new Bridge (experimental)'' checkbox.
[[Datei:ActivateNewJavaBridge.png]]

'''Attention:''' Ticking the checkbox will terminate all currently active Bridge connections due to incompatibilities between the new and the old version.

== Initializing / Releasing the Bridge ==

Before any communication can take place between expecco and any Java object, the Java side of the bridge has to be started, and a communication has to be established.
In expecco, all of the bridge classes are found in the <CODE>JAVA</CODE> namespace.

The main interface class is "<CODE>Java</CODE>", in the "<CODE>JAVA</CODE>" namespace:
<CODE><PRE>
java := JAVA::Java newWithServer.
</PRE></CODE>
or (in JavaScript):
<CODE><PRE>
java = JAVA::Java.newWithServer();
</PRE></CODE>

This starts the Java-side of the bridge (actually executes java as a background command) on the local machine, and establishes a connection to that JVM.

The bridge connection should be closed, if the bridge is no longer needed. Release the bridge with:
<CODE><PRE>
java.closeBridge();
</PRE></CODE>
which terminates the connection.

=== Start and Connect to a Remote Machine ===
The above started a Java VM and connected to it. Alternatively, you may want to connect to an already running Java program (typically, your system under test).
In order for your program to be reachable, it must allow for the bridge to connect to it via a special bridge-connection, which is a socket connection. For this, it must execute the server code found in the "JavaBridge.jar" file. To pass [[#Startup Parameters| parameters]] you will typically start it from a command line or a little shell/batch script.

Call (on the shell/cmd level):
$ java -jar <PATH_TO_JAVABRIDGE.JAR> <PARAMETERS>

The "JavaBridge.jar" file is found in the installation directory of expecco at:
\exept\expecco\packages\exept\bridgeFramework\javaBridge\javaBin\JavaBridge.jar

The Javabridge code allows for either side to initiate the connection - i.e. it can be run in server mode,
where it awaits an incoming connection, or in client mode, where it actively initiates a connection.
After connection establishment, there is no difference in the operation of the bridge, however depending on the setup of your network infrastructure, especially firewalls, either mechanism may be easier to be used.

Assuming that the bridge is already running on the remote machine as server (default),
use <CODE>newConnectedTo:port:withTimeout:</CODE> to connect to it from the expecco side:
java := JAVA::Java newConnectedTo:'myHost' port:4567 withTimeout:30.
This will initiate the connection setup from the expecco side.

Alternatively, if started in client mode use <CODE>newWaitingForConnectOnHost:port:withTimeout:</CODE>:
java := JAVA::Java newWaitingForConnectOnHost:'localhost' port:4567 withTimeout:30.
which will open a port on the expecco side, and wait until the Java side connects to it.
[[#JAVA::Java|For more details see API]]

====Startup Parameters====
You can use any parameter in any order.
If no parameter is used then the bridge listenes on port 14014 in server mode without keepAlive.
;<code>-help</code>
* Shows the help

;<code>-ip <aHostnameOrIP></code>
* In client mode this specifies the ip or hostname to connect to. In server mode this specifies the ip or hostname to bind to.

;<code>-port <aPortNumber> </code>
* In client mode this specifies the port to connect to. In server mode this specifies the listening port.

;<code>-asClient</code>
* The bridge will start in client mode. If not set the bridge is started in server mode.

;<code>-keepAlive</code>
* By setting this flag the bridge will not exit after the connection has closed and starts to connect or listen again. Otherwise, it will run for a single connection session only.

== Loading Applications (from the expecco side) ==

Normally, you would start your application with the required command line arguments and include the javabridge as jar there. However, in some situations, it may be required to dynamically load other jars into the connected Java VM.
By accessing a classloader, additional classes, or applications as contained in JAR files can be loaded from the expecco side.

This can be used to add a JAR file to the classloader:
<CODE><PRE>
java loadJarByPath:'pathToJarFile'. "/ assuming "java" is a handle as returned from the above connect
</PRE></CODE>

or, if the JAR file is loaded in memory:
<CODE><PRE>
java loadJar:jarByteArray. "/ where "jarByteArray" is a ByteArray containing the JAR file
</PRE></CODE>

If the JVM is on a remote machine, the path is resolved on the expecco side and the JAR will be transferred to the remote side.

Should transferring the JAR be too much overhead, an additional mechanism is provided:
<CODE><PRE>
java loadExtension:'pathToJarFile'.
</PRE></CODE>
this will cache the JAR file on the bridge side and eliminate the overhead of subsequent invocations.

== Java Class Access ==

This following code sample simply references (i.e. accesses) the class "JFrame" from the <CODE>"javax.swing"</CODE> package. The fully specified class name in Java would be <CODE>"javax.swing.JFrame"</CODE>:
<CODE><PRE>
java getJavaClass:'javax.swing.JFrame'
</PRE></CODE>

Or, if you want to load multiple classes:
<CODE><PRE>
java import:'javax.swing.JFrame' import:'javax.swing.JButton'
do:[:jFrame :jButton | "do something with JButton and JFrame" ].
</PRE></CODE>

v2 also supports dynamic compilation of java source code:
<CODE><PRE>
java getJavaClass:'className' fromSource:'classSource'. "/ where classSource is a String containing valid java source code
</PRE></CODE>

and loading precompiled java bytecode:
<CODE><PRE>
java getJavaClass:'className' fromByteCode:byteCode. "/ where byteCode is a ByteArray containing valid java bytecode
</PRE></CODE>

[[#Remote Dynamic Code Injection | for details see Remote Dynamic Code Injection]]

== Instantiating a Class ==

Object instances are created via the "new"-message, sent to a proxy of a Java class. You can get this proxy as described in the previous section. For example, if we want to create a new instance of a "JFrame" and a "JButton", write:
<CODE><PRE>
frame := java getJavaClass:'javax.swing.JFrame' new.
button := java getJavaClass:'javax.swing.JButton' new.
</PRE></CODE>
The first statement results in a proxy object for the "JFrame" instance. The second line results in a proxy for a new "JButton" object.

== Calling Instance Methods ==

A method call is done by a message send to a proxy object, where the message is the method name to call. For example, to call the <CODE>"setVisible(boolean isVisible)"</CODE> method on the above JFrame object, we send the following message to that proxy:
<CODE><PRE>
frame setVisible:true.
</PRE></CODE>

As method naming is different in Smalltalk and Java, a dynamic translation is applied when sending messages from Smalltalk code to a remote Java object. Smalltalk has arguments embedded inside parts of a so called "keyword" message, such as in "receiver foo:arg1 bar:arg2", where "foo:bar:" would be the message name, and "arg1", "arg2" be the arguments.

In Java, the message name is a single identifier, and arguments are written in an argument list after the message name: "receiver.fooBar(arg1, arg2)".

When message names are translated, only the very first part of the Smalltalk keyword message is taken ("foo" in the above example), and the remaining parts are simpl ignored. Thus, any of the Smalltalk messages "foo:bar:", "foo:xxxx:" and "foo:_:" (a single underscore as second part) all translate to the same Java message name "foo()".

Therefore, to call a method with more than one argument, like <CODE>"setSize(int width,int height)"</CODE> on a JFrame instance we can write:
<CODE><PRE>
frame setSize:300 _:200.
</PRE></CODE>
but just as well:
<CODE><PRE>
frame setSize:300 anyWord:200.
</PRE></CODE>
or any other selector with "setSize:" as its first component.
The selector translation mechanism simply takes the first part as the Java selector.

In practice, you should take a reasonably descriptive name, such as: "frame setSize:300 height:200" or only the Java name as first part, such as "frame setSize:300 _:200".

For a call of a method with 4 arguments, we could write:
<CODE><PRE>
frame setBounds:100 y:50 width:300 height:200.
</PRE></CODE>
or:
<CODE><PRE>
frame setBounds:100 _:50 _:300 _:200.
</PRE></CODE>

Also here the <CODE>"y: width: height:"</CODE> can be named as you want, but the first part must be "setBounds:".

=== Calling Static Methods ===

Calling a static method on an object is not different from calling non static methods. In most cases you will call a static method not on an object but directly on the class. This is done by using the class object as "receiver" of the message. For example, if we want to call the static method <CODE>"isDefaultLookAndFeelDecorated()"</CODE> of the JFrame class, write:
<CODE><PRE>
java getJavaClass:'javax.swing.JFrame' isDefaultLookAndFeelDecorated.
</PRE></CODE>

== Accessing Fields ==

As Smalltalk does not support access of an object's fields from the outside (it is fully encapsulated, and access from outside is ONLY allowed via getters/setters), an additional translation mechanism is provided for field access.

Accessing a field of a Java object or a class's static field uses the same syntax as method calls. To access a field, send a message where the message is the field name. To access the field of a class the field must be static.
For example, to get the value of the static field named <CODE>"EXIT_ON_CLOSE"</CODE> of the "JFrame" class, write
<CODE><PRE>
value := java getJavaClass:'javax.swing.JFrame' EXIT_ON_CLOSE.
</PRE></CODE>
The variable "value" now holds the integer value of the <CODE>"EXIT_ON_CLOSE"</CODE> constant.

Assuming that a "JFrame" object had a field named <CODE>"myField"</CODE>, to access this field, we'd have to write:
<CODE><PRE>
value := frame myField.
</PRE></CODE>
and "value" now holding whatever <CODE>"myField"</CODE> returns. This could be another object reference or any primitive value.

=== Setting Fields ===
To set a field, use a setter-like method call:
<CODE><PRE>
frame myField: newValue.
</PRE></CODE>

=== Name Conflicts ===

In very rare situations, a Java object may contain both a field and a method by the same name.
In this case, the Smalltalk code cannot depend on the dynamic translation mechanism (which actually looks for either a field or method name to match), but instead make it explicit, which operation is wanted:
Use:
<CODE><PRE>
frame getFieldByName:'myField'
</PRE></CODE>
to read a field, and:
<CODE><PRE>
frame setFieldByName:'myField' value:123.
</PRE></CODE>
to write the field.

If there are both fields and methods by the same name, and you use the non-explicit call,
the bridge will always assume that you want to call the getter/setter and perform a method call.
 

== Arrays ==

=== Passing Smalltalk Collections to Java ===

Smalltalk collections can now be directly passed to Java with a few limitations:
* The identity of the Smalltalk collections will not be preserved. passing the same collection to java multiple times will result in multiple instances of the same array on the java side. (to bypass this instantiate a new java array)
* Smalltalk collections need to be explicitly converted to the correct type (e.g. a <CODE>SignedIntegerArray</CODE> on the smalltalk side matches an <CODE>int</CODE>-Array on the java side)

=== Instantiating Arrays ===

The new bridge supports instantiation of arrays (whereas previously reflection had to be used to instantiate arrays from the smalltalk side).
There are two ways an array can be instantiated:

<CODE><PRE>
intArray := (java getJavaClass:'int[]') new:#[ 1 2 3 4 5 ] asSignedIntegerArray. "/ instantiates a new array of type "int" with the contents "1, 2, 3, 4, 5"
</PRE></CODE>

<CODE><PRE>
intArray := (java getJavaClass:'int[]') new:10. "/ instantiates a new empty array of type "int" with 10 elements.
</PRE></CODE>

=== Accessing Arrays ===

To achieve better performance, arrays of primitive types smaller than a certain size have their contents cached on the smalltalk side:
<CODE><PRE>
intArray contents at:1. "/ this will access the first element of the cached contents.
</PRE></CODE>

large arrays are not serialized immediately. large arrays will be serialized when <CODE>contents</CODE> is called the first time.

'''Attention:''' Java arrays are not immutable. changes to an array are not reflected in the cached contents. if an array has been updated, call <CODE>refresh</CODE> on the array to update the cache. arrays will not be updated automatically.

<CODE><PRE>
shortArray := (java getJavaClass:'short[]') new:10. "/ new empty "short" array with 10 elements

"/ copy the contents of the smalltalk collection to the newly instantiated short array
(java getJavaClass:'java.lang.System') arraycopy:(#[ 1 2 3 ] asSignedWordArray) srcPos:0 dest:shortArray destPos:0 length:3.

shortArray at:0. "/ will reflect the changes made to the array

shortArray contents at:1. "/ will still return 0 because the cached contents have not been updated.

shortArray refresh. "/ update the cached contents

shortArray contents at:1. "/ will now correctly reflect the changes made to the array
</PRE></CODE>

== Boxed Primitives ==

In version 1 of the java bridge boxed primitives were unboxed automatically and the identity was not preserved.
In version 2 a mechanism is provided allowing to preserve the identity of boxed primitives: [[ #boxedDo:aBlock | boxedDo:aBlock ]].

Example:
<CODE><PRE>
java boxedDo:[
boxedInt := java getJavaClass:'java.lang.Integer' new:30. "/ instantiate a new boxed integer. boxedInt now holds a reference to this object
].
intValue := boxedInt value. "/ extract the value of the boxed integer. (no overhead)
</PRE></CODE>

== Asynchronous Communication ==

In the new Bridge, everything can be done asynchronously. This is achieved via the <CODE>asyncDo:aBlock</CODE> method.
Every request sent to the Bridge inside of aBlock will immediately return a lazy value.
This lazy value will block upon access until the actual result is received from the java side.
The order of execution is guaranteed to be the same on the java side as on the smalltalk side.

Example:
<CODE><PRE>
java asyncDo:[
lazyInteger := (java getJavaClass:'java.lang.Integer') new:40. "/ this will return immediately
].
actualInteger := lazyInteger value. "/ this will block until the result is available
</PRE></CODE>

== Callbacks from Java ==
Sometimes you may want to execute a piece of Smalltalk code during the execution of the Java code. For example, we may want to install a Smalltalk observer to be notified when a button on a Java GUI was pressed,
or some other callback from a Java framework.

The following code registers a Smalltalk block as a callback for a mouse press event of a button:
<CODE><PRE>
listener := MouseListener new.
listener implementMethod:'mousePressed' as:[ Transcript showCR:'Hello from Java' ].
</PRE></CODE>
The above creates the callback and the listener, which can now be registered on a button:
<CODE><PRE>
button addMouseListener:listener.
</PRE></CODE>
Now, with the press of the button in the Java GUI, the Smalltalk block will be executed and writes <CODE>"Hello from Java"</CODE> to the Smalltalk console.
Of course, any other (Smalltalk-)action code can be made to run via this mechanism.

But be aware, that the callback is possibly called later (when the elementary action, which installed the code, has already finished long ago). Also, as the Java code execution is not synchronized with any of your expecco action execution, the callback may also be called at any arbutrary time, even at times when no activity at all is executed on the expecco side. If you forget to cleanup, and the Java object is still alive, it may even be called after you have finished your test run (if you keep the java bridge handle around and alive, for example in an expecoo environment variable).

So the Smalltalk callback code should not depend on any particular elementary action to be currently running, but instead in most cases write some information into a shared data container, preferably an instance of "SharedQueue", which is thread safe. Then, some other action (an elementary action) would read-wait and read events from that shared queue.

make sure that your test correctly cleans up any such callbacks afterwards. As a last resort, use the "Shutdown Bridge Connection" menu item, which closes the bridge connection, and thereby - as a side effect - removes any leftover callbacks. It does close the connection, and any remaining java proxy object handles become invalid, though.

Another example, using an observer could look like:
<CODE><PRE>
observer := java Observer new.
observer implementMethod:'update'
as:[:sourceObservable :argument|
argument notNil ifTrue:[ Transcript showCR:('I was notifyed with: ',argument toString) ]
ifFalse:[ Transcript showCR:'I was notifyed and the argument was nil' ].
].
myObservable addObserver:observer.
</PRE></CODE>
When the observable calls <CODE>"notifyObservers"</CODE>, the Smalltalk block will be executed.

== Exceptions in Java ==
Exceptions on the Java side are signalled back to the Smalltalk side and raise a corresponding exception there. However, on the Java side, the call stack which lead to the exception has already been unwound at that time (Java exceptions are not proceedable). So a proceed in the Smalltalk-side exception handler only affects the Smalltalk caller, but may leave the Java side in an undefined state.

== Remote Dynamic Code Injection ==
Sometimes we might want to execute code without the overhead of many rpc-messages being sent over the bridge, especially if we want to do something time critical, or want to make execution time measurements.
For this, it is possible to load a class at runtime into the JavaVM. The code of the class will first be sent to the JavaVM, which will compile and load the generated byte code. Then, the class can be accessed via the bridge just like any other preloaded class.

The following example specifies the class code in a smalltalk string and inject the code into the JavaVM. Then an instance of that new class will be instantiated and finally a method of the object instance will be invoked:
<CODE><PRE>
classCode := '
package myPackage.test;

import java.awt.BorderLayout;
import java.awt.event.MouseAdapter;
import java.awt.event.MouseEvent;
import java.util.Calendar;

import javax.swing.JButton;
import javax.swing.JFrame;
import javax.swing.JLabel;;

public class MyInjectedClass {
public void createSampleApp(){
JFrame frame=new JFrame("Hello im injected");
frame.setLayout(new BorderLayout());
JButton button=new JButton("click me");
final JLabel label=new JLabel("Text");
button.addMouseListener(new MouseAdapter() {

@Override
public void mouseClicked(MouseEvent e) {
label.setText(Calendar.getInstance().getTime().toString());
}
});
frame.add(label,BorderLayout.NORTH);
frame.add(button,BorderLayout.SOUTH);
frame.setSize(300, 300);
frame.setVisible(true);
}
}
'.
classObject := java getJavaClass:'myPackage.test.MyInjectedClass' fromSource:classCode.
classObject new createSampleApp.
</PRE></CODE>
After the code has been injected, a new instance of <CODE>"MyInjectedClass"</CODE> is created and the <CODE>"createSampleApp"</CODE> method is called. Because the example implements a GUI, a Java window will open, containing a label and a button. Clicking the button displays the current time in the label.



=== Code Sources for Class injection ===
There are 3 possible types of class code sources which we can use to inject the code. In the examples before we directly used a simple <CODE>"String"</CODE> in the smalltalk code as a code source. We also can use a <CODE>"*.java"</CODE> file as source. Just read the content of the file into a string and use it as in the previous examples.

To inject a <CODE>"*.class"</CODE> file use the following code:
<pre>
java getJavaClass:'the.class.name' fromByteCode:classCode.
</pre>

== Examples ==

This example creates a JFrame with one button inside. Then a Mouselistener is created and registered on the button. When the button is pressed, the title of the window changes to <CODE>"onPressed"</CODE> and the Transcript shows the message <CODE>"onPressed"</CODE>. When the button is released, the title of the window is changed to <CODE>"onReleased"</CODE> and the Transcript shows <CODE>"onReleased"</CODE>. If the button lost the mouse focus, the bridge will exit (disconnect), and the Java side is terminated.
<CODE><PRE>
|java frame button listener|

"/getting a bridge
java := JAVA::JavaBridge newWithServer.

"/creating a new frame and button object
frame := java getJavaClass:'javax.swing.JFrame' new.
button := (java getJavaClass:'javax.swing.JButton') new:'Click'.

"/creating a new mouse listener and adding callback blocks
listener := (java getJavaClass:'java.awt.event.MouseListener') new.

listener implementMethod:'mousePressed' as:[ Transcript showCR:'onPress'. frame setTitle:'onPressed' ].
listener implementMethod:'mouseReleased' as:[ Transcript showCR:'onReleased'. frame setTitle:'onReleased' ].
listener implementMethod:'mouseExited' as:[ Transcript showCR:'onExited'. java closeBridge. ].

"/register the mouse listener on the button and make the frame with button visible
button addMouseListener:listener.
frame add:button.
frame setSize:300 y:100.
frame setVisible: true.
</PRE></CODE>



==Differences between v1 and v2==
===General===
* A Java Bridge instance no longer requires multiple tcp ports to be open. This simplifies connection through ssh tunnels and firewalls.
* The identity of strings and primitve wrappers can now be preserved. (see [[#boxedDo:aBlock | boxedDo]])
* Simplified instantiation and access of arrays. (see [[#Arrays | Arrays]])
* Every request to the java side can now be done asynchronously. (see [[#Asynchronous Communication | Asynchronous Communication]])

===Loading Applications===
* '''addJarByPath:''' and '''addToClassPath:''' are still supported but have been deprecated. use '''loadJar:''', '''loadJarByPath:''' and '''loadExtension:''' instead. The new methods no longer require the jar or library to be present on the remote machine.

[[Java Interface Library#Loading Applications (from the expecco side) | v1]] [[#Loading Applications (from the expecco side) | v2]]

===Java Class Access===
* Sending the fully qualified name with instances of "." replaced by "_" to the bridge handle is still supported, but not recommended.
* A new method '''getJavaClass:''' has been introduced (also available for v1 since expecco v2.9). This solves the side effects of "_" being a legal character in class names.

[[Java Interface Library#Java Package Import and Class Access | v1]] [[#Java Class Access | v2]]
===Callbacks from Java===
* A new method '''implementMethod:as:''' has been introduced to assign callback blocks to method names. The old way is still supported.

[[Java Interface Library#Callbacks from Java | v1]] [[#Callbacks from Java | v2]]

===Remote Dynamic Code Injection===
* Code injection was problematic in v1 and has now been re-implemented in v2.

[[#Remote Dynamic Code Injection | v2]]

== API ==
===JAVA::Java===
====class protocol====
=====newWithServer=====
* This will start a local JavaVM, running the JavaBridge, and establishes a connection on a random free port.
: A new connected instance of JAVA::Java class is returned.

=====newWithServerForJavaPath:aJavaPathFilename=====
* This is the same as newWithServer but the path to the java executable can be specified. The JavaVM version must be 1.6 or higher to run the JavaBridge.
:: '''aJavaPathFilename''' - must be a instance of Filename
Smalltalk: JAVA::Java newWithServerForJavaPath:('my\path\to\java.executable'asFilename).
JavaScript: JAVA::Java.newWithServerForJavaPath("my\path\to\java.executable".asFilename());

=====newConnectedTo:aHhostString port:aPortNumber withTimeout:aTimeoutSeconds=====
* This is used to connect to a running JavaBridge on the network. The JavaBridge must be started in server mode on the remote host. After connecting a new connected instance of JAVA::Java is returned.
:: '''aHostString''' - the hostname or IP of the remote machine as String
:: '''aPortNumber ''' - the port on which the remote machine is listening as Number
:: '''aTimeoutSeconds''' - a connect timeout in seconds as Number
Smalltalk: JAVA::Java newConnectedTo:'myHostName' port:4567 withTimeout:30.
JavaScript: JAVA::Java.newConnectedTo_port_withTimeout("myHostName",4567,30);

=====newWaitingForConnectOnHost:aListeningAddressString port:aListeningPortNumber withTimeout:aTimeoutSeconds=====
* This is used to wait for incomming connecions of a running JavaBridge on the network. The JavaBridge must be started in client mode on the remote host. After connecting a new connected instance of JAVA::Java is returned.
:: '''deprecated: aListeningAddressString''' - no longer used. Can be nil.
:: '''aListeningPortNumber ''' - the port on which to listen for incomming connections as Number
:: '''aTimeoutSeconds''' - a connect timeout in seconds as Number, If nil it will wait endless.

=====singletonInstance=====
* This will call newWithServer for the first time and then always returns the same connected JAVA::Java instance until the connection was closed, then a new connected instance is returned.

=====exitAllInstances=====
* This will close all instances of JAVA::Java.

====instance protocol====
=====loadJarByPath:aPath=====
* Adds a jar to the running JavaVM. If the jar depends on other jars or libraries you have to add them too.
:: '''aPath''' - the path to the jar file as String.

=====loadJar:aByteArray=====
* Adds a jar to the running JavaVM. If the jar depends on other jars or libraries you have to add them too.
:: '''aByteArrays''' - a ByteArray containing the JAR file.

=====loadExtension:aPath=====
* Adds a jar to the running JavaVM and caches it for subsequent usages. If the jar depends on other jars you have to add them too.
:: '''aPath''' - the path to the jar file as String.

=====boxedDo:aBlock=====
* Any boxed values in aBlock returned from the JVM are preserved as such. By default autoboxed values are automatically unboxed. This way, the identity of such objects is preserved.

=====isConnected=====
* Tests if a connection is still established.
:: '''return:''' - true if the connection is still established, else false.

=====isAlive=====
* Tests if a connection is still responding.
:: '''return:''' - true if the connection is still alive, else false. Does a message round trip.

=====closeBridge=====
* This will close the bridge connection. Depending on in which mode the JavaBridge was started, the JavaVM is also closed (-keepAlive startparameter not set).

=====exit=====
* Same as closeBridge.

== See Also==
The [[DOT NET Interface Library| DOTNET Interface Plugin & Library]], which implements a likewise interface for .NET applications/libraries.
 
[[Java Interface Library | Version 1 of the Java Interface Library]]
<hr>
Back to [[Plugins]]

Java Interface Library v2

2016-06-01T12:38:06Z

Javogel: /* Boxed Primitives */

== Introduction ==

This article discusses version 2 of the Java Bridge (which is as of expecco v2.9 still experimental).
The article for version 1 can be found [[Java Interface Library | here]].

The Java Interface library ("Java Bridge") is used to interact with Java objects inside an external Java Virtual Machine (JVM).

The access to Java objects, classes and programs is done via a framework called "''Java-Bridge''", which is similar in operation to the [[DOT NET Interface Library| dotNET bridge]]. This framework implements transparent forwarding of method (virtual function) calls to Java objects, which exist in a local or remote Java Virtual Machine (JVM). Also, return values, callBacks and exception information are passed back from the Java program to expecco. This is done by a proxy-object mechanism, which catches all function calls, wraps the arguments, sends a datagram to the other bridge side, awaits the reply and returns the result to the original caller. Thus, remote procedure calls are almost completely transparent to the Smalltalk/JavaScript code inside expecco. In your elementary code, you can write remote function calls as if they were to local objects.

Notice that this document describes the low level framework, which implements the bridge communication. A much easier to use high level interface (called "Groovy Blocks") exists and should normally be used, if you need access to a java application's internals during testing.
Please take a look at
[[Expecco_API#Groovy_Elementary_Blocks | "Groovy Block API"]]
and [[Testing Java Applications using Groovy blocks/en | "Testing Java Applications using Groovy blocks"]].

== Architecture ==

On the expecco side, the bridge consists of a number of Proxy objects,
which behave like regular Smalltalk objects as seen from elementary expecco code.
However, instead of performing an action when one of their methods (virtual functions) is called,
they send a message over a socket connection to the Java VM (actually: to a bridge software inside the
Java application) which decodes the message and sends it to the destination Java object.
The same is done in reverse direction with the return value.

+---------------------+ +----------+ +----------------+ +----------------+ +---------+
| | | | | | | | | Java |
| expecco |---->| Proxy |---->| Bridge |==>>==| Bridge |---->| Object |
| (elementary code) |<----| |<----| (expecco side) |==<<==| (Java side) |<----| |
+---------------------+ +----------+ +----------------+ +----------------+ +---------+

This setup allows for transparent communication with objects inside a local or remote Java VM. This may be either utility functions which happen to be convenient for the test application (for example: file parsing, syntax analysis, protocol implementaitons or access to specific hardware via driver libraries), or the tested application in the system under test itself.

Especially, it allows for the objects of the tested application to be looked into, manipulated and for functions of it or underlying frameworks to be called.

For expecco code, we tried to make this as transparent as possible, however there are a few exceptions, when function names need to be translated (for example, because the function naming syntax is different) or due to the fact that for some operations no corresponding name exists in Smalltalk (array access, for example).

Of course, multiple such connections can coexist and be served/handled in parallel. This enables an expecco test suite to communicate with both sides of a tested client-server Java application, for example.

Notice that a similar mechanism is used in expecco to communicate with DOTNET, Qt (C++) and C applications.

 

== Activating the new Java Bridge ==
To activate the new bridge in expecco navigate to ''Extras'' ► ''Settings'' ► ''Plugins'' ► ''Java Bridge'' and tick the ''Use new Bridge (experimental)'' checkbox.
[[Datei:ActivateNewJavaBridge.png]]

'''Attention:''' Ticking the checkbox will terminate all currently active Bridge connections due to incompatibilities between the new and the old version.

== Initializing / Releasing the Bridge ==

Before any communication can take place between expecco and any Java object, the Java side of the bridge has to be started, and a communication has to be established.
In expecco, all of the bridge classes are found in the <CODE>JAVA</CODE> namespace.

The main interface class is "<CODE>Java</CODE>", in the "<CODE>JAVA</CODE>" namespace:
<CODE><PRE>
java := JAVA::Java newWithServer.
</PRE></CODE>
or (in JavaScript):
<CODE><PRE>
java = JAVA::Java.newWithServer();
</PRE></CODE>

This starts the Java-side of the bridge (actually executes java as a background command) on the local machine, and establishes a connection to that JVM.

The bridge connection should be closed, if the bridge is no longer needed. Release the bridge with:
<CODE><PRE>
java.closeBridge();
</PRE></CODE>
which terminates the connection.

=== Start and Connect to a Remote Machine ===
The above started a Java VM and connected to it. Alternatively, you may want to connect to an already running Java program (typically, your system under test).
In order for your program to be reachable, it must allow for the bridge to connect to it via a special bridge-connection, which is a socket connection. For this, it must execute the server code found in the "JavaBridge.jar" file. To pass [[#Startup Parameters| parameters]] you will typically start it from a command line or a little shell/batch script.

Call (on the shell/cmd level):
$ java -jar <PATH_TO_JAVABRIDGE.JAR> <PARAMETERS>

The "JavaBridge.jar" file is found in the installation directory of expecco at:
\exept\expecco\packages\exept\bridgeFramework\javaBridge\javaBin\JavaBridge.jar

The Javabridge code allows for either side to initiate the connection - i.e. it can be run in server mode,
where it awaits an incoming connection, or in client mode, where it actively initiates a connection.
After connection establishment, there is no difference in the operation of the bridge, however depending on the setup of your network infrastructure, especially firewalls, either mechanism may be easier to be used.

Assuming that the bridge is already running on the remote machine as server (default),
use <CODE>newConnectedTo:port:withTimeout:</CODE> to connect to it from the expecco side:
java := JAVA::Java newConnectedTo:'myHost' port:4567 withTimeout:30.
This will initiate the connection setup from the expecco side.

Alternatively, if started in client mode use <CODE>newWaitingForConnectOnHost:port:withTimeout:</CODE>:
java := JAVA::Java newWaitingForConnectOnHost:'localhost' port:4567 withTimeout:30.
which will open a port on the expecco side, and wait until the Java side connects to it.
[[#JAVA::Java|For more details see API]]

====Startup Parameters====
You can use any parameter in any order.
If no parameter is used then the bridge listenes on port 14014 in server mode without keepAlive.
;<code>-help</code>
* Shows the help

;<code>-ip <aHostnameOrIP></code>
* In client mode this specifies the ip or hostname to connect to. In server mode this specifies the ip or hostname to bind to.

;<code>-port <aPortNumber> </code>
* In client mode this specifies the port to connect to. In server mode this specifies the listening port.

;<code>-asClient</code>
* The bridge will start in client mode. If not set the bridge is started in server mode.

;<code>-keepAlive</code>
* By setting this flag the bridge will not exit after the connection has closed and starts to connect or listen again. Otherwise, it will run for a single connection session only.

== Loading Applications (from the expecco side) ==

Normally, you would start your application with the required command line arguments and include the javabridge as jar there. However, in some situations, it may be required to dynamically load other jars into the connected Java VM.
By accessing a classloader, additional classes, or applications as contained in JAR files can be loaded from the expecco side.

This can be used to add a JAR file to the classloader:
<CODE><PRE>
java loadJarByPath:'pathToJarFile'. "/ assuming "java" is a handle as returned from the above connect
</PRE></CODE>

or, if the JAR file is loaded in memory:
<CODE><PRE>
java loadJar:jarByteArray. "/ where "jarByteArray" is a ByteArray containing the JAR file
</PRE></CODE>

If the JVM is on a remote machine, the path is resolved on the expecco side and the JAR will be transferred to the remote side.

Should transferring the JAR be too much overhead, an additional mechanism is provided:
<CODE><PRE>
java loadExtension:'pathToJarFile'.
</PRE></CODE>
this will cache the JAR file on the bridge side and eliminate the overhead of subsequent invocations.

== Java Class Access ==

This following code sample simply references (i.e. accesses) the class "JFrame" from the <CODE>"javax.swing"</CODE> package. The fully specified class name in Java would be <CODE>"javax.swing.JFrame"</CODE>:
<CODE><PRE>
java getJavaClass:'javax.swing.JFrame'
</PRE></CODE>

Or, if you want to load multiple classes:
<CODE><PRE>
java import:'javax.swing.JFrame' import:'javax.swing.JButton'
do:[:jFrame :jButton | "do something with JButton and JFrame" ].
</PRE></CODE>

v2 also supports dynamic compilation of java source code:
<CODE><PRE>
java getJavaClass:'className' fromSource:'classSource'. "/ where classSource is a String containing valid java source code
</PRE></CODE>

and loading precompiled java bytecode:
<CODE><PRE>
java getJavaClass:'className' fromByteCode:byteCode. "/ where byteCode is a ByteArray containing valid java bytecode
</PRE></CODE>

[[#Remote Dynamic Code Injection | for details see Remote Dynamic Code Injection]]

== Instantiating a Class ==

Object instances are created via the "new"-message, sent to a proxy of a Java class. You can get this proxy as described in the previous section. For example, if we want to create a new instance of a "JFrame" and a "JButton", write:
<CODE><PRE>
frame := java getJavaClass:'javax.swing.JFrame' new.
button := java getJavaClass:'javax.swing.JButton' new.
</PRE></CODE>
The first statement results in a proxy object for the "JFrame" instance. The second line results in a proxy for a new "JButton" object.

== Calling Instance Methods ==

A method call is done by a message send to a proxy object, where the message is the method name to call. For example, to call the <CODE>"setVisible(boolean isVisible)"</CODE> method on the above JFrame object, we send the following message to that proxy:
<CODE><PRE>
frame setVisible:true.
</PRE></CODE>

As method naming is different in Smalltalk and Java, a dynamic translation is applied when sending messages from Smalltalk code to a remote Java object. Smalltalk has arguments embedded inside parts of a so called "keyword" message, such as in "receiver foo:arg1 bar:arg2", where "foo:bar:" would be the message name, and "arg1", "arg2" be the arguments.

In Java, the message name is a single identifier, and arguments are written in an argument list after the message name: "receiver.fooBar(arg1, arg2)".

When message names are translated, only the very first part of the Smalltalk keyword message is taken ("foo" in the above example), and the remaining parts are simpl ignored. Thus, any of the Smalltalk messages "foo:bar:", "foo:xxxx:" and "foo:_:" (a single underscore as second part) all translate to the same Java message name "foo()".

Therefore, to call a method with more than one argument, like <CODE>"setSize(int width,int height)"</CODE> on a JFrame instance we can write:
<CODE><PRE>
frame setSize:300 _:200.
</PRE></CODE>
but just as well:
<CODE><PRE>
frame setSize:300 anyWord:200.
</PRE></CODE>
or any other selector with "setSize:" as its first component.
The selector translation mechanism simply takes the first part as the Java selector.

In practice, you should take a reasonably descriptive name, such as: "frame setSize:300 height:200" or only the Java name as first part, such as "frame setSize:300 _:200".

For a call of a method with 4 arguments, we could write:
<CODE><PRE>
frame setBounds:100 y:50 width:300 height:200.
</PRE></CODE>
or:
<CODE><PRE>
frame setBounds:100 _:50 _:300 _:200.
</PRE></CODE>

Also here the <CODE>"y: width: height:"</CODE> can be named as you want, but the first part must be "setBounds:".

=== Calling Static Methods ===

Calling a static method on an object is not different from calling non static methods. In most cases you will call a static method not on an object but directly on the class. This is done by using the class object as "receiver" of the message. For example, if we want to call the static method <CODE>"isDefaultLookAndFeelDecorated()"</CODE> of the JFrame class, write:
<CODE><PRE>
java getJavaClass:'javax.swing.JFrame' isDefaultLookAndFeelDecorated.
</PRE></CODE>

== Accessing Fields ==

As Smalltalk does not support access of an object's fields from the outside (it is fully encapsulated, and access from outside is ONLY allowed via getters/setters), an additional translation mechanism is provided for field access.

Accessing a field of a Java object or a class's static field uses the same syntax as method calls. To access a field, send a message where the message is the field name. To access the field of a class the field must be static.
For example, to get the value of the static field named <CODE>"EXIT_ON_CLOSE"</CODE> of the "JFrame" class, write
<CODE><PRE>
value := java getJavaClass:'javax.swing.JFrame' EXIT_ON_CLOSE.
</PRE></CODE>
The variable "value" now holds the integer value of the <CODE>"EXIT_ON_CLOSE"</CODE> constant.

Assuming that a "JFrame" object had a field named <CODE>"myField"</CODE>, to access this field, we'd have to write:
<CODE><PRE>
value := frame myField.
</PRE></CODE>
and "value" now holding whatever <CODE>"myField"</CODE> returns. This could be another object reference or any primitive value.

=== Setting Fields ===
To set a field, use a setter-like method call:
<CODE><PRE>
frame myField: newValue.
</PRE></CODE>

=== Name Conflicts ===

In very rare situations, a Java object may contain both a field and a method by the same name.
In this case, the Smalltalk code cannot depend on the dynamic translation mechanism (which actually looks for either a field or method name to match), but instead make it explicit, which operation is wanted:
Use:
<CODE><PRE>
frame getFieldByName:'myField'
</PRE></CODE>
to read a field, and:
<CODE><PRE>
frame setFieldByName:'myField' value:123.
</PRE></CODE>
to write the field.

If there are both fields and methods by the same name, and you use the non-explicit call,
the bridge will always assume that you want to call the getter/setter and perform a method call.
 

== Arrays ==

=== Passing Smalltalk Collections to Java ===

Smalltalk collections can now be directly passed to Java with a few limitations:
* The identity of the Smalltalk collections will not be preserved. passing the same collection to java multiple times will result in multiple instances of the same array on the java side. (to bypass this instantiate a new java array)
* Smalltalk collections need to be explicitly converted to the correct type (e.g. a <CODE>SignedIntegerArray</CODE> on the smalltalk side matches an <CODE>int</CODE>-Array on the java side)

=== Instantiating Arrays ===

The new bridge supports instantiation of arrays (whereas previously reflection had to be used to instantiate arrays from the smalltalk side).
There are two ways an array can be instantiated:

<CODE><PRE>
intArray := (java getJavaClass:'int[]') new:#[ 1 2 3 4 5 ] asSignedIntegerArray. "/ instantiates a new array of type "int" with the contents "1, 2, 3, 4, 5"
</PRE></CODE>

<CODE><PRE>
intArray := (java getJavaClass:'int[]') new:10. "/ instantiates a new empty array of type "int" with 10 elements.
</PRE></CODE>

=== Accessing Arrays ===

To achieve better performance, arrays of primitive types smaller than a certain size have their contents cached on the smalltalk side:
<CODE><PRE>
intArray contents at:1. "/ this will access the first element of the cached contents.
</PRE></CODE>

large arrays are not serialized immediately. large arrays will be serialized when <CODE>contents</CODE> is called the first time.

'''Attention:''' Java arrays are not immutable. changes to an array are not reflected in the cached contents. if an array has been updated, call <CODE>refresh</CODE> on the array to update the cache. arrays will not be updated automatically.

<CODE><PRE>
shortArray := (java getJavaClass:'short[]') new:10. "/ new empty "short" array with 10 elements

"/ copy the contents of the smalltalk collection to the newly instantiated short array
(java getJavaClass:'java.lang.System') arraycopy:(#[ 1 2 3 ] asSignedWordArray) srcPos:0 dest:shortArray destPos:0 length:3.

shortArray at:0. "/ will reflect the changes made to the array

shortArray contents at:1. "/ will still return 0 because the cached contents have not been updated.

shortArray refresh. "/ update the cached contents

shortArray contents at:1. "/ will now correctly reflect the changes made to the array
</PRE></CODE>

== Boxed Primitives ==

In version 1 of the java bridge boxed primitives were unboxed automatically and the identity was not preserved.
In version 2 a mechanism is provided allowing to preserve the identity of boxed primitives: [[ #boxedDo:aBlock | boxedDo:aBlock ]].

Example:
<CODE><PRE>
java boxedDo:[
boxedInt := java getJavaClass:'java.lang.Integer' new:30. "/ instantiate a new boxed integer. boxedInt now holds a reference to this object
].
intValue := boxedInt value. "/ extract the value of the boxed integer. (no overhead)
</PRE></CODE>

== Asynchronous Communication ==

In the new Bridge, everything can be done asynchronously. This is achieved via the <CODE>asyncDo:aBlock</CODE> method.
Every request sent to the Bridge inside of aBlock will immediately return a lazy value.
This lazy value will block upon access until the actual result is received from the java side.
The order of execution is guaranteed to be the same on the java side as on the smalltalk side.

Example:
<CODE><PRE>
java asyncDo:[
lazyInteger := (java getJavaClass:'java.lang.Integer') new:40. "/ this will return immediately
].
actualInteger := lazyInteger value. "/ this will block until the result is available
</PRE></CODE>

== Callbacks from Java ==
Sometimes you may want to execute a piece of Smalltalk code during the execution of the Java code. For example, we may want to install a Smalltalk observer to be notified when a button on a Java GUI was pressed,
or some other callback from a Java framework.

The following code registers a Smalltalk block as a callback for a mouse press event of a button:
<CODE><PRE>
listener := MouseListener new.
listener implementMethod:'mousePressed' as:[ Transcript showCR:'Hello from Java' ].
</PRE></CODE>
The above creates the callback and the listener, which can now be registered on a button:
<CODE><PRE>
button addMouseListener:listener.
</PRE></CODE>
Now, with the press of the button in the Java GUI, the Smalltalk block will be executed and writes <CODE>"Hello from Java"</CODE> to the Smalltalk console.
Of course, any other (Smalltalk-)action code can be made to run via this mechanism.

But be aware, that the callback is possibly called later (when the elementary action, which installed the code, has already finished long ago). Also, as the Java code execution is not synchronized with any of your expecco action execution, the callback may also be called at any arbutrary time, even at times when no activity at all is executed on the expecco side. If you forget to cleanup, and the Java object is still alive, it may even be called after you have finished your test run (if you keep the java bridge handle around and alive, for example in an expecoo environment variable).

So the Smalltalk callback code should not depend on any particular elementary action to be currently running, but instead in most cases write some information into a shared data container, preferably an instance of "SharedQueue", which is thread safe. Then, some other action (an elementary action) would read-wait and read events from that shared queue.

make sure that your test correctly cleans up any such callbacks afterwards. As a last resort, use the "Shutdown Bridge Connection" menu item, which closes the bridge connection, and thereby - as a side effect - removes any leftover callbacks. It does close the connection, and any remaining java proxy object handles become invalid, though.

Another example, using an observer could look like:
<CODE><PRE>
observer := java Observer new.
observer implementMethod:'update'
as:[:sourceObservable :argument|
argument notNil ifTrue:[ Transcript showCR:('I was notifyed with: ',argument toString) ]
ifFalse:[ Transcript showCR:'I was notifyed and the argument was nil' ].
].
myObservable addObserver:observer.
</PRE></CODE>
When the observable calls <CODE>"notifyObservers"</CODE>, the Smalltalk block will be executed.

== Exceptions in Java ==
Exceptions on the Java side are signalled back to the Smalltalk side and raise a corresponding exception there. However, on the Java side, the call stack which lead to the exception has already been unwound at that time (Java exceptions are not proceedable). So a proceed in the Smalltalk-side exception handler only affects the Smalltalk caller, but may leave the Java side in an undefined state.

== Remote Dynamic Code Injection ==
Sometimes we might want to execute code without the overhead of many rpc-messages being sent over the bridge, especially if we want to do something time critical, or want to make execution time measurements.
For this, it is possible to load a class at runtime into the JavaVM. The code of the class will first be sent to the JavaVM, which will compile and load the generated byte code. Then, the class can be accessed via the bridge just like any other preloaded class.

The following example specifies the class code in a smalltalk string and inject the code into the JavaVM. Then an instance of that new class will be instantiated and finally a method of the object instance will be invoked:
<CODE><PRE>
classCode := '
package myPackage.test;

import java.awt.BorderLayout;
import java.awt.event.MouseAdapter;
import java.awt.event.MouseEvent;
import java.util.Calendar;

import javax.swing.JButton;
import javax.swing.JFrame;
import javax.swing.JLabel;;

public class MyInjectedClass {
public void createSampleApp(){
JFrame frame=new JFrame("Hello im injected");
frame.setLayout(new BorderLayout());
JButton button=new JButton("click me");
final JLabel label=new JLabel("Text");
button.addMouseListener(new MouseAdapter() {

@Override
public void mouseClicked(MouseEvent e) {
label.setText(Calendar.getInstance().getTime().toString());
}
});
frame.add(label,BorderLayout.NORTH);
frame.add(button,BorderLayout.SOUTH);
frame.setSize(300, 300);
frame.setVisible(true);
}
}
'.
classObject := java getJavaClass:'myPackage.test.MyInjectedClass' fromSource:classCode.
classObject new createSampleApp.
</PRE></CODE>
After the code has been injected, a new instance of <CODE>"MyInjectedClass"</CODE> is created and the <CODE>"createSampleApp"</CODE> method is called. Because the example implements a GUI, a Java window will open, containing a label and a button. Clicking the button displays the current time in the label.



=== Code Sources for Class injection ===
There are 3 possible types of class code sources which we can use to inject the code. In the examples before we directly used a simple <CODE>"String"</CODE> in the smalltalk code as a code source. We also can use a <CODE>"*.java"</CODE> file as source. Just read the content of the file into a string and use it as in the previous examples.

To inject a <CODE>"*.class"</CODE> file use the following code:
<pre>
java getJavaClass:'the.class.name' fromByteCode:classCode.
</pre>

== Examples ==

This example creates a JFrame with one button inside. Then a Mouselistener is created and registered on the button. When the button is pressed, the title of the window changes to <CODE>"onPressed"</CODE> and the Transcript shows the message <CODE>"onPressed"</CODE>. When the button is released, the title of the window is changed to <CODE>"onReleased"</CODE> and the Transcript shows <CODE>"onReleased"</CODE>. If the button lost the mouse focus, the bridge will exit (disconnect), and the Java side is terminated.
<CODE><PRE>
|java frame button listener|

"/getting a bridge
java := JAVA::JavaBridge newWithServer.

"/creating a new frame and button object
frame := java getJavaClass:'javax.swing.JFrame' new.
button := (java getJavaClass:'javax.swing.JButton') new:'Click'.

"/creating a new mouse listener and adding callback blocks
listener := (java getJavaClass:'java.awt.event.MouseListener') new.

listener implementMethod:'mousePressed' as:[ Transcript showCR:'onPress'. frame setTitle:'onPressed' ].
listener implementMethod:'mouseReleased' as:[ Transcript showCR:'onReleased'. frame setTitle:'onReleased' ].
listener implementMethod:'mouseExited' as:[ Transcript showCR:'onExited'. java closeBridge. ].

"/register the mouse listener on the button and make the frame with button visible
button addMouseListener:listener.
frame add:button.
frame setSize:300 y:100.
frame setVisible: true.
</PRE></CODE>



==Differences between v1 and v2==
===General===
* A Java Bridge instance no longer requires multiple tcp ports to be open. This simplifies connection through ssh tunnels and firewalls.
* The identity of strings and primitve wrappers can now be preserved. (see [[#boxedDo:aBlock | boxedDo]])
* Simplified instantiation and access of arrays. (see [[#Arrays | Arrays]])
* Every request to the java side can now be done asynchronously. (see [[#Asynchronous Communication | Asynchronous Communication]])

===Loading Applications===
* '''addJarByPath:''' and '''addToClassPath:''' are still supported but have been deprecated. use '''loadJar:''', '''loadJarByPath:''' and '''loadExtension:''' instead. The new methods no longer require the jar or library to be present on the remote machine.

[[Java Interface Library#Loading Applications (from the expecco side) | v1]] [[#Loading Applications (from the expecco side) | v2]]

===Java Class Access===
* Sending the fully qualified name with instances of "." replaced by "_" to the bridge handle is still supported, but not recommended.
* A new method '''getJavaClass:''' has been introduced (also available for v1 since expecco v2.9). This solves the side effects of "_" being a legal character in class names.

[[Java Interface Library#Java Package Import and Class Access | v1]] [[#Java Class Access | v2]]
===Callbacks from Java===
* A new method '''implementMethod:as:''' has been introduced to assign callback blocks to method names. The old way is still supported.

[[Java Interface Library#Callbacks from Java | v1]] [[#Callbacks from Java | v2]]

===Remote Dynamic Code Injection===
* Code injection was problematic in v1 and has now been re-implemented in v2.

[[#Remote Dynamic Code Injection | v2]]

== API ==
===JAVA::Java===
====class protocol====
=====newWithServer=====
* This will start a local JavaVM, running the JavaBridge, and establishes a connection on a random free port.
: A new connected instance of JAVA::Java class is returned.

=====newWithServerForJavaPath:aJavaPathFilename=====
* This is the same as newWithServer but the path to the java executable can be specified. The JavaVM version must be 1.6 or higher to run the JavaBridge.
:: '''aJavaPathFilename''' - must be a instance of Filename
Smalltalk: JAVA::Java newWithServerForJavaPath:('my\path\to\java.executable'asFilename).
JavaScript: JAVA::Java.newWithServerForJavaPath("my\path\to\java.executable".asFilename());

=====newConnectedTo:aHhostString port:aPortNumber withTimeout:aTimeoutSeconds=====
* This is used to connect to a running JavaBridge on the network. The JavaBridge must be started in server mode on the remote host. After connecting a new connected instance of JAVA::Java is returned.
:: '''aHostString''' - the hostname or IP of the remote machine as String
:: '''aPortNumber ''' - the port on which the remote machine is listening as Number
:: '''aTimeoutSeconds''' - a connect timeout in seconds as Number
Smalltalk: JAVA::Java newConnectedTo:'myHostName' port:4567 withTimeout:30.
JavaScript: JAVA::Java.newConnectedTo_port_withTimeout("myHostName",4567,30);

=====newWaitingForConnectOnHost:aListeningAddressString port:aListeningPortNumber withTimeout:aTimeoutSeconds=====
* This is used to wait for incomming connecions of a running JavaBridge on the network. The JavaBridge must be started in client mode on the remote host. After connecting a new connected instance of JAVA::Java is returned.
:: '''deprecated: aListeningAddressString''' - no longer used. Can be nil.
:: '''aListeningPortNumber ''' - the port on which to listen for incomming connections as Number
:: '''aTimeoutSeconds''' - a connect timeout in seconds as Number, If nil it will wait endless.

=====singletonInstance=====
* This will call newWithServer for the first time and then always returns the same connected JAVA::Java instance until the connection was closed, then a new connected instance is returned.

=====exitAllInstances=====
* This will close all instances of JAVA::Java.

====instance protocol====
=====loadJarByPath:aPath=====
* Adds a jar to the running JavaVM. If the jar depends on other jars or libraries you have to add them too.
:: '''aPath''' - the path to the jar file as String.

=====loadJar:aByteArray=====
* Adds a jar to the running JavaVM. If the jar depends on other jars or libraries you have to add them too.
:: '''aByteArrays''' - a ByteArray containing the JAR file.

=====loadExtension:aPath=====
* Adds a jar to the running JavaVM and caches it for subsequent usages. If the jar depends on other jars you have to add them too.
:: '''aPath''' - the path to the jar file as String.

=====boxedDo:aBlock=====
* Any autoboxed values in aBlock returned from the JavaVM are preserved as such. By default autoboxed values are automatically unboxed. This way, the identity of such objects is preserved.

=====isConnected=====
* Tests if a connection is still established.
:: '''return:''' - true if the connection is still established, else false.

=====isAlive=====
* Tests if a connection is still responding.
:: '''return:''' - true if the connection is still alive, else false. Does a message round trip.

=====closeBridge=====
* This will close the bridge connection. Depending on in which mode the JavaBridge was started, the JavaVM is also closed (-keepAlive startparameter not set).

=====exit=====
* Same as closeBridge.

== See Also==
The [[DOT NET Interface Library| DOTNET Interface Plugin & Library]], which implements a likewise interface for .NET applications/libraries.
 
[[Java Interface Library | Version 1 of the Java Interface Library]]
<hr>
Back to [[Plugins]]

Java Interface Library v2

2016-06-01T12:37:37Z

Javogel: /* Boxed Primitives */

== Introduction ==

This article discusses version 2 of the Java Bridge (which is as of expecco v2.9 still experimental).
The article for version 1 can be found [[Java Interface Library | here]].

The Java Interface library ("Java Bridge") is used to interact with Java objects inside an external Java Virtual Machine (JVM).

The access to Java objects, classes and programs is done via a framework called "''Java-Bridge''", which is similar in operation to the [[DOT NET Interface Library| dotNET bridge]]. This framework implements transparent forwarding of method (virtual function) calls to Java objects, which exist in a local or remote Java Virtual Machine (JVM). Also, return values, callBacks and exception information are passed back from the Java program to expecco. This is done by a proxy-object mechanism, which catches all function calls, wraps the arguments, sends a datagram to the other bridge side, awaits the reply and returns the result to the original caller. Thus, remote procedure calls are almost completely transparent to the Smalltalk/JavaScript code inside expecco. In your elementary code, you can write remote function calls as if they were to local objects.

Notice that this document describes the low level framework, which implements the bridge communication. A much easier to use high level interface (called "Groovy Blocks") exists and should normally be used, if you need access to a java application's internals during testing.
Please take a look at
[[Expecco_API#Groovy_Elementary_Blocks | "Groovy Block API"]]
and [[Testing Java Applications using Groovy blocks/en | "Testing Java Applications using Groovy blocks"]].

== Architecture ==

On the expecco side, the bridge consists of a number of Proxy objects,
which behave like regular Smalltalk objects as seen from elementary expecco code.
However, instead of performing an action when one of their methods (virtual functions) is called,
they send a message over a socket connection to the Java VM (actually: to a bridge software inside the
Java application) which decodes the message and sends it to the destination Java object.
The same is done in reverse direction with the return value.

+---------------------+ +----------+ +----------------+ +----------------+ +---------+
| | | | | | | | | Java |
| expecco |---->| Proxy |---->| Bridge |==>>==| Bridge |---->| Object |
| (elementary code) |<----| |<----| (expecco side) |==<<==| (Java side) |<----| |
+---------------------+ +----------+ +----------------+ +----------------+ +---------+

This setup allows for transparent communication with objects inside a local or remote Java VM. This may be either utility functions which happen to be convenient for the test application (for example: file parsing, syntax analysis, protocol implementaitons or access to specific hardware via driver libraries), or the tested application in the system under test itself.

Especially, it allows for the objects of the tested application to be looked into, manipulated and for functions of it or underlying frameworks to be called.

For expecco code, we tried to make this as transparent as possible, however there are a few exceptions, when function names need to be translated (for example, because the function naming syntax is different) or due to the fact that for some operations no corresponding name exists in Smalltalk (array access, for example).

Of course, multiple such connections can coexist and be served/handled in parallel. This enables an expecco test suite to communicate with both sides of a tested client-server Java application, for example.

Notice that a similar mechanism is used in expecco to communicate with DOTNET, Qt (C++) and C applications.

 

== Activating the new Java Bridge ==
To activate the new bridge in expecco navigate to ''Extras'' ► ''Settings'' ► ''Plugins'' ► ''Java Bridge'' and tick the ''Use new Bridge (experimental)'' checkbox.
[[Datei:ActivateNewJavaBridge.png]]

'''Attention:''' Ticking the checkbox will terminate all currently active Bridge connections due to incompatibilities between the new and the old version.

== Initializing / Releasing the Bridge ==

Before any communication can take place between expecco and any Java object, the Java side of the bridge has to be started, and a communication has to be established.
In expecco, all of the bridge classes are found in the <CODE>JAVA</CODE> namespace.

The main interface class is "<CODE>Java</CODE>", in the "<CODE>JAVA</CODE>" namespace:
<CODE><PRE>
java := JAVA::Java newWithServer.
</PRE></CODE>
or (in JavaScript):
<CODE><PRE>
java = JAVA::Java.newWithServer();
</PRE></CODE>

This starts the Java-side of the bridge (actually executes java as a background command) on the local machine, and establishes a connection to that JVM.

The bridge connection should be closed, if the bridge is no longer needed. Release the bridge with:
<CODE><PRE>
java.closeBridge();
</PRE></CODE>
which terminates the connection.

=== Start and Connect to a Remote Machine ===
The above started a Java VM and connected to it. Alternatively, you may want to connect to an already running Java program (typically, your system under test).
In order for your program to be reachable, it must allow for the bridge to connect to it via a special bridge-connection, which is a socket connection. For this, it must execute the server code found in the "JavaBridge.jar" file. To pass [[#Startup Parameters| parameters]] you will typically start it from a command line or a little shell/batch script.

Call (on the shell/cmd level):
$ java -jar <PATH_TO_JAVABRIDGE.JAR> <PARAMETERS>

The "JavaBridge.jar" file is found in the installation directory of expecco at:
\exept\expecco\packages\exept\bridgeFramework\javaBridge\javaBin\JavaBridge.jar

The Javabridge code allows for either side to initiate the connection - i.e. it can be run in server mode,
where it awaits an incoming connection, or in client mode, where it actively initiates a connection.
After connection establishment, there is no difference in the operation of the bridge, however depending on the setup of your network infrastructure, especially firewalls, either mechanism may be easier to be used.

Assuming that the bridge is already running on the remote machine as server (default),
use <CODE>newConnectedTo:port:withTimeout:</CODE> to connect to it from the expecco side:
java := JAVA::Java newConnectedTo:'myHost' port:4567 withTimeout:30.
This will initiate the connection setup from the expecco side.

Alternatively, if started in client mode use <CODE>newWaitingForConnectOnHost:port:withTimeout:</CODE>:
java := JAVA::Java newWaitingForConnectOnHost:'localhost' port:4567 withTimeout:30.
which will open a port on the expecco side, and wait until the Java side connects to it.
[[#JAVA::Java|For more details see API]]

====Startup Parameters====
You can use any parameter in any order.
If no parameter is used then the bridge listenes on port 14014 in server mode without keepAlive.
;<code>-help</code>
* Shows the help

;<code>-ip <aHostnameOrIP></code>
* In client mode this specifies the ip or hostname to connect to. In server mode this specifies the ip or hostname to bind to.

;<code>-port <aPortNumber> </code>
* In client mode this specifies the port to connect to. In server mode this specifies the listening port.

;<code>-asClient</code>
* The bridge will start in client mode. If not set the bridge is started in server mode.

;<code>-keepAlive</code>
* By setting this flag the bridge will not exit after the connection has closed and starts to connect or listen again. Otherwise, it will run for a single connection session only.

== Loading Applications (from the expecco side) ==

Normally, you would start your application with the required command line arguments and include the javabridge as jar there. However, in some situations, it may be required to dynamically load other jars into the connected Java VM.
By accessing a classloader, additional classes, or applications as contained in JAR files can be loaded from the expecco side.

This can be used to add a JAR file to the classloader:
<CODE><PRE>
java loadJarByPath:'pathToJarFile'. "/ assuming "java" is a handle as returned from the above connect
</PRE></CODE>

or, if the JAR file is loaded in memory:
<CODE><PRE>
java loadJar:jarByteArray. "/ where "jarByteArray" is a ByteArray containing the JAR file
</PRE></CODE>

If the JVM is on a remote machine, the path is resolved on the expecco side and the JAR will be transferred to the remote side.

Should transferring the JAR be too much overhead, an additional mechanism is provided:
<CODE><PRE>
java loadExtension:'pathToJarFile'.
</PRE></CODE>
this will cache the JAR file on the bridge side and eliminate the overhead of subsequent invocations.

== Java Class Access ==

This following code sample simply references (i.e. accesses) the class "JFrame" from the <CODE>"javax.swing"</CODE> package. The fully specified class name in Java would be <CODE>"javax.swing.JFrame"</CODE>:
<CODE><PRE>
java getJavaClass:'javax.swing.JFrame'
</PRE></CODE>

Or, if you want to load multiple classes:
<CODE><PRE>
java import:'javax.swing.JFrame' import:'javax.swing.JButton'
do:[:jFrame :jButton | "do something with JButton and JFrame" ].
</PRE></CODE>

v2 also supports dynamic compilation of java source code:
<CODE><PRE>
java getJavaClass:'className' fromSource:'classSource'. "/ where classSource is a String containing valid java source code
</PRE></CODE>

and loading precompiled java bytecode:
<CODE><PRE>
java getJavaClass:'className' fromByteCode:byteCode. "/ where byteCode is a ByteArray containing valid java bytecode
</PRE></CODE>

[[#Remote Dynamic Code Injection | for details see Remote Dynamic Code Injection]]

== Instantiating a Class ==

Object instances are created via the "new"-message, sent to a proxy of a Java class. You can get this proxy as described in the previous section. For example, if we want to create a new instance of a "JFrame" and a "JButton", write:
<CODE><PRE>
frame := java getJavaClass:'javax.swing.JFrame' new.
button := java getJavaClass:'javax.swing.JButton' new.
</PRE></CODE>
The first statement results in a proxy object for the "JFrame" instance. The second line results in a proxy for a new "JButton" object.

== Calling Instance Methods ==

A method call is done by a message send to a proxy object, where the message is the method name to call. For example, to call the <CODE>"setVisible(boolean isVisible)"</CODE> method on the above JFrame object, we send the following message to that proxy:
<CODE><PRE>
frame setVisible:true.
</PRE></CODE>

As method naming is different in Smalltalk and Java, a dynamic translation is applied when sending messages from Smalltalk code to a remote Java object. Smalltalk has arguments embedded inside parts of a so called "keyword" message, such as in "receiver foo:arg1 bar:arg2", where "foo:bar:" would be the message name, and "arg1", "arg2" be the arguments.

In Java, the message name is a single identifier, and arguments are written in an argument list after the message name: "receiver.fooBar(arg1, arg2)".

When message names are translated, only the very first part of the Smalltalk keyword message is taken ("foo" in the above example), and the remaining parts are simpl ignored. Thus, any of the Smalltalk messages "foo:bar:", "foo:xxxx:" and "foo:_:" (a single underscore as second part) all translate to the same Java message name "foo()".

Therefore, to call a method with more than one argument, like <CODE>"setSize(int width,int height)"</CODE> on a JFrame instance we can write:
<CODE><PRE>
frame setSize:300 _:200.
</PRE></CODE>
but just as well:
<CODE><PRE>
frame setSize:300 anyWord:200.
</PRE></CODE>
or any other selector with "setSize:" as its first component.
The selector translation mechanism simply takes the first part as the Java selector.

In practice, you should take a reasonably descriptive name, such as: "frame setSize:300 height:200" or only the Java name as first part, such as "frame setSize:300 _:200".

For a call of a method with 4 arguments, we could write:
<CODE><PRE>
frame setBounds:100 y:50 width:300 height:200.
</PRE></CODE>
or:
<CODE><PRE>
frame setBounds:100 _:50 _:300 _:200.
</PRE></CODE>

Also here the <CODE>"y: width: height:"</CODE> can be named as you want, but the first part must be "setBounds:".

=== Calling Static Methods ===

Calling a static method on an object is not different from calling non static methods. In most cases you will call a static method not on an object but directly on the class. This is done by using the class object as "receiver" of the message. For example, if we want to call the static method <CODE>"isDefaultLookAndFeelDecorated()"</CODE> of the JFrame class, write:
<CODE><PRE>
java getJavaClass:'javax.swing.JFrame' isDefaultLookAndFeelDecorated.
</PRE></CODE>

== Accessing Fields ==

As Smalltalk does not support access of an object's fields from the outside (it is fully encapsulated, and access from outside is ONLY allowed via getters/setters), an additional translation mechanism is provided for field access.

Accessing a field of a Java object or a class's static field uses the same syntax as method calls. To access a field, send a message where the message is the field name. To access the field of a class the field must be static.
For example, to get the value of the static field named <CODE>"EXIT_ON_CLOSE"</CODE> of the "JFrame" class, write
<CODE><PRE>
value := java getJavaClass:'javax.swing.JFrame' EXIT_ON_CLOSE.
</PRE></CODE>
The variable "value" now holds the integer value of the <CODE>"EXIT_ON_CLOSE"</CODE> constant.

Assuming that a "JFrame" object had a field named <CODE>"myField"</CODE>, to access this field, we'd have to write:
<CODE><PRE>
value := frame myField.
</PRE></CODE>
and "value" now holding whatever <CODE>"myField"</CODE> returns. This could be another object reference or any primitive value.

=== Setting Fields ===
To set a field, use a setter-like method call:
<CODE><PRE>
frame myField: newValue.
</PRE></CODE>

=== Name Conflicts ===

In very rare situations, a Java object may contain both a field and a method by the same name.
In this case, the Smalltalk code cannot depend on the dynamic translation mechanism (which actually looks for either a field or method name to match), but instead make it explicit, which operation is wanted:
Use:
<CODE><PRE>
frame getFieldByName:'myField'
</PRE></CODE>
to read a field, and:
<CODE><PRE>
frame setFieldByName:'myField' value:123.
</PRE></CODE>
to write the field.

If there are both fields and methods by the same name, and you use the non-explicit call,
the bridge will always assume that you want to call the getter/setter and perform a method call.
 

== Arrays ==

=== Passing Smalltalk Collections to Java ===

Smalltalk collections can now be directly passed to Java with a few limitations:
* The identity of the Smalltalk collections will not be preserved. passing the same collection to java multiple times will result in multiple instances of the same array on the java side. (to bypass this instantiate a new java array)
* Smalltalk collections need to be explicitly converted to the correct type (e.g. a <CODE>SignedIntegerArray</CODE> on the smalltalk side matches an <CODE>int</CODE>-Array on the java side)

=== Instantiating Arrays ===

The new bridge supports instantiation of arrays (whereas previously reflection had to be used to instantiate arrays from the smalltalk side).
There are two ways an array can be instantiated:

<CODE><PRE>
intArray := (java getJavaClass:'int[]') new:#[ 1 2 3 4 5 ] asSignedIntegerArray. "/ instantiates a new array of type "int" with the contents "1, 2, 3, 4, 5"
</PRE></CODE>

<CODE><PRE>
intArray := (java getJavaClass:'int[]') new:10. "/ instantiates a new empty array of type "int" with 10 elements.
</PRE></CODE>

=== Accessing Arrays ===

To achieve better performance, arrays of primitive types smaller than a certain size have their contents cached on the smalltalk side:
<CODE><PRE>
intArray contents at:1. "/ this will access the first element of the cached contents.
</PRE></CODE>

large arrays are not serialized immediately. large arrays will be serialized when <CODE>contents</CODE> is called the first time.

'''Attention:''' Java arrays are not immutable. changes to an array are not reflected in the cached contents. if an array has been updated, call <CODE>refresh</CODE> on the array to update the cache. arrays will not be updated automatically.

<CODE><PRE>
shortArray := (java getJavaClass:'short[]') new:10. "/ new empty "short" array with 10 elements

"/ copy the contents of the smalltalk collection to the newly instantiated short array
(java getJavaClass:'java.lang.System') arraycopy:(#[ 1 2 3 ] asSignedWordArray) srcPos:0 dest:shortArray destPos:0 length:3.

shortArray at:0. "/ will reflect the changes made to the array

shortArray contents at:1. "/ will still return 0 because the cached contents have not been updated.

shortArray refresh. "/ update the cached contents

shortArray contents at:1. "/ will now correctly reflect the changes made to the array
</PRE></CODE>

== Boxed Primitives ==

In version 1 of the java bridge boxed primitives were unboxed automatically and the identity was not preserved.
In version 2 a mechanism is provided allowing to preserve the identity of boxed primitives: [[ #boxedDo:aBlock | boxedDo:aBlock ]].

Example:
<CODE><PRE>
java boxedDo:[
boxedInt := java getJavaClass:'java.lang.Integer' new:30. "/ instantiate a new boxed integer. boxedInt now holds a reference to this object
].
intValue := boxedInt value. "/ extract the value of the boxed integer. (does not require a roundtrip)
</PRE></CODE>

== Asynchronous Communication ==

In the new Bridge, everything can be done asynchronously. This is achieved via the <CODE>asyncDo:aBlock</CODE> method.
Every request sent to the Bridge inside of aBlock will immediately return a lazy value.
This lazy value will block upon access until the actual result is received from the java side.
The order of execution is guaranteed to be the same on the java side as on the smalltalk side.

Example:
<CODE><PRE>
java asyncDo:[
lazyInteger := (java getJavaClass:'java.lang.Integer') new:40. "/ this will return immediately
].
actualInteger := lazyInteger value. "/ this will block until the result is available
</PRE></CODE>

== Callbacks from Java ==
Sometimes you may want to execute a piece of Smalltalk code during the execution of the Java code. For example, we may want to install a Smalltalk observer to be notified when a button on a Java GUI was pressed,
or some other callback from a Java framework.

The following code registers a Smalltalk block as a callback for a mouse press event of a button:
<CODE><PRE>
listener := MouseListener new.
listener implementMethod:'mousePressed' as:[ Transcript showCR:'Hello from Java' ].
</PRE></CODE>
The above creates the callback and the listener, which can now be registered on a button:
<CODE><PRE>
button addMouseListener:listener.
</PRE></CODE>
Now, with the press of the button in the Java GUI, the Smalltalk block will be executed and writes <CODE>"Hello from Java"</CODE> to the Smalltalk console.
Of course, any other (Smalltalk-)action code can be made to run via this mechanism.

But be aware, that the callback is possibly called later (when the elementary action, which installed the code, has already finished long ago). Also, as the Java code execution is not synchronized with any of your expecco action execution, the callback may also be called at any arbutrary time, even at times when no activity at all is executed on the expecco side. If you forget to cleanup, and the Java object is still alive, it may even be called after you have finished your test run (if you keep the java bridge handle around and alive, for example in an expecoo environment variable).

So the Smalltalk callback code should not depend on any particular elementary action to be currently running, but instead in most cases write some information into a shared data container, preferably an instance of "SharedQueue", which is thread safe. Then, some other action (an elementary action) would read-wait and read events from that shared queue.

make sure that your test correctly cleans up any such callbacks afterwards. As a last resort, use the "Shutdown Bridge Connection" menu item, which closes the bridge connection, and thereby - as a side effect - removes any leftover callbacks. It does close the connection, and any remaining java proxy object handles become invalid, though.

Another example, using an observer could look like:
<CODE><PRE>
observer := java Observer new.
observer implementMethod:'update'
as:[:sourceObservable :argument|
argument notNil ifTrue:[ Transcript showCR:('I was notifyed with: ',argument toString) ]
ifFalse:[ Transcript showCR:'I was notifyed and the argument was nil' ].
].
myObservable addObserver:observer.
</PRE></CODE>
When the observable calls <CODE>"notifyObservers"</CODE>, the Smalltalk block will be executed.

== Exceptions in Java ==
Exceptions on the Java side are signalled back to the Smalltalk side and raise a corresponding exception there. However, on the Java side, the call stack which lead to the exception has already been unwound at that time (Java exceptions are not proceedable). So a proceed in the Smalltalk-side exception handler only affects the Smalltalk caller, but may leave the Java side in an undefined state.

== Remote Dynamic Code Injection ==
Sometimes we might want to execute code without the overhead of many rpc-messages being sent over the bridge, especially if we want to do something time critical, or want to make execution time measurements.
For this, it is possible to load a class at runtime into the JavaVM. The code of the class will first be sent to the JavaVM, which will compile and load the generated byte code. Then, the class can be accessed via the bridge just like any other preloaded class.

The following example specifies the class code in a smalltalk string and inject the code into the JavaVM. Then an instance of that new class will be instantiated and finally a method of the object instance will be invoked:
<CODE><PRE>
classCode := '
package myPackage.test;

import java.awt.BorderLayout;
import java.awt.event.MouseAdapter;
import java.awt.event.MouseEvent;
import java.util.Calendar;

import javax.swing.JButton;
import javax.swing.JFrame;
import javax.swing.JLabel;;

public class MyInjectedClass {
public void createSampleApp(){
JFrame frame=new JFrame("Hello im injected");
frame.setLayout(new BorderLayout());
JButton button=new JButton("click me");
final JLabel label=new JLabel("Text");
button.addMouseListener(new MouseAdapter() {

@Override
public void mouseClicked(MouseEvent e) {
label.setText(Calendar.getInstance().getTime().toString());
}
});
frame.add(label,BorderLayout.NORTH);
frame.add(button,BorderLayout.SOUTH);
frame.setSize(300, 300);
frame.setVisible(true);
}
}
'.
classObject := java getJavaClass:'myPackage.test.MyInjectedClass' fromSource:classCode.
classObject new createSampleApp.
</PRE></CODE>
After the code has been injected, a new instance of <CODE>"MyInjectedClass"</CODE> is created and the <CODE>"createSampleApp"</CODE> method is called. Because the example implements a GUI, a Java window will open, containing a label and a button. Clicking the button displays the current time in the label.



=== Code Sources for Class injection ===
There are 3 possible types of class code sources which we can use to inject the code. In the examples before we directly used a simple <CODE>"String"</CODE> in the smalltalk code as a code source. We also can use a <CODE>"*.java"</CODE> file as source. Just read the content of the file into a string and use it as in the previous examples.

To inject a <CODE>"*.class"</CODE> file use the following code:
<pre>
java getJavaClass:'the.class.name' fromByteCode:classCode.
</pre>

== Examples ==

This example creates a JFrame with one button inside. Then a Mouselistener is created and registered on the button. When the button is pressed, the title of the window changes to <CODE>"onPressed"</CODE> and the Transcript shows the message <CODE>"onPressed"</CODE>. When the button is released, the title of the window is changed to <CODE>"onReleased"</CODE> and the Transcript shows <CODE>"onReleased"</CODE>. If the button lost the mouse focus, the bridge will exit (disconnect), and the Java side is terminated.
<CODE><PRE>
|java frame button listener|

"/getting a bridge
java := JAVA::JavaBridge newWithServer.

"/creating a new frame and button object
frame := java getJavaClass:'javax.swing.JFrame' new.
button := (java getJavaClass:'javax.swing.JButton') new:'Click'.

"/creating a new mouse listener and adding callback blocks
listener := (java getJavaClass:'java.awt.event.MouseListener') new.

listener implementMethod:'mousePressed' as:[ Transcript showCR:'onPress'. frame setTitle:'onPressed' ].
listener implementMethod:'mouseReleased' as:[ Transcript showCR:'onReleased'. frame setTitle:'onReleased' ].
listener implementMethod:'mouseExited' as:[ Transcript showCR:'onExited'. java closeBridge. ].

"/register the mouse listener on the button and make the frame with button visible
button addMouseListener:listener.
frame add:button.
frame setSize:300 y:100.
frame setVisible: true.
</PRE></CODE>



==Differences between v1 and v2==
===General===
* A Java Bridge instance no longer requires multiple tcp ports to be open. This simplifies connection through ssh tunnels and firewalls.
* The identity of strings and primitve wrappers can now be preserved. (see [[#boxedDo:aBlock | boxedDo]])
* Simplified instantiation and access of arrays. (see [[#Arrays | Arrays]])
* Every request to the java side can now be done asynchronously. (see [[#Asynchronous Communication | Asynchronous Communication]])

===Loading Applications===
* '''addJarByPath:''' and '''addToClassPath:''' are still supported but have been deprecated. use '''loadJar:''', '''loadJarByPath:''' and '''loadExtension:''' instead. The new methods no longer require the jar or library to be present on the remote machine.

[[Java Interface Library#Loading Applications (from the expecco side) | v1]] [[#Loading Applications (from the expecco side) | v2]]

===Java Class Access===
* Sending the fully qualified name with instances of "." replaced by "_" to the bridge handle is still supported, but not recommended.
* A new method '''getJavaClass:''' has been introduced (also available for v1 since expecco v2.9). This solves the side effects of "_" being a legal character in class names.

[[Java Interface Library#Java Package Import and Class Access | v1]] [[#Java Class Access | v2]]
===Callbacks from Java===
* A new method '''implementMethod:as:''' has been introduced to assign callback blocks to method names. The old way is still supported.

[[Java Interface Library#Callbacks from Java | v1]] [[#Callbacks from Java | v2]]

===Remote Dynamic Code Injection===
* Code injection was problematic in v1 and has now been re-implemented in v2.

[[#Remote Dynamic Code Injection | v2]]

== API ==
===JAVA::Java===
====class protocol====
=====newWithServer=====
* This will start a local JavaVM, running the JavaBridge, and establishes a connection on a random free port.
: A new connected instance of JAVA::Java class is returned.

=====newWithServerForJavaPath:aJavaPathFilename=====
* This is the same as newWithServer but the path to the java executable can be specified. The JavaVM version must be 1.6 or higher to run the JavaBridge.
:: '''aJavaPathFilename''' - must be a instance of Filename
Smalltalk: JAVA::Java newWithServerForJavaPath:('my\path\to\java.executable'asFilename).
JavaScript: JAVA::Java.newWithServerForJavaPath("my\path\to\java.executable".asFilename());

=====newConnectedTo:aHhostString port:aPortNumber withTimeout:aTimeoutSeconds=====
* This is used to connect to a running JavaBridge on the network. The JavaBridge must be started in server mode on the remote host. After connecting a new connected instance of JAVA::Java is returned.
:: '''aHostString''' - the hostname or IP of the remote machine as String
:: '''aPortNumber ''' - the port on which the remote machine is listening as Number
:: '''aTimeoutSeconds''' - a connect timeout in seconds as Number
Smalltalk: JAVA::Java newConnectedTo:'myHostName' port:4567 withTimeout:30.
JavaScript: JAVA::Java.newConnectedTo_port_withTimeout("myHostName",4567,30);

=====newWaitingForConnectOnHost:aListeningAddressString port:aListeningPortNumber withTimeout:aTimeoutSeconds=====
* This is used to wait for incomming connecions of a running JavaBridge on the network. The JavaBridge must be started in client mode on the remote host. After connecting a new connected instance of JAVA::Java is returned.
:: '''deprecated: aListeningAddressString''' - no longer used. Can be nil.
:: '''aListeningPortNumber ''' - the port on which to listen for incomming connections as Number
:: '''aTimeoutSeconds''' - a connect timeout in seconds as Number, If nil it will wait endless.

=====singletonInstance=====
* This will call newWithServer for the first time and then always returns the same connected JAVA::Java instance until the connection was closed, then a new connected instance is returned.

=====exitAllInstances=====
* This will close all instances of JAVA::Java.

====instance protocol====
=====loadJarByPath:aPath=====
* Adds a jar to the running JavaVM. If the jar depends on other jars or libraries you have to add them too.
:: '''aPath''' - the path to the jar file as String.

=====loadJar:aByteArray=====
* Adds a jar to the running JavaVM. If the jar depends on other jars or libraries you have to add them too.
:: '''aByteArrays''' - a ByteArray containing the JAR file.

=====loadExtension:aPath=====
* Adds a jar to the running JavaVM and caches it for subsequent usages. If the jar depends on other jars you have to add them too.
:: '''aPath''' - the path to the jar file as String.

=====boxedDo:aBlock=====
* Any autoboxed values in aBlock returned from the JavaVM are preserved as such. By default autoboxed values are automatically unboxed. This way, the identity of such objects is preserved.

=====isConnected=====
* Tests if a connection is still established.
:: '''return:''' - true if the connection is still established, else false.

=====isAlive=====
* Tests if a connection is still responding.
:: '''return:''' - true if the connection is still alive, else false. Does a message round trip.

=====closeBridge=====
* This will close the bridge connection. Depending on in which mode the JavaBridge was started, the JavaVM is also closed (-keepAlive startparameter not set).

=====exit=====
* Same as closeBridge.

== See Also==
The [[DOT NET Interface Library| DOTNET Interface Plugin & Library]], which implements a likewise interface for .NET applications/libraries.
 
[[Java Interface Library | Version 1 of the Java Interface Library]]
<hr>
Back to [[Plugins]]

Java Interface Library v2

2016-06-01T12:36:52Z

Javogel:

== Introduction ==

This article discusses version 2 of the Java Bridge (which is as of expecco v2.9 still experimental).
The article for version 1 can be found [[Java Interface Library | here]].

The Java Interface library ("Java Bridge") is used to interact with Java objects inside an external Java Virtual Machine (JVM).

The access to Java objects, classes and programs is done via a framework called "''Java-Bridge''", which is similar in operation to the [[DOT NET Interface Library| dotNET bridge]]. This framework implements transparent forwarding of method (virtual function) calls to Java objects, which exist in a local or remote Java Virtual Machine (JVM). Also, return values, callBacks and exception information are passed back from the Java program to expecco. This is done by a proxy-object mechanism, which catches all function calls, wraps the arguments, sends a datagram to the other bridge side, awaits the reply and returns the result to the original caller. Thus, remote procedure calls are almost completely transparent to the Smalltalk/JavaScript code inside expecco. In your elementary code, you can write remote function calls as if they were to local objects.

Notice that this document describes the low level framework, which implements the bridge communication. A much easier to use high level interface (called "Groovy Blocks") exists and should normally be used, if you need access to a java application's internals during testing.
Please take a look at
[[Expecco_API#Groovy_Elementary_Blocks | "Groovy Block API"]]
and [[Testing Java Applications using Groovy blocks/en | "Testing Java Applications using Groovy blocks"]].

== Architecture ==

On the expecco side, the bridge consists of a number of Proxy objects,
which behave like regular Smalltalk objects as seen from elementary expecco code.
However, instead of performing an action when one of their methods (virtual functions) is called,
they send a message over a socket connection to the Java VM (actually: to a bridge software inside the
Java application) which decodes the message and sends it to the destination Java object.
The same is done in reverse direction with the return value.

+---------------------+ +----------+ +----------------+ +----------------+ +---------+
| | | | | | | | | Java |
| expecco |---->| Proxy |---->| Bridge |==>>==| Bridge |---->| Object |
| (elementary code) |<----| |<----| (expecco side) |==<<==| (Java side) |<----| |
+---------------------+ +----------+ +----------------+ +----------------+ +---------+

This setup allows for transparent communication with objects inside a local or remote Java VM. This may be either utility functions which happen to be convenient for the test application (for example: file parsing, syntax analysis, protocol implementaitons or access to specific hardware via driver libraries), or the tested application in the system under test itself.

Especially, it allows for the objects of the tested application to be looked into, manipulated and for functions of it or underlying frameworks to be called.

For expecco code, we tried to make this as transparent as possible, however there are a few exceptions, when function names need to be translated (for example, because the function naming syntax is different) or due to the fact that for some operations no corresponding name exists in Smalltalk (array access, for example).

Of course, multiple such connections can coexist and be served/handled in parallel. This enables an expecco test suite to communicate with both sides of a tested client-server Java application, for example.

Notice that a similar mechanism is used in expecco to communicate with DOTNET, Qt (C++) and C applications.

 

== Activating the new Java Bridge ==
To activate the new bridge in expecco navigate to ''Extras'' ► ''Settings'' ► ''Plugins'' ► ''Java Bridge'' and tick the ''Use new Bridge (experimental)'' checkbox.
[[Datei:ActivateNewJavaBridge.png]]

'''Attention:''' Ticking the checkbox will terminate all currently active Bridge connections due to incompatibilities between the new and the old version.

== Initializing / Releasing the Bridge ==

Before any communication can take place between expecco and any Java object, the Java side of the bridge has to be started, and a communication has to be established.
In expecco, all of the bridge classes are found in the <CODE>JAVA</CODE> namespace.

The main interface class is "<CODE>Java</CODE>", in the "<CODE>JAVA</CODE>" namespace:
<CODE><PRE>
java := JAVA::Java newWithServer.
</PRE></CODE>
or (in JavaScript):
<CODE><PRE>
java = JAVA::Java.newWithServer();
</PRE></CODE>

This starts the Java-side of the bridge (actually executes java as a background command) on the local machine, and establishes a connection to that JVM.

The bridge connection should be closed, if the bridge is no longer needed. Release the bridge with:
<CODE><PRE>
java.closeBridge();
</PRE></CODE>
which terminates the connection.

=== Start and Connect to a Remote Machine ===
The above started a Java VM and connected to it. Alternatively, you may want to connect to an already running Java program (typically, your system under test).
In order for your program to be reachable, it must allow for the bridge to connect to it via a special bridge-connection, which is a socket connection. For this, it must execute the server code found in the "JavaBridge.jar" file. To pass [[#Startup Parameters| parameters]] you will typically start it from a command line or a little shell/batch script.

Call (on the shell/cmd level):
$ java -jar <PATH_TO_JAVABRIDGE.JAR> <PARAMETERS>

The "JavaBridge.jar" file is found in the installation directory of expecco at:
\exept\expecco\packages\exept\bridgeFramework\javaBridge\javaBin\JavaBridge.jar

The Javabridge code allows for either side to initiate the connection - i.e. it can be run in server mode,
where it awaits an incoming connection, or in client mode, where it actively initiates a connection.
After connection establishment, there is no difference in the operation of the bridge, however depending on the setup of your network infrastructure, especially firewalls, either mechanism may be easier to be used.

Assuming that the bridge is already running on the remote machine as server (default),
use <CODE>newConnectedTo:port:withTimeout:</CODE> to connect to it from the expecco side:
java := JAVA::Java newConnectedTo:'myHost' port:4567 withTimeout:30.
This will initiate the connection setup from the expecco side.

Alternatively, if started in client mode use <CODE>newWaitingForConnectOnHost:port:withTimeout:</CODE>:
java := JAVA::Java newWaitingForConnectOnHost:'localhost' port:4567 withTimeout:30.
which will open a port on the expecco side, and wait until the Java side connects to it.
[[#JAVA::Java|For more details see API]]

====Startup Parameters====
You can use any parameter in any order.
If no parameter is used then the bridge listenes on port 14014 in server mode without keepAlive.
;<code>-help</code>
* Shows the help

;<code>-ip <aHostnameOrIP></code>
* In client mode this specifies the ip or hostname to connect to. In server mode this specifies the ip or hostname to bind to.

;<code>-port <aPortNumber> </code>
* In client mode this specifies the port to connect to. In server mode this specifies the listening port.

;<code>-asClient</code>
* The bridge will start in client mode. If not set the bridge is started in server mode.

;<code>-keepAlive</code>
* By setting this flag the bridge will not exit after the connection has closed and starts to connect or listen again. Otherwise, it will run for a single connection session only.

== Loading Applications (from the expecco side) ==

Normally, you would start your application with the required command line arguments and include the javabridge as jar there. However, in some situations, it may be required to dynamically load other jars into the connected Java VM.
By accessing a classloader, additional classes, or applications as contained in JAR files can be loaded from the expecco side.

This can be used to add a JAR file to the classloader:
<CODE><PRE>
java loadJarByPath:'pathToJarFile'. "/ assuming "java" is a handle as returned from the above connect
</PRE></CODE>

or, if the JAR file is loaded in memory:
<CODE><PRE>
java loadJar:jarByteArray. "/ where "jarByteArray" is a ByteArray containing the JAR file
</PRE></CODE>

If the JVM is on a remote machine, the path is resolved on the expecco side and the JAR will be transferred to the remote side.

Should transferring the JAR be too much overhead, an additional mechanism is provided:
<CODE><PRE>
java loadExtension:'pathToJarFile'.
</PRE></CODE>
this will cache the JAR file on the bridge side and eliminate the overhead of subsequent invocations.

== Java Class Access ==

This following code sample simply references (i.e. accesses) the class "JFrame" from the <CODE>"javax.swing"</CODE> package. The fully specified class name in Java would be <CODE>"javax.swing.JFrame"</CODE>:
<CODE><PRE>
java getJavaClass:'javax.swing.JFrame'
</PRE></CODE>

Or, if you want to load multiple classes:
<CODE><PRE>
java import:'javax.swing.JFrame' import:'javax.swing.JButton'
do:[:jFrame :jButton | "do something with JButton and JFrame" ].
</PRE></CODE>

v2 also supports dynamic compilation of java source code:
<CODE><PRE>
java getJavaClass:'className' fromSource:'classSource'. "/ where classSource is a String containing valid java source code
</PRE></CODE>

and loading precompiled java bytecode:
<CODE><PRE>
java getJavaClass:'className' fromByteCode:byteCode. "/ where byteCode is a ByteArray containing valid java bytecode
</PRE></CODE>

[[#Remote Dynamic Code Injection | for details see Remote Dynamic Code Injection]]

== Instantiating a Class ==

Object instances are created via the "new"-message, sent to a proxy of a Java class. You can get this proxy as described in the previous section. For example, if we want to create a new instance of a "JFrame" and a "JButton", write:
<CODE><PRE>
frame := java getJavaClass:'javax.swing.JFrame' new.
button := java getJavaClass:'javax.swing.JButton' new.
</PRE></CODE>
The first statement results in a proxy object for the "JFrame" instance. The second line results in a proxy for a new "JButton" object.

== Calling Instance Methods ==

A method call is done by a message send to a proxy object, where the message is the method name to call. For example, to call the <CODE>"setVisible(boolean isVisible)"</CODE> method on the above JFrame object, we send the following message to that proxy:
<CODE><PRE>
frame setVisible:true.
</PRE></CODE>

As method naming is different in Smalltalk and Java, a dynamic translation is applied when sending messages from Smalltalk code to a remote Java object. Smalltalk has arguments embedded inside parts of a so called "keyword" message, such as in "receiver foo:arg1 bar:arg2", where "foo:bar:" would be the message name, and "arg1", "arg2" be the arguments.

In Java, the message name is a single identifier, and arguments are written in an argument list after the message name: "receiver.fooBar(arg1, arg2)".

When message names are translated, only the very first part of the Smalltalk keyword message is taken ("foo" in the above example), and the remaining parts are simpl ignored. Thus, any of the Smalltalk messages "foo:bar:", "foo:xxxx:" and "foo:_:" (a single underscore as second part) all translate to the same Java message name "foo()".

Therefore, to call a method with more than one argument, like <CODE>"setSize(int width,int height)"</CODE> on a JFrame instance we can write:
<CODE><PRE>
frame setSize:300 _:200.
</PRE></CODE>
but just as well:
<CODE><PRE>
frame setSize:300 anyWord:200.
</PRE></CODE>
or any other selector with "setSize:" as its first component.
The selector translation mechanism simply takes the first part as the Java selector.

In practice, you should take a reasonably descriptive name, such as: "frame setSize:300 height:200" or only the Java name as first part, such as "frame setSize:300 _:200".

For a call of a method with 4 arguments, we could write:
<CODE><PRE>
frame setBounds:100 y:50 width:300 height:200.
</PRE></CODE>
or:
<CODE><PRE>
frame setBounds:100 _:50 _:300 _:200.
</PRE></CODE>

Also here the <CODE>"y: width: height:"</CODE> can be named as you want, but the first part must be "setBounds:".

=== Calling Static Methods ===

Calling a static method on an object is not different from calling non static methods. In most cases you will call a static method not on an object but directly on the class. This is done by using the class object as "receiver" of the message. For example, if we want to call the static method <CODE>"isDefaultLookAndFeelDecorated()"</CODE> of the JFrame class, write:
<CODE><PRE>
java getJavaClass:'javax.swing.JFrame' isDefaultLookAndFeelDecorated.
</PRE></CODE>

== Accessing Fields ==

As Smalltalk does not support access of an object's fields from the outside (it is fully encapsulated, and access from outside is ONLY allowed via getters/setters), an additional translation mechanism is provided for field access.

Accessing a field of a Java object or a class's static field uses the same syntax as method calls. To access a field, send a message where the message is the field name. To access the field of a class the field must be static.
For example, to get the value of the static field named <CODE>"EXIT_ON_CLOSE"</CODE> of the "JFrame" class, write
<CODE><PRE>
value := java getJavaClass:'javax.swing.JFrame' EXIT_ON_CLOSE.
</PRE></CODE>
The variable "value" now holds the integer value of the <CODE>"EXIT_ON_CLOSE"</CODE> constant.

Assuming that a "JFrame" object had a field named <CODE>"myField"</CODE>, to access this field, we'd have to write:
<CODE><PRE>
value := frame myField.
</PRE></CODE>
and "value" now holding whatever <CODE>"myField"</CODE> returns. This could be another object reference or any primitive value.

=== Setting Fields ===
To set a field, use a setter-like method call:
<CODE><PRE>
frame myField: newValue.
</PRE></CODE>

=== Name Conflicts ===

In very rare situations, a Java object may contain both a field and a method by the same name.
In this case, the Smalltalk code cannot depend on the dynamic translation mechanism (which actually looks for either a field or method name to match), but instead make it explicit, which operation is wanted:
Use:
<CODE><PRE>
frame getFieldByName:'myField'
</PRE></CODE>
to read a field, and:
<CODE><PRE>
frame setFieldByName:'myField' value:123.
</PRE></CODE>
to write the field.

If there are both fields and methods by the same name, and you use the non-explicit call,
the bridge will always assume that you want to call the getter/setter and perform a method call.
 

== Arrays ==

=== Passing Smalltalk Collections to Java ===

Smalltalk collections can now be directly passed to Java with a few limitations:
* The identity of the Smalltalk collections will not be preserved. passing the same collection to java multiple times will result in multiple instances of the same array on the java side. (to bypass this instantiate a new java array)
* Smalltalk collections need to be explicitly converted to the correct type (e.g. a <CODE>SignedIntegerArray</CODE> on the smalltalk side matches an <CODE>int</CODE>-Array on the java side)

=== Instantiating Arrays ===

The new bridge supports instantiation of arrays (whereas previously reflection had to be used to instantiate arrays from the smalltalk side).
There are two ways an array can be instantiated:

<CODE><PRE>
intArray := (java getJavaClass:'int[]') new:#[ 1 2 3 4 5 ] asSignedIntegerArray. "/ instantiates a new array of type "int" with the contents "1, 2, 3, 4, 5"
</PRE></CODE>

<CODE><PRE>
intArray := (java getJavaClass:'int[]') new:10. "/ instantiates a new empty array of type "int" with 10 elements.
</PRE></CODE>

=== Accessing Arrays ===

To achieve better performance, arrays of primitive types smaller than a certain size have their contents cached on the smalltalk side:
<CODE><PRE>
intArray contents at:1. "/ this will access the first element of the cached contents.
</PRE></CODE>

large arrays are not serialized immediately. large arrays will be serialized when <CODE>contents</CODE> is called the first time.

'''Attention:''' Java arrays are not immutable. changes to an array are not reflected in the cached contents. if an array has been updated, call <CODE>refresh</CODE> on the array to update the cache. arrays will not be updated automatically.

<CODE><PRE>
shortArray := (java getJavaClass:'short[]') new:10. "/ new empty "short" array with 10 elements

"/ copy the contents of the smalltalk collection to the newly instantiated short array
(java getJavaClass:'java.lang.System') arraycopy:(#[ 1 2 3 ] asSignedWordArray) srcPos:0 dest:shortArray destPos:0 length:3.

shortArray at:0. "/ will reflect the changes made to the array

shortArray contents at:1. "/ will still return 0 because the cached contents have not been updated.

shortArray refresh. "/ update the cached contents

shortArray contents at:1. "/ will now correctly reflect the changes made to the array
</PRE></CODE>

== Boxed Primitives ==

In version 1 of the java bridge boxed primitives were unboxed automatically and the identity was not preserved.
In version 2 a mechanism is provided allowing to preserve the identity of boxed primitives: [[ #boxedDo:aBlock | boxedDo:aBlock ]].

Example:
<CODE><PRE>
java boxedDo:[
boxedInt := java getJavaClass:'java.lang.Integer' new:30. "/ instantiate a new boxed integer. boxedInt now holds a reference to this integer and not the value
].
intValue := boxedInt value. "/ extract the value of the boxed integer. (does not require a roundtrip)
</PRE></CODE>

== Asynchronous Communication ==

In the new Bridge, everything can be done asynchronously. This is achieved via the <CODE>asyncDo:aBlock</CODE> method.
Every request sent to the Bridge inside of aBlock will immediately return a lazy value.
This lazy value will block upon access until the actual result is received from the java side.
The order of execution is guaranteed to be the same on the java side as on the smalltalk side.

Example:
<CODE><PRE>
java asyncDo:[
lazyInteger := (java getJavaClass:'java.lang.Integer') new:40. "/ this will return immediately
].
actualInteger := lazyInteger value. "/ this will block until the result is available
</PRE></CODE>

== Callbacks from Java ==
Sometimes you may want to execute a piece of Smalltalk code during the execution of the Java code. For example, we may want to install a Smalltalk observer to be notified when a button on a Java GUI was pressed,
or some other callback from a Java framework.

The following code registers a Smalltalk block as a callback for a mouse press event of a button:
<CODE><PRE>
listener := MouseListener new.
listener implementMethod:'mousePressed' as:[ Transcript showCR:'Hello from Java' ].
</PRE></CODE>
The above creates the callback and the listener, which can now be registered on a button:
<CODE><PRE>
button addMouseListener:listener.
</PRE></CODE>
Now, with the press of the button in the Java GUI, the Smalltalk block will be executed and writes <CODE>"Hello from Java"</CODE> to the Smalltalk console.
Of course, any other (Smalltalk-)action code can be made to run via this mechanism.

But be aware, that the callback is possibly called later (when the elementary action, which installed the code, has already finished long ago). Also, as the Java code execution is not synchronized with any of your expecco action execution, the callback may also be called at any arbutrary time, even at times when no activity at all is executed on the expecco side. If you forget to cleanup, and the Java object is still alive, it may even be called after you have finished your test run (if you keep the java bridge handle around and alive, for example in an expecoo environment variable).

So the Smalltalk callback code should not depend on any particular elementary action to be currently running, but instead in most cases write some information into a shared data container, preferably an instance of "SharedQueue", which is thread safe. Then, some other action (an elementary action) would read-wait and read events from that shared queue.

make sure that your test correctly cleans up any such callbacks afterwards. As a last resort, use the "Shutdown Bridge Connection" menu item, which closes the bridge connection, and thereby - as a side effect - removes any leftover callbacks. It does close the connection, and any remaining java proxy object handles become invalid, though.

Another example, using an observer could look like:
<CODE><PRE>
observer := java Observer new.
observer implementMethod:'update'
as:[:sourceObservable :argument|
argument notNil ifTrue:[ Transcript showCR:('I was notifyed with: ',argument toString) ]
ifFalse:[ Transcript showCR:'I was notifyed and the argument was nil' ].
].
myObservable addObserver:observer.
</PRE></CODE>
When the observable calls <CODE>"notifyObservers"</CODE>, the Smalltalk block will be executed.

== Exceptions in Java ==
Exceptions on the Java side are signalled back to the Smalltalk side and raise a corresponding exception there. However, on the Java side, the call stack which lead to the exception has already been unwound at that time (Java exceptions are not proceedable). So a proceed in the Smalltalk-side exception handler only affects the Smalltalk caller, but may leave the Java side in an undefined state.

== Remote Dynamic Code Injection ==
Sometimes we might want to execute code without the overhead of many rpc-messages being sent over the bridge, especially if we want to do something time critical, or want to make execution time measurements.
For this, it is possible to load a class at runtime into the JavaVM. The code of the class will first be sent to the JavaVM, which will compile and load the generated byte code. Then, the class can be accessed via the bridge just like any other preloaded class.

The following example specifies the class code in a smalltalk string and inject the code into the JavaVM. Then an instance of that new class will be instantiated and finally a method of the object instance will be invoked:
<CODE><PRE>
classCode := '
package myPackage.test;

import java.awt.BorderLayout;
import java.awt.event.MouseAdapter;
import java.awt.event.MouseEvent;
import java.util.Calendar;

import javax.swing.JButton;
import javax.swing.JFrame;
import javax.swing.JLabel;;

public class MyInjectedClass {
public void createSampleApp(){
JFrame frame=new JFrame("Hello im injected");
frame.setLayout(new BorderLayout());
JButton button=new JButton("click me");
final JLabel label=new JLabel("Text");
button.addMouseListener(new MouseAdapter() {

@Override
public void mouseClicked(MouseEvent e) {
label.setText(Calendar.getInstance().getTime().toString());
}
});
frame.add(label,BorderLayout.NORTH);
frame.add(button,BorderLayout.SOUTH);
frame.setSize(300, 300);
frame.setVisible(true);
}
}
'.
classObject := java getJavaClass:'myPackage.test.MyInjectedClass' fromSource:classCode.
classObject new createSampleApp.
</PRE></CODE>
After the code has been injected, a new instance of <CODE>"MyInjectedClass"</CODE> is created and the <CODE>"createSampleApp"</CODE> method is called. Because the example implements a GUI, a Java window will open, containing a label and a button. Clicking the button displays the current time in the label.



=== Code Sources for Class injection ===
There are 3 possible types of class code sources which we can use to inject the code. In the examples before we directly used a simple <CODE>"String"</CODE> in the smalltalk code as a code source. We also can use a <CODE>"*.java"</CODE> file as source. Just read the content of the file into a string and use it as in the previous examples.

To inject a <CODE>"*.class"</CODE> file use the following code:
<pre>
java getJavaClass:'the.class.name' fromByteCode:classCode.
</pre>

== Examples ==

This example creates a JFrame with one button inside. Then a Mouselistener is created and registered on the button. When the button is pressed, the title of the window changes to <CODE>"onPressed"</CODE> and the Transcript shows the message <CODE>"onPressed"</CODE>. When the button is released, the title of the window is changed to <CODE>"onReleased"</CODE> and the Transcript shows <CODE>"onReleased"</CODE>. If the button lost the mouse focus, the bridge will exit (disconnect), and the Java side is terminated.
<CODE><PRE>
|java frame button listener|

"/getting a bridge
java := JAVA::JavaBridge newWithServer.

"/creating a new frame and button object
frame := java getJavaClass:'javax.swing.JFrame' new.
button := (java getJavaClass:'javax.swing.JButton') new:'Click'.

"/creating a new mouse listener and adding callback blocks
listener := (java getJavaClass:'java.awt.event.MouseListener') new.

listener implementMethod:'mousePressed' as:[ Transcript showCR:'onPress'. frame setTitle:'onPressed' ].
listener implementMethod:'mouseReleased' as:[ Transcript showCR:'onReleased'. frame setTitle:'onReleased' ].
listener implementMethod:'mouseExited' as:[ Transcript showCR:'onExited'. java closeBridge. ].

"/register the mouse listener on the button and make the frame with button visible
button addMouseListener:listener.
frame add:button.
frame setSize:300 y:100.
frame setVisible: true.
</PRE></CODE>



==Differences between v1 and v2==
===General===
* A Java Bridge instance no longer requires multiple tcp ports to be open. This simplifies connection through ssh tunnels and firewalls.
* The identity of strings and primitve wrappers can now be preserved. (see [[#boxedDo:aBlock | boxedDo]])
* Simplified instantiation and access of arrays. (see [[#Arrays | Arrays]])
* Every request to the java side can now be done asynchronously. (see [[#Asynchronous Communication | Asynchronous Communication]])

===Loading Applications===
* '''addJarByPath:''' and '''addToClassPath:''' are still supported but have been deprecated. use '''loadJar:''', '''loadJarByPath:''' and '''loadExtension:''' instead. The new methods no longer require the jar or library to be present on the remote machine.

[[Java Interface Library#Loading Applications (from the expecco side) | v1]] [[#Loading Applications (from the expecco side) | v2]]

===Java Class Access===
* Sending the fully qualified name with instances of "." replaced by "_" to the bridge handle is still supported, but not recommended.
* A new method '''getJavaClass:''' has been introduced (also available for v1 since expecco v2.9). This solves the side effects of "_" being a legal character in class names.

[[Java Interface Library#Java Package Import and Class Access | v1]] [[#Java Class Access | v2]]
===Callbacks from Java===
* A new method '''implementMethod:as:''' has been introduced to assign callback blocks to method names. The old way is still supported.

[[Java Interface Library#Callbacks from Java | v1]] [[#Callbacks from Java | v2]]

===Remote Dynamic Code Injection===
* Code injection was problematic in v1 and has now been re-implemented in v2.

[[#Remote Dynamic Code Injection | v2]]

== API ==
===JAVA::Java===
====class protocol====
=====newWithServer=====
* This will start a local JavaVM, running the JavaBridge, and establishes a connection on a random free port.
: A new connected instance of JAVA::Java class is returned.

=====newWithServerForJavaPath:aJavaPathFilename=====
* This is the same as newWithServer but the path to the java executable can be specified. The JavaVM version must be 1.6 or higher to run the JavaBridge.
:: '''aJavaPathFilename''' - must be a instance of Filename
Smalltalk: JAVA::Java newWithServerForJavaPath:('my\path\to\java.executable'asFilename).
JavaScript: JAVA::Java.newWithServerForJavaPath("my\path\to\java.executable".asFilename());

=====newConnectedTo:aHhostString port:aPortNumber withTimeout:aTimeoutSeconds=====
* This is used to connect to a running JavaBridge on the network. The JavaBridge must be started in server mode on the remote host. After connecting a new connected instance of JAVA::Java is returned.
:: '''aHostString''' - the hostname or IP of the remote machine as String
:: '''aPortNumber ''' - the port on which the remote machine is listening as Number
:: '''aTimeoutSeconds''' - a connect timeout in seconds as Number
Smalltalk: JAVA::Java newConnectedTo:'myHostName' port:4567 withTimeout:30.
JavaScript: JAVA::Java.newConnectedTo_port_withTimeout("myHostName",4567,30);

=====newWaitingForConnectOnHost:aListeningAddressString port:aListeningPortNumber withTimeout:aTimeoutSeconds=====
* This is used to wait for incomming connecions of a running JavaBridge on the network. The JavaBridge must be started in client mode on the remote host. After connecting a new connected instance of JAVA::Java is returned.
:: '''deprecated: aListeningAddressString''' - no longer used. Can be nil.
:: '''aListeningPortNumber ''' - the port on which to listen for incomming connections as Number
:: '''aTimeoutSeconds''' - a connect timeout in seconds as Number, If nil it will wait endless.

=====singletonInstance=====
* This will call newWithServer for the first time and then always returns the same connected JAVA::Java instance until the connection was closed, then a new connected instance is returned.

=====exitAllInstances=====
* This will close all instances of JAVA::Java.

====instance protocol====
=====loadJarByPath:aPath=====
* Adds a jar to the running JavaVM. If the jar depends on other jars or libraries you have to add them too.
:: '''aPath''' - the path to the jar file as String.

=====loadJar:aByteArray=====
* Adds a jar to the running JavaVM. If the jar depends on other jars or libraries you have to add them too.
:: '''aByteArrays''' - a ByteArray containing the JAR file.

=====loadExtension:aPath=====
* Adds a jar to the running JavaVM and caches it for subsequent usages. If the jar depends on other jars you have to add them too.
:: '''aPath''' - the path to the jar file as String.

=====boxedDo:aBlock=====
* Any autoboxed values in aBlock returned from the JavaVM are preserved as such. By default autoboxed values are automatically unboxed. This way, the identity of such objects is preserved.

=====isConnected=====
* Tests if a connection is still established.
:: '''return:''' - true if the connection is still established, else false.

=====isAlive=====
* Tests if a connection is still responding.
:: '''return:''' - true if the connection is still alive, else false. Does a message round trip.

=====closeBridge=====
* This will close the bridge connection. Depending on in which mode the JavaBridge was started, the JavaVM is also closed (-keepAlive startparameter not set).

=====exit=====
* Same as closeBridge.

== See Also==
The [[DOT NET Interface Library| DOTNET Interface Plugin & Library]], which implements a likewise interface for .NET applications/libraries.
 
[[Java Interface Library | Version 1 of the Java Interface Library]]
<hr>
Back to [[Plugins]]

Java Interface Library v2

2016-06-01T12:19:09Z

Javogel: /* Activating the new Java Bridge */

== Introduction ==

This article discusses version 2 of the Java Bridge (which is as of expecco v2.9 still experimental).
The article for version 1 can be found [[Java Interface Library | here]].

The Java Interface library ("Java Bridge") is used to interact with Java objects inside an external Java Virtual Machine (JVM).

The access to Java objects, classes and programs is done via a framework called "''Java-Bridge''", which is similar in operation to the [[DOT NET Interface Library| dotNET bridge]]. This framework implements transparent forwarding of method (virtual function) calls to Java objects, which exist in a local or remote Java Virtual Machine (JVM). Also, return values, callBacks and exception information are passed back from the Java program to expecco. This is done by a proxy-object mechanism, which catches all function calls, wraps the arguments, sends a datagram to the other bridge side, awaits the reply and returns the result to the original caller. Thus, remote procedure calls are almost completely transparent to the Smalltalk/JavaScript code inside expecco. In your elementary code, you can write remote function calls as if they were to local objects.

Notice that this document describes the low level framework, which implements the bridge communication. A much easier to use high level interface (called "Groovy Blocks") exists and should normally be used, if you need access to a java application's internals during testing.
Please take a look at
[[Expecco_API#Groovy_Elementary_Blocks | "Groovy Block API"]]
and [[Testing Java Applications using Groovy blocks/en | "Testing Java Applications using Groovy blocks"]].

== Architecture ==

On the expecco side, the bridge consists of a number of Proxy objects,
which behave like regular Smalltalk objects as seen from elementary expecco code.
However, instead of performing an action when one of their methods (virtual functions) is called,
they send a message over a socket connection to the Java VM (actually: to a bridge software inside the
Java application) which decodes the message and sends it to the destination Java object.
The same is done in reverse direction with the return value.

+---------------------+ +----------+ +----------------+ +----------------+ +---------+
| | | | | | | | | Java |
| expecco |---->| Proxy |---->| Bridge |==>>==| Bridge |---->| Object |
| (elementary code) |<----| |<----| (expecco side) |==<<==| (Java side) |<----| |
+---------------------+ +----------+ +----------------+ +----------------+ +---------+

This setup allows for transparent communication with objects inside a local or remote Java VM. This may be either utility functions which happen to be convenient for the test application (for example: file parsing, syntax analysis, protocol implementaitons or access to specific hardware via driver libraries), or the tested application in the system under test itself.

Especially, it allows for the objects of the tested application to be looked into, manipulated and for functions of it or underlying frameworks to be called.

For expecco code, we tried to make this as transparent as possible, however there are a few exceptions, when function names need to be translated (for example, because the function naming syntax is different) or due to the fact that for some operations no corresponding name exists in Smalltalk (array access, for example).

Of course, multiple such connections can coexist and be served/handled in parallel. This enables an expecco test suite to communicate with both sides of a tested client-server Java application, for example.

Notice that a similar mechanism is used in expecco to communicate with DOTNET, Qt (C++) and C applications.

 

== Activating the new Java Bridge ==
To activate the new bridge in expecco navigate to ''Extras'' ► ''Settings'' ► ''Plugins'' ► ''Java Bridge'' and tick the ''Use new Bridge (experimental)'' checkbox.
[[Datei:ActivateNewJavaBridge.png]]

'''Attention:''' Ticking the checkbox will terminate all currently active Bridge connections due to incompatibilities between the new and the old version.

== Initializing / Releasing the Bridge ==

Before any communication can take place between expecco and any Java object, the Java side of the bridge has to be started, and a communication has to be established.
In expecco, all of the bridge classes are found in the <CODE>JAVA</CODE> namespace.

The main interface class is "<CODE>Java</CODE>", in the "<CODE>JAVA</CODE>" namespace:
<CODE><PRE>
java := JAVA::Java newWithServer.
</PRE></CODE>
or (in JavaScript):
<CODE><PRE>
java = JAVA::Java.newWithServer();
</PRE></CODE>

This starts the Java-side of the bridge (actually executes java as a background command) on the local machine, and establishes a connection to that JVM.

The bridge connection should be closed, if the bridge is no longer needed. Release the bridge with:
<CODE><PRE>
java.closeBridge();
</PRE></CODE>
which terminates the connection.

=== Start and Connect to a Remote Machine ===
The above started a Java VM and connected to it. Alternatively, you may want to connect to an already running Java program (typically, your system under test).
In order for your program to be reachable, it must allow for the bridge to connect to it via a special bridge-connection, which is a socket connection. For this, it must execute the server code found in the "JavaBridge.jar" file. To pass [[#Startup Parameters| parameters]] you will typically start it from a command line or a little shell/batch script.

Call (on the shell/cmd level):
$ java -jar <PATH_TO_JAVABRIDGE.JAR> <PARAMETERS>

The "JavaBridge.jar" file is found in the installation directory of expecco at:
\exept\expecco\packages\exept\bridgeFramework\javaBridge\javaBin\JavaBridge.jar

The Javabridge code allows for either side to initiate the connection - i.e. it can be run in server mode,
where it awaits an incoming connection, or in client mode, where it actively initiates a connection.
After connection establishment, there is no difference in the operation of the bridge, however depending on the setup of your network infrastructure, especially firewalls, either mechanism may be easier to be used.

Assuming that the bridge is already running on the remote machine as server (default),
use <CODE>newConnectedTo:port:withTimeout:</CODE> to connect to it from the expecco side:
java := JAVA::Java newConnectedTo:'myHost' port:4567 withTimeout:30.
This will initiate the connection setup from the expecco side.

Alternatively, if started in client mode use <CODE>newWaitingForConnectOnHost:port:withTimeout:</CODE>:
java := JAVA::Java newWaitingForConnectOnHost:'localhost' port:4567 withTimeout:30.
which will open a port on the expecco side, and wait until the Java side connects to it.
[[#JAVA::Java|For more details see API]]

====Startup Parameters====
You can use any parameter in any order.
If no parameter is used then the bridge listenes on port 14014 in server mode without keepAlive.
;<code>-help</code>
* Shows the help

;<code>-ip <aHostnameOrIP></code>
* In client mode this specifies the ip or hostname to connect to. In server mode this specifies the ip or hostname to bind to.

;<code>-port <aPortNumber> </code>
* In client mode this specifies the port to connect to. In server mode this specifies the listening port.

;<code>-asClient</code>
* The bridge will start in client mode. If not set the bridge is started in server mode.

;<code>-keepAlive</code>
* By setting this flag the bridge will not exit after the connection has closed and starts to connect or listen again. Otherwise, it will run for a single connection session only.

== Loading Applications (from the expecco side) ==

Normally, you would start your application with the required command line arguments and include the javabridge as jar there. However, in some situations, it may be required to dynamically load other jars into the connected Java VM.
By accessing a classloader, additional classes, or applications as contained in JAR files can be loaded from the expecco side.

This can be used to add a JAR file to the classloader:
<CODE><PRE>
java loadJarByPath:'pathToJarFile'. "/ assuming "java" is a handle as returned from the above connect
</PRE></CODE>

or, if the JAR file is loaded in memory:
<CODE><PRE>
java loadJar:jarByteArray. "/ where "jarByteArray" is a ByteArray containing the JAR file
</PRE></CODE>

If the JVM is on a remote machine, the path is resolved on the expecco side and the JAR will be transferred to the remote side.

Should transferring the JAR be too much overhead, an additional mechanism is provided:
<CODE><PRE>
java loadExtension:'pathToJarFile'.
</PRE></CODE>
this will cache the JAR file on the bridge side and eliminate the overhead of subsequent invocations.

== Java Class Access ==

This following code sample simply references (i.e. accesses) the class "JFrame" from the <CODE>"javax.swing"</CODE> package. The fully specified class name in Java would be <CODE>"javax.swing.JFrame"</CODE>:
<CODE><PRE>
java getJavaClass:'javax.swing.JFrame'
</PRE></CODE>

Or, if you want to load multiple classes:
<CODE><PRE>
java import:'javax.swing.JFrame' import:'javax.swing.JButton'
do:[:jFrame :jButton | "do something with JButton and JFrame" ].
</PRE></CODE>

v2 also supports dynamic compilation of java source code:
<CODE><PRE>
java getJavaClass:'className' fromSource:'classSource'. "/ where classSource is a String containing valid java source code
</PRE></CODE>

and loading precompiled java bytecode:
<CODE><PRE>
java getJavaClass:'className' fromByteCode:byteCode. "/ where byteCode is a ByteArray containing valid java bytecode
</PRE></CODE>

[[#Remote Dynamic Code Injection | for details see Remote Dynamic Code Injection]]

== Instantiating a Class ==

Object instances are created via the "new"-message, sent to a proxy of a Java class. You can get this proxy as described in the previous section. For example, if we want to create a new instance of a "JFrame" and a "JButton", write:
<CODE><PRE>
frame := java getJavaClass:'javax.swing.JFrame' new.
button := java getJavaClass:'javax.swing.JButton' new.
</PRE></CODE>
The first statement results in a proxy object for the "JFrame" instance. The second line results in a proxy for a new "JButton" object.

== Calling Instance Methods ==

A method call is done by a message send to a proxy object, where the message is the method name to call. For example, to call the <CODE>"setVisible(boolean isVisible)"</CODE> method on the above JFrame object, we send the following message to that proxy:
<CODE><PRE>
frame setVisible:true.
</PRE></CODE>

As method naming is different in Smalltalk and Java, a dynamic translation is applied when sending messages from Smalltalk code to a remote Java object. Smalltalk has arguments embedded inside parts of a so called "keyword" message, such as in "receiver foo:arg1 bar:arg2", where "foo:bar:" would be the message name, and "arg1", "arg2" be the arguments.

In Java, the message name is a single identifier, and arguments are written in an argument list after the message name: "receiver.fooBar(arg1, arg2)".

When message names are translated, only the very first part of the Smalltalk keyword message is taken ("foo" in the above example), and the remaining parts are simpl ignored. Thus, any of the Smalltalk messages "foo:bar:", "foo:xxxx:" and "foo:_:" (a single underscore as second part) all translate to the same Java message name "foo()".

Therefore, to call a method with more than one argument, like <CODE>"setSize(int width,int height)"</CODE> on a JFrame instance we can write:
<CODE><PRE>
frame setSize:300 _:200.
</PRE></CODE>
but just as well:
<CODE><PRE>
frame setSize:300 anyWord:200.
</PRE></CODE>
or any other selector with "setSize:" as its first component.
The selector translation mechanism simply takes the first part as the Java selector.

In practice, you should take a reasonably descriptive name, such as: "frame setSize:300 height:200" or only the Java name as first part, such as "frame setSize:300 _:200".

For a call of a method with 4 arguments, we could write:
<CODE><PRE>
frame setBounds:100 y:50 width:300 height:200.
</PRE></CODE>
or:
<CODE><PRE>
frame setBounds:100 _:50 _:300 _:200.
</PRE></CODE>

Also here the <CODE>"y: width: height:"</CODE> can be named as you want, but the first part must be "setBounds:".

=== Calling Static Methods ===

Calling a static method on an object is not different from calling non static methods. In most cases you will call a static method not on an object but directly on the class. This is done by using the class object as "receiver" of the message. For example, if we want to call the static method <CODE>"isDefaultLookAndFeelDecorated()"</CODE> of the JFrame class, write:
<CODE><PRE>
java getJavaClass:'javax.swing.JFrame' isDefaultLookAndFeelDecorated.
</PRE></CODE>

== Accessing Fields ==

As Smalltalk does not support access of an object's fields from the outside (it is fully encapsulated, and access from outside is ONLY allowed via getters/setters), an additional translation mechanism is provided for field access.

Accessing a field of a Java object or a class's static field uses the same syntax as method calls. To access a field, send a message where the message is the field name. To access the field of a class the field must be static.
For example, to get the value of the static field named <CODE>"EXIT_ON_CLOSE"</CODE> of the "JFrame" class, write
<CODE><PRE>
value := java getJavaClass:'javax.swing.JFrame' EXIT_ON_CLOSE.
</PRE></CODE>
The variable "value" now holds the integer value of the <CODE>"EXIT_ON_CLOSE"</CODE> constant.

Assuming that a "JFrame" object had a field named <CODE>"myField"</CODE>, to access this field, we'd have to write:
<CODE><PRE>
value := frame myField.
</PRE></CODE>
and "value" now holding whatever <CODE>"myField"</CODE> returns. This could be another object reference or any primitive value.

=== Setting Fields ===
To set a field, use a setter-like method call:
<CODE><PRE>
frame myField: newValue.
</PRE></CODE>

=== Name Conflicts ===

In very rare situations, a Java object may contain both a field and a method by the same name.
In this case, the Smalltalk code cannot depend on the dynamic translation mechanism (which actually looks for either a field or method name to match), but instead make it explicit, which operation is wanted:
Use:
<CODE><PRE>
frame getFieldByName:'myField'
</PRE></CODE>
to read a field, and:
<CODE><PRE>
frame setFieldByName:'myField' value:123.
</PRE></CODE>
to write the field.

If there are both fields and methods by the same name, and you use the non-explicit call,
the bridge will always assume that you want to call the getter/setter and perform a method call.
 

== Arrays ==

=== Passing Smalltalk Collections to Java ===

Smalltalk collections can now be directly passed to Java with a few limitations:
* The identity of the Smalltalk collections will not be preserved. passing the same collection to java multiple times will result in multiple instances of the same array on the java side. (to bypass this instantiate a new java array)
* Smalltalk collections need to be explicitly converted to the correct type (e.g. a <CODE>SignedIntegerArray</CODE> on the smalltalk side matches an <CODE>int</CODE>-Array on the java side)

=== Instantiating Arrays ===

The new bridge supports instantiation of arrays (whereas previously reflection had to be used to instantiate arrays from the smalltalk side).
There are two ways an array can be instantiated:

<CODE><PRE>
intArray := (java getJavaClass:'int[]') new:#[ 1 2 3 4 5 ] asSignedIntegerArray. "/ instantiates a new array of type "int" with the contents "1, 2, 3, 4, 5"
</PRE></CODE>

<CODE><PRE>
intArray := (java getJavaClass:'int[]') new:10. "/ instantiates a new empty array of type "int" with 10 elements.
</PRE></CODE>

=== Accessing Arrays ===

To achieve better performance, arrays of primitive types smaller than a certain size have their contents cached on the smalltalk side:
<CODE><PRE>
intArray contents at:1. "/ this will access the first element of the cached contents.
</PRE></CODE>

large arrays are not serialized immediately. large arrays will be serialized when <CODE>contents</CODE> is called the first time.

'''Attention:''' Java arrays are not immutable. changes to an array are not reflected in the cached contents. if an array has been updated, call <CODE>refresh</CODE> on the array to update the cache. arrays will not be updated automatically.

<CODE><PRE>
shortArray := (java getJavaClass:'short[]') new:10. "/ new empty "short" array with 10 elements

"/ copy the contents of the smalltalk collection to the newly instantiated short array
(java getJavaClass:'java.lang.System') arraycopy:(#[ 1 2 3 ] asSignedWordArray) srcPos:0 dest:shortArray destPos:0 length:3.

shortArray at:0. "/ will reflect the changes made to the array

shortArray contents at:1. "/ will still return 0 because the cached contents have not been updated.

shortArray refresh. "/ update the cached contents

shortArray contents at:1. "/ will now correctly reflect the changes made to the array
</PRE></CODE>

== Asynchronous Communication ==

In the new Bridge, everything can be done asynchronously. This is achieved via the <CODE>asyncDo:aBlock</CODE> method.
Every request sent to the Bridge inside of aBlock will immediately return a lazy value.
This lazy value will block upon access until the actual result is received from the java side.
The order of execution is guaranteed to be the same on the java side as on the smalltalk side.

Example:
<CODE><PRE>
java asyncDo:[
lazyInteger := (java getJavaClass:'java.lang.Integer') new:40. "/ this will return immediately
].
actualInteger := lazyInteger value. "/ this will block until the result is available
</PRE></CODE>

== Callbacks from Java ==
Sometimes you may want to execute a piece of Smalltalk code during the execution of the Java code. For example, we may want to install a Smalltalk observer to be notified when a button on a Java GUI was pressed,
or some other callback from a Java framework.

The following code registers a Smalltalk block as a callback for a mouse press event of a button:
<CODE><PRE>
listener := MouseListener new.
listener implementMethod:'mousePressed' as:[ Transcript showCR:'Hello from Java' ].
</PRE></CODE>
The above creates the callback and the listener, which can now be registered on a button:
<CODE><PRE>
button addMouseListener:listener.
</PRE></CODE>
Now, with the press of the button in the Java GUI, the Smalltalk block will be executed and writes <CODE>"Hello from Java"</CODE> to the Smalltalk console.
Of course, any other (Smalltalk-)action code can be made to run via this mechanism.

But be aware, that the callback is possibly called later (when the elementary action, which installed the code, has already finished long ago). Also, as the Java code execution is not synchronized with any of your expecco action execution, the callback may also be called at any arbutrary time, even at times when no activity at all is executed on the expecco side. If you forget to cleanup, and the Java object is still alive, it may even be called after you have finished your test run (if you keep the java bridge handle around and alive, for example in an expecoo environment variable).

So the Smalltalk callback code should not depend on any particular elementary action to be currently running, but instead in most cases write some information into a shared data container, preferably an instance of "SharedQueue", which is thread safe. Then, some other action (an elementary action) would read-wait and read events from that shared queue.

make sure that your test correctly cleans up any such callbacks afterwards. As a last resort, use the "Shutdown Bridge Connection" menu item, which closes the bridge connection, and thereby - as a side effect - removes any leftover callbacks. It does close the connection, and any remaining java proxy object handles become invalid, though.

Another example, using an observer could look like:
<CODE><PRE>
observer := java Observer new.
observer implementMethod:'update'
as:[:sourceObservable :argument|
argument notNil ifTrue:[ Transcript showCR:('I was notifyed with: ',argument toString) ]
ifFalse:[ Transcript showCR:'I was notifyed and the argument was nil' ].
].
myObservable addObserver:observer.
</PRE></CODE>
When the observable calls <CODE>"notifyObservers"</CODE>, the Smalltalk block will be executed.

== Exceptions in Java ==
Exceptions on the Java side are signalled back to the Smalltalk side and raise a corresponding exception there. However, on the Java side, the call stack which lead to the exception has already been unwound at that time (Java exceptions are not proceedable). So a proceed in the Smalltalk-side exception handler only affects the Smalltalk caller, but may leave the Java side in an undefined state.

== Remote Dynamic Code Injection ==
Sometimes we might want to execute code without the overhead of many rpc-messages being sent over the bridge, especially if we want to do something time critical, or want to make execution time measurements.
For this, it is possible to load a class at runtime into the JavaVM. The code of the class will first be sent to the JavaVM, which will compile and load the generated byte code. Then, the class can be accessed via the bridge just like any other preloaded class.

The following example specifies the class code in a smalltalk string and inject the code into the JavaVM. Then an instance of that new class will be instantiated and finally a method of the object instance will be invoked:
<CODE><PRE>
classCode := '
package myPackage.test;

import java.awt.BorderLayout;
import java.awt.event.MouseAdapter;
import java.awt.event.MouseEvent;
import java.util.Calendar;

import javax.swing.JButton;
import javax.swing.JFrame;
import javax.swing.JLabel;;

public class MyInjectedClass {
public void createSampleApp(){
JFrame frame=new JFrame("Hello im injected");
frame.setLayout(new BorderLayout());
JButton button=new JButton("click me");
final JLabel label=new JLabel("Text");
button.addMouseListener(new MouseAdapter() {

@Override
public void mouseClicked(MouseEvent e) {
label.setText(Calendar.getInstance().getTime().toString());
}
});
frame.add(label,BorderLayout.NORTH);
frame.add(button,BorderLayout.SOUTH);
frame.setSize(300, 300);
frame.setVisible(true);
}
}
'.
classObject := java getJavaClass:'myPackage.test.MyInjectedClass' fromSource:classCode.
classObject new createSampleApp.
</PRE></CODE>
After the code has been injected, a new instance of <CODE>"MyInjectedClass"</CODE> is created and the <CODE>"createSampleApp"</CODE> method is called. Because the example implements a GUI, a Java window will open, containing a label and a button. Clicking the button displays the current time in the label.



=== Code Sources for Class injection ===
There are 3 possible types of class code sources which we can use to inject the code. In the examples before we directly used a simple <CODE>"String"</CODE> in the smalltalk code as a code source. We also can use a <CODE>"*.java"</CODE> file as source. Just read the content of the file into a string and use it as in the previous examples.

To inject a <CODE>"*.class"</CODE> file use the following code:
<pre>
java getJavaClass:'the.class.name' fromByteCode:classCode.
</pre>

== Examples ==

This example creates a JFrame with one button inside. Then a Mouselistener is created and registered on the button. When the button is pressed, the title of the window changes to <CODE>"onPressed"</CODE> and the Transcript shows the message <CODE>"onPressed"</CODE>. When the button is released, the title of the window is changed to <CODE>"onReleased"</CODE> and the Transcript shows <CODE>"onReleased"</CODE>. If the button lost the mouse focus, the bridge will exit (disconnect), and the Java side is terminated.
<CODE><PRE>
|java frame button listener|

"/getting a bridge
java := JAVA::JavaBridge newWithServer.

"/creating a new frame and button object
frame := java getJavaClass:'javax.swing.JFrame' new.
button := (java getJavaClass:'javax.swing.JButton') new:'Click'.

"/creating a new mouse listener and adding callback blocks
listener := (java getJavaClass:'java.awt.event.MouseListener') new.

listener implementMethod:'mousePressed' as:[ Transcript showCR:'onPress'. frame setTitle:'onPressed' ].
listener implementMethod:'mouseReleased' as:[ Transcript showCR:'onReleased'. frame setTitle:'onReleased' ].
listener implementMethod:'mouseExited' as:[ Transcript showCR:'onExited'. java closeBridge. ].

"/register the mouse listener on the button and make the frame with button visible
button addMouseListener:listener.
frame add:button.
frame setSize:300 y:100.
frame setVisible: true.
</PRE></CODE>



==Differences between v1 and v2==
===General===
* A Java Bridge instance no longer requires multiple tcp ports to be open. This simplifies connection through ssh tunnels and firewalls.
* The identity of strings and primitve wrappers can now be preserved. (see [[#boxedDo:aBlock | boxedDo]])
* Simplified instantiation and access of arrays. (see [[#Arrays | Arrays]])
* Every request to the java side can now be done asynchronously. (see [[#Asynchronous Communication | Asynchronous Communication]])

===Loading Applications===
* '''addJarByPath:''' and '''addToClassPath:''' are still supported but have been deprecated. use '''loadJar:''', '''loadJarByPath:''' and '''loadExtension:''' instead. The new methods no longer require the jar or library to be present on the remote machine.

[[Java Interface Library#Loading Applications (from the expecco side) | v1]] [[#Loading Applications (from the expecco side) | v2]]

===Java Class Access===
* Sending the fully qualified name with instances of "." replaced by "_" to the bridge handle is still supported, but not recommended.
* A new method '''getJavaClass:''' has been introduced (also available for v1 since expecco v2.9). This solves the side effects of "_" being a legal character in class names.

[[Java Interface Library#Java Package Import and Class Access | v1]] [[#Java Class Access | v2]]
===Callbacks from Java===
* A new method '''implementMethod:as:''' has been introduced to assign callback blocks to method names. The old way is still supported.

[[Java Interface Library#Callbacks from Java | v1]] [[#Callbacks from Java | v2]]

===Remote Dynamic Code Injection===
* Code injection was problematic in v1 and has now been re-implemented in v2.

[[#Remote Dynamic Code Injection | v2]]

== API ==
===JAVA::Java===
====class protocol====
=====newWithServer=====
* This will start a local JavaVM, running the JavaBridge, and establishes a connection on a random free port.
: A new connected instance of JAVA::Java class is returned.

=====newWithServerForJavaPath:aJavaPathFilename=====
* This is the same as newWithServer but the path to the java executable can be specified. The JavaVM version must be 1.6 or higher to run the JavaBridge.
:: '''aJavaPathFilename''' - must be a instance of Filename
Smalltalk: JAVA::Java newWithServerForJavaPath:('my\path\to\java.executable'asFilename).
JavaScript: JAVA::Java.newWithServerForJavaPath("my\path\to\java.executable".asFilename());

=====newConnectedTo:aHhostString port:aPortNumber withTimeout:aTimeoutSeconds=====
* This is used to connect to a running JavaBridge on the network. The JavaBridge must be started in server mode on the remote host. After connecting a new connected instance of JAVA::Java is returned.
:: '''aHostString''' - the hostname or IP of the remote machine as String
:: '''aPortNumber ''' - the port on which the remote machine is listening as Number
:: '''aTimeoutSeconds''' - a connect timeout in seconds as Number
Smalltalk: JAVA::Java newConnectedTo:'myHostName' port:4567 withTimeout:30.
JavaScript: JAVA::Java.newConnectedTo_port_withTimeout("myHostName",4567,30);

=====newWaitingForConnectOnHost:aListeningAddressString port:aListeningPortNumber withTimeout:aTimeoutSeconds=====
* This is used to wait for incomming connecions of a running JavaBridge on the network. The JavaBridge must be started in client mode on the remote host. After connecting a new connected instance of JAVA::Java is returned.
:: '''deprecated: aListeningAddressString''' - no longer used. Can be nil.
:: '''aListeningPortNumber ''' - the port on which to listen for incomming connections as Number
:: '''aTimeoutSeconds''' - a connect timeout in seconds as Number, If nil it will wait endless.

=====singletonInstance=====
* This will call newWithServer for the first time and then always returns the same connected JAVA::Java instance until the connection was closed, then a new connected instance is returned.

=====exitAllInstances=====
* This will close all instances of JAVA::Java.

====instance protocol====
=====loadJarByPath:aPath=====
* Adds a jar to the running JavaVM. If the jar depends on other jars or libraries you have to add them too.
:: '''aPath''' - the path to the jar file as String.

=====loadJar:aByteArray=====
* Adds a jar to the running JavaVM. If the jar depends on other jars or libraries you have to add them too.
:: '''aByteArrays''' - a ByteArray containing the JAR file.

=====loadExtension:aPath=====
* Adds a jar to the running JavaVM and caches it for subsequent usages. If the jar depends on other jars you have to add them too.
:: '''aPath''' - the path to the jar file as String.

=====boxedDo:aBlock=====
* Any autoboxed values in aBlock returned from the JavaVM are preserved as such. By default autoboxed values are automatically unboxed. This way, the identity of such objects is preserved.

=====isConnected=====
* Tests if a connection is still established.
:: '''return:''' - true if the connection is still established, else false.

=====isAlive=====
* Tests if a connection is still responding.
:: '''return:''' - true if the connection is still alive, else false. Does a message round trip.

=====closeBridge=====
* This will close the bridge connection. Depending on in which mode the JavaBridge was started, the JavaVM is also closed (-keepAlive startparameter not set).

=====exit=====
* Same as closeBridge.

== See Also==
The [[DOT NET Interface Library| DOTNET Interface Plugin & Library]], which implements a likewise interface for .NET applications/libraries.
 
[[Java Interface Library | Version 1 of the Java Interface Library]]
<hr>
Back to [[Plugins]]

Java Interface Library v2

2016-06-01T11:39:15Z

Javogel: /* Examples */

== Introduction ==

This article discusses version 2 of the Java Bridge (which is as of expecco v2.9 still experimental).
The article for version 1 can be found [[Java Interface Library | here]].

The Java Interface library ("Java Bridge") is used to interact with Java objects inside an external Java Virtual Machine (JVM).

The access to Java objects, classes and programs is done via a framework called "''Java-Bridge''", which is similar in operation to the [[DOT NET Interface Library| dotNET bridge]]. This framework implements transparent forwarding of method (virtual function) calls to Java objects, which exist in a local or remote Java Virtual Machine (JVM). Also, return values, callBacks and exception information are passed back from the Java program to expecco. This is done by a proxy-object mechanism, which catches all function calls, wraps the arguments, sends a datagram to the other bridge side, awaits the reply and returns the result to the original caller. Thus, remote procedure calls are almost completely transparent to the Smalltalk/JavaScript code inside expecco. In your elementary code, you can write remote function calls as if they were to local objects.

Notice that this document describes the low level framework, which implements the bridge communication. A much easier to use high level interface (called "Groovy Blocks") exists and should normally be used, if you need access to a java application's internals during testing.
Please take a look at
[[Expecco_API#Groovy_Elementary_Blocks | "Groovy Block API"]]
and [[Testing Java Applications using Groovy blocks/en | "Testing Java Applications using Groovy blocks"]].

== Architecture ==

On the expecco side, the bridge consists of a number of Proxy objects,
which behave like regular Smalltalk objects as seen from elementary expecco code.
However, instead of performing an action when one of their methods (virtual functions) is called,
they send a message over a socket connection to the Java VM (actually: to a bridge software inside the
Java application) which decodes the message and sends it to the destination Java object.
The same is done in reverse direction with the return value.

+---------------------+ +----------+ +----------------+ +----------------+ +---------+
| | | | | | | | | Java |
| expecco |---->| Proxy |---->| Bridge |==>>==| Bridge |---->| Object |
| (elementary code) |<----| |<----| (expecco side) |==<<==| (Java side) |<----| |
+---------------------+ +----------+ +----------------+ +----------------+ +---------+

This setup allows for transparent communication with objects inside a local or remote Java VM. This may be either utility functions which happen to be convenient for the test application (for example: file parsing, syntax analysis, protocol implementaitons or access to specific hardware via driver libraries), or the tested application in the system under test itself.

Especially, it allows for the objects of the tested application to be looked into, manipulated and for functions of it or underlying frameworks to be called.

For expecco code, we tried to make this as transparent as possible, however there are a few exceptions, when function names need to be translated (for example, because the function naming syntax is different) or due to the fact that for some operations no corresponding name exists in Smalltalk (array access, for example).

Of course, multiple such connections can coexist and be served/handled in parallel. This enables an expecco test suite to communicate with both sides of a tested client-server Java application, for example.

Notice that a similar mechanism is used in expecco to communicate with DOTNET, Qt (C++) and C applications.

 

== Activating the new Java Bridge ==
To activate the new bridge in expecco navigate to <CODE>Extras -> Settings -> Plugins -> Java Bridge</CODE> and tick the '''Use new Bridge (experimental)''' checkbox.
[[Datei:ActivateNewJavaBridge.png]]

'''Attention:''' Ticking the checkbox will terminate all currently active Bridge connections due to incompatibilities between the new and the old version.

== Initializing / Releasing the Bridge ==

Before any communication can take place between expecco and any Java object, the Java side of the bridge has to be started, and a communication has to be established.
In expecco, all of the bridge classes are found in the <CODE>JAVA</CODE> namespace.

The main interface class is "<CODE>Java</CODE>", in the "<CODE>JAVA</CODE>" namespace:
<CODE><PRE>
java := JAVA::Java newWithServer.
</PRE></CODE>
or (in JavaScript):
<CODE><PRE>
java = JAVA::Java.newWithServer();
</PRE></CODE>

This starts the Java-side of the bridge (actually executes java as a background command) on the local machine, and establishes a connection to that JVM.

The bridge connection should be closed, if the bridge is no longer needed. Release the bridge with:
<CODE><PRE>
java.closeBridge();
</PRE></CODE>
which terminates the connection.

=== Start and Connect to a Remote Machine ===
The above started a Java VM and connected to it. Alternatively, you may want to connect to an already running Java program (typically, your system under test).
In order for your program to be reachable, it must allow for the bridge to connect to it via a special bridge-connection, which is a socket connection. For this, it must execute the server code found in the "JavaBridge.jar" file. To pass [[#Startup Parameters| parameters]] you will typically start it from a command line or a little shell/batch script.

Call (on the shell/cmd level):
$ java -jar <PATH_TO_JAVABRIDGE.JAR> <PARAMETERS>

The "JavaBridge.jar" file is found in the installation directory of expecco at:
\exept\expecco\packages\exept\bridgeFramework\javaBridge\javaBin\JavaBridge.jar

The Javabridge code allows for either side to initiate the connection - i.e. it can be run in server mode,
where it awaits an incoming connection, or in client mode, where it actively initiates a connection.
After connection establishment, there is no difference in the operation of the bridge, however depending on the setup of your network infrastructure, especially firewalls, either mechanism may be easier to be used.

Assuming that the bridge is already running on the remote machine as server (default),
use <CODE>newConnectedTo:port:withTimeout:</CODE> to connect to it from the expecco side:
java := JAVA::Java newConnectedTo:'myHost' port:4567 withTimeout:30.
This will initiate the connection setup from the expecco side.

Alternatively, if started in client mode use <CODE>newWaitingForConnectOnHost:port:withTimeout:</CODE>:
java := JAVA::Java newWaitingForConnectOnHost:'localhost' port:4567 withTimeout:30.
which will open a port on the expecco side, and wait until the Java side connects to it.
[[#JAVA::Java|For more details see API]]

====Startup Parameters====
You can use any parameter in any order.
If no parameter is used then the bridge listenes on port 14014 in server mode without keepAlive.
;<code>-help</code>
* Shows the help

;<code>-ip <aHostnameOrIP></code>
* In client mode this specifies the ip or hostname to connect to. In server mode this specifies the ip or hostname to bind to.

;<code>-port <aPortNumber> </code>
* In client mode this specifies the port to connect to. In server mode this specifies the listening port.

;<code>-asClient</code>
* The bridge will start in client mode. If not set the bridge is started in server mode.

;<code>-keepAlive</code>
* By setting this flag the bridge will not exit after the connection has closed and starts to connect or listen again. Otherwise, it will run for a single connection session only.

== Loading Applications (from the expecco side) ==

Normally, you would start your application with the required command line arguments and include the javabridge as jar there. However, in some situations, it may be required to dynamically load other jars into the connected Java VM.
By accessing a classloader, additional classes, or applications as contained in JAR files can be loaded from the expecco side.

This can be used to add a JAR file to the classloader:
<CODE><PRE>
java loadJarByPath:'pathToJarFile'. "/ assuming "java" is a handle as returned from the above connect
</PRE></CODE>

or, if the JAR file is loaded in memory:
<CODE><PRE>
java loadJar:jarByteArray. "/ where "jarByteArray" is a ByteArray containing the JAR file
</PRE></CODE>

If the JVM is on a remote machine, the path is resolved on the expecco side and the JAR will be transferred to the remote side.

Should transferring the JAR be too much overhead, an additional mechanism is provided:
<CODE><PRE>
java loadExtension:'pathToJarFile'.
</PRE></CODE>
this will cache the JAR file on the bridge side and eliminate the overhead of subsequent invocations.

== Java Class Access ==

This following code sample simply references (i.e. accesses) the class "JFrame" from the <CODE>"javax.swing"</CODE> package. The fully specified class name in Java would be <CODE>"javax.swing.JFrame"</CODE>:
<CODE><PRE>
java getJavaClass:'javax.swing.JFrame'
</PRE></CODE>

Or, if you want to load multiple classes:
<CODE><PRE>
java import:'javax.swing.JFrame' import:'javax.swing.JButton'
do:[:jFrame :jButton | "do something with JButton and JFrame" ].
</PRE></CODE>

v2 also supports dynamic compilation of java source code:
<CODE><PRE>
java getJavaClass:'className' fromSource:'classSource'. "/ where classSource is a String containing valid java source code
</PRE></CODE>

and loading precompiled java bytecode:
<CODE><PRE>
java getJavaClass:'className' fromByteCode:byteCode. "/ where byteCode is a ByteArray containing valid java bytecode
</PRE></CODE>

[[#Remote Dynamic Code Injection | for details see Remote Dynamic Code Injection]]

== Instantiating a Class ==

Object instances are created via the "new"-message, sent to a proxy of a Java class. You can get this proxy as described in the previous section. For example, if we want to create a new instance of a "JFrame" and a "JButton", write:
<CODE><PRE>
frame := java getJavaClass:'javax.swing.JFrame' new.
button := java getJavaClass:'javax.swing.JButton' new.
</PRE></CODE>
The first statement results in a proxy object for the "JFrame" instance. The second line results in a proxy for a new "JButton" object.

== Calling Instance Methods ==

A method call is done by a message send to a proxy object, where the message is the method name to call. For example, to call the <CODE>"setVisible(boolean isVisible)"</CODE> method on the above JFrame object, we send the following message to that proxy:
<CODE><PRE>
frame setVisible:true.
</PRE></CODE>

As method naming is different in Smalltalk and Java, a dynamic translation is applied when sending messages from Smalltalk code to a remote Java object. Smalltalk has arguments embedded inside parts of a so called "keyword" message, such as in "receiver foo:arg1 bar:arg2", where "foo:bar:" would be the message name, and "arg1", "arg2" be the arguments.

In Java, the message name is a single identifier, and arguments are written in an argument list after the message name: "receiver.fooBar(arg1, arg2)".

When message names are translated, only the very first part of the Smalltalk keyword message is taken ("foo" in the above example), and the remaining parts are simpl ignored. Thus, any of the Smalltalk messages "foo:bar:", "foo:xxxx:" and "foo:_:" (a single underscore as second part) all translate to the same Java message name "foo()".

Therefore, to call a method with more than one argument, like <CODE>"setSize(int width,int height)"</CODE> on a JFrame instance we can write:
<CODE><PRE>
frame setSize:300 _:200.
</PRE></CODE>
but just as well:
<CODE><PRE>
frame setSize:300 anyWord:200.
</PRE></CODE>
or any other selector with "setSize:" as its first component.
The selector translation mechanism simply takes the first part as the Java selector.

In practice, you should take a reasonably descriptive name, such as: "frame setSize:300 height:200" or only the Java name as first part, such as "frame setSize:300 _:200".

For a call of a method with 4 arguments, we could write:
<CODE><PRE>
frame setBounds:100 y:50 width:300 height:200.
</PRE></CODE>
or:
<CODE><PRE>
frame setBounds:100 _:50 _:300 _:200.
</PRE></CODE>

Also here the <CODE>"y: width: height:"</CODE> can be named as you want, but the first part must be "setBounds:".

=== Calling Static Methods ===

Calling a static method on an object is not different from calling non static methods. In most cases you will call a static method not on an object but directly on the class. This is done by using the class object as "receiver" of the message. For example, if we want to call the static method <CODE>"isDefaultLookAndFeelDecorated()"</CODE> of the JFrame class, write:
<CODE><PRE>
java getJavaClass:'javax.swing.JFrame' isDefaultLookAndFeelDecorated.
</PRE></CODE>

== Accessing Fields ==

As Smalltalk does not support access of an object's fields from the outside (it is fully encapsulated, and access from outside is ONLY allowed via getters/setters), an additional translation mechanism is provided for field access.

Accessing a field of a Java object or a class's static field uses the same syntax as method calls. To access a field, send a message where the message is the field name. To access the field of a class the field must be static.
For example, to get the value of the static field named <CODE>"EXIT_ON_CLOSE"</CODE> of the "JFrame" class, write
<CODE><PRE>
value := java getJavaClass:'javax.swing.JFrame' EXIT_ON_CLOSE.
</PRE></CODE>
The variable "value" now holds the integer value of the <CODE>"EXIT_ON_CLOSE"</CODE> constant.

Assuming that a "JFrame" object had a field named <CODE>"myField"</CODE>, to access this field, we'd have to write:
<CODE><PRE>
value := frame myField.
</PRE></CODE>
and "value" now holding whatever <CODE>"myField"</CODE> returns. This could be another object reference or any primitive value.

=== Setting Fields ===
To set a field, use a setter-like method call:
<CODE><PRE>
frame myField: newValue.
</PRE></CODE>

=== Name Conflicts ===

In very rare situations, a Java object may contain both a field and a method by the same name.
In this case, the Smalltalk code cannot depend on the dynamic translation mechanism (which actually looks for either a field or method name to match), but instead make it explicit, which operation is wanted:
Use:
<CODE><PRE>
frame getFieldByName:'myField'
</PRE></CODE>
to read a field, and:
<CODE><PRE>
frame setFieldByName:'myField' value:123.
</PRE></CODE>
to write the field.

If there are both fields and methods by the same name, and you use the non-explicit call,
the bridge will always assume that you want to call the getter/setter and perform a method call.
 

== Arrays ==

=== Passing Smalltalk Collections to Java ===

Smalltalk collections can now be directly passed to Java with a few limitations:
* The identity of the Smalltalk collections will not be preserved. passing the same collection to java multiple times will result in multiple instances of the same array on the java side. (to bypass this instantiate a new java array)
* Smalltalk collections need to be explicitly converted to the correct type (e.g. a <CODE>SignedIntegerArray</CODE> on the smalltalk side matches an <CODE>int</CODE>-Array on the java side)

=== Instantiating Arrays ===

The new bridge supports instantiation of arrays (whereas previously reflection had to be used to instantiate arrays from the smalltalk side).
There are two ways an array can be instantiated:

<CODE><PRE>
intArray := (java getJavaClass:'int[]') new:#[ 1 2 3 4 5 ] asSignedIntegerArray. "/ instantiates a new array of type "int" with the contents "1, 2, 3, 4, 5"
</PRE></CODE>

<CODE><PRE>
intArray := (java getJavaClass:'int[]') new:10. "/ instantiates a new empty array of type "int" with 10 elements.
</PRE></CODE>

=== Accessing Arrays ===

To achieve better performance, arrays of primitive types smaller than a certain size have their contents cached on the smalltalk side:
<CODE><PRE>
intArray contents at:1. "/ this will access the first element of the cached contents.
</PRE></CODE>

large arrays are not serialized immediately. large arrays will be serialized when <CODE>contents</CODE> is called the first time.

'''Attention:''' Java arrays are not immutable. changes to an array are not reflected in the cached contents. if an array has been updated, call <CODE>refresh</CODE> on the array to update the cache. arrays will not be updated automatically.

<CODE><PRE>
shortArray := (java getJavaClass:'short[]') new:10. "/ new empty "short" array with 10 elements

"/ copy the contents of the smalltalk collection to the newly instantiated short array
(java getJavaClass:'java.lang.System') arraycopy:(#[ 1 2 3 ] asSignedWordArray) srcPos:0 dest:shortArray destPos:0 length:3.

shortArray at:0. "/ will reflect the changes made to the array

shortArray contents at:1. "/ will still return 0 because the cached contents have not been updated.

shortArray refresh. "/ update the cached contents

shortArray contents at:1. "/ will now correctly reflect the changes made to the array
</PRE></CODE>

== Asynchronous Communication ==

In the new Bridge, everything can be done asynchronously. This is achieved via the <CODE>asyncDo:aBlock</CODE> method.
Every request sent to the Bridge inside of aBlock will immediately return a lazy value.
This lazy value will block upon access until the actual result is received from the java side.
The order of execution is guaranteed to be the same on the java side as on the smalltalk side.

Example:
<CODE><PRE>
java asyncDo:[
lazyInteger := (java getJavaClass:'java.lang.Integer') new:40. "/ this will return immediately
].
actualInteger := lazyInteger value. "/ this will block until the result is available
</PRE></CODE>

== Callbacks from Java ==
Sometimes you may want to execute a piece of Smalltalk code during the execution of the Java code. For example, we may want to install a Smalltalk observer to be notified when a button on a Java GUI was pressed,
or some other callback from a Java framework.

The following code registers a Smalltalk block as a callback for a mouse press event of a button:
<CODE><PRE>
listener := MouseListener new.
listener implementMethod:'mousePressed' as:[ Transcript showCR:'Hello from Java' ].
</PRE></CODE>
The above creates the callback and the listener, which can now be registered on a button:
<CODE><PRE>
button addMouseListener:listener.
</PRE></CODE>
Now, with the press of the button in the Java GUI, the Smalltalk block will be executed and writes <CODE>"Hello from Java"</CODE> to the Smalltalk console.
Of course, any other (Smalltalk-)action code can be made to run via this mechanism.

But be aware, that the callback is possibly called later (when the elementary action, which installed the code, has already finished long ago). Also, as the Java code execution is not synchronized with any of your expecco action execution, the callback may also be called at any arbutrary time, even at times when no activity at all is executed on the expecco side. If you forget to cleanup, and the Java object is still alive, it may even be called after you have finished your test run (if you keep the java bridge handle around and alive, for example in an expecoo environment variable).

So the Smalltalk callback code should not depend on any particular elementary action to be currently running, but instead in most cases write some information into a shared data container, preferably an instance of "SharedQueue", which is thread safe. Then, some other action (an elementary action) would read-wait and read events from that shared queue.

make sure that your test correctly cleans up any such callbacks afterwards. As a last resort, use the "Shutdown Bridge Connection" menu item, which closes the bridge connection, and thereby - as a side effect - removes any leftover callbacks. It does close the connection, and any remaining java proxy object handles become invalid, though.

Another example, using an observer could look like:
<CODE><PRE>
observer := java Observer new.
observer implementMethod:'update'
as:[:sourceObservable :argument|
argument notNil ifTrue:[ Transcript showCR:('I was notifyed with: ',argument toString) ]
ifFalse:[ Transcript showCR:'I was notifyed and the argument was nil' ].
].
myObservable addObserver:observer.
</PRE></CODE>
When the observable calls <CODE>"notifyObservers"</CODE>, the Smalltalk block will be executed.

== Exceptions in Java ==
Exceptions on the Java side are signalled back to the Smalltalk side and raise a corresponding exception there. However, on the Java side, the call stack which lead to the exception has already been unwound at that time (Java exceptions are not proceedable). So a proceed in the Smalltalk-side exception handler only affects the Smalltalk caller, but may leave the Java side in an undefined state.

== Remote Dynamic Code Injection ==
Sometimes we might want to execute code without the overhead of many rpc-messages being sent over the bridge, especially if we want to do something time critical, or want to make execution time measurements.
For this, it is possible to load a class at runtime into the JavaVM. The code of the class will first be sent to the JavaVM, which will compile and load the generated byte code. Then, the class can be accessed via the bridge just like any other preloaded class.

The following example specifies the class code in a smalltalk string and inject the code into the JavaVM. Then an instance of that new class will be instantiated and finally a method of the object instance will be invoked:
<CODE><PRE>
classCode := '
package myPackage.test;

import java.awt.BorderLayout;
import java.awt.event.MouseAdapter;
import java.awt.event.MouseEvent;
import java.util.Calendar;

import javax.swing.JButton;
import javax.swing.JFrame;
import javax.swing.JLabel;;

public class MyInjectedClass {
public void createSampleApp(){
JFrame frame=new JFrame("Hello im injected");
frame.setLayout(new BorderLayout());
JButton button=new JButton("click me");
final JLabel label=new JLabel("Text");
button.addMouseListener(new MouseAdapter() {

@Override
public void mouseClicked(MouseEvent e) {
label.setText(Calendar.getInstance().getTime().toString());
}
});
frame.add(label,BorderLayout.NORTH);
frame.add(button,BorderLayout.SOUTH);
frame.setSize(300, 300);
frame.setVisible(true);
}
}
'.
classObject := java getJavaClass:'myPackage.test.MyInjectedClass' fromSource:classCode.
classObject new createSampleApp.
</PRE></CODE>
After the code has been injected, a new instance of <CODE>"MyInjectedClass"</CODE> is created and the <CODE>"createSampleApp"</CODE> method is called. Because the example implements a GUI, a Java window will open, containing a label and a button. Clicking the button displays the current time in the label.



=== Code Sources for Class injection ===
There are 3 possible types of class code sources which we can use to inject the code. In the examples before we directly used a simple <CODE>"String"</CODE> in the smalltalk code as a code source. We also can use a <CODE>"*.java"</CODE> file as source. Just read the content of the file into a string and use it as in the previous examples.

To inject a <CODE>"*.class"</CODE> file use the following code:
<pre>
java getJavaClass:'the.class.name' fromByteCode:classCode.
</pre>

== Examples ==

This example creates a JFrame with one button inside. Then a Mouselistener is created and registered on the button. When the button is pressed, the title of the window changes to <CODE>"onPressed"</CODE> and the Transcript shows the message <CODE>"onPressed"</CODE>. When the button is released, the title of the window is changed to <CODE>"onReleased"</CODE> and the Transcript shows <CODE>"onReleased"</CODE>. If the button lost the mouse focus, the bridge will exit (disconnect), and the Java side is terminated.
<CODE><PRE>
|java frame button listener|

"/getting a bridge
java := JAVA::JavaBridge newWithServer.

"/creating a new frame and button object
frame := java getJavaClass:'javax.swing.JFrame' new.
button := (java getJavaClass:'javax.swing.JButton') new:'Click'.

"/creating a new mouse listener and adding callback blocks
listener := (java getJavaClass:'java.awt.event.MouseListener') new.

listener implementMethod:'mousePressed' as:[ Transcript showCR:'onPress'. frame setTitle:'onPressed' ].
listener implementMethod:'mouseReleased' as:[ Transcript showCR:'onReleased'. frame setTitle:'onReleased' ].
listener implementMethod:'mouseExited' as:[ Transcript showCR:'onExited'. java closeBridge. ].

"/register the mouse listener on the button and make the frame with button visible
button addMouseListener:listener.
frame add:button.
frame setSize:300 y:100.
frame setVisible: true.
</PRE></CODE>



==Differences between v1 and v2==
===General===
* A Java Bridge instance no longer requires multiple tcp ports to be open. This simplifies connection through ssh tunnels and firewalls.
* The identity of strings and primitve wrappers can now be preserved. (see [[#boxedDo:aBlock | boxedDo]])
* Simplified instantiation and access of arrays. (see [[#Arrays | Arrays]])
* Every request to the java side can now be done asynchronously. (see [[#Asynchronous Communication | Asynchronous Communication]])

===Loading Applications===
* '''addJarByPath:''' and '''addToClassPath:''' are still supported but have been deprecated. use '''loadJar:''', '''loadJarByPath:''' and '''loadExtension:''' instead. The new methods no longer require the jar or library to be present on the remote machine.

[[Java Interface Library#Loading Applications (from the expecco side) | v1]] [[#Loading Applications (from the expecco side) | v2]]

===Java Class Access===
* Sending the fully qualified name with instances of "." replaced by "_" to the bridge handle is still supported, but not recommended.
* A new method '''getJavaClass:''' has been introduced (also available for v1 since expecco v2.9). This solves the side effects of "_" being a legal character in class names.

[[Java Interface Library#Java Package Import and Class Access | v1]] [[#Java Class Access | v2]]
===Callbacks from Java===
* A new method '''implementMethod:as:''' has been introduced to assign callback blocks to method names. The old way is still supported.

[[Java Interface Library#Callbacks from Java | v1]] [[#Callbacks from Java | v2]]

===Remote Dynamic Code Injection===
* Code injection was problematic in v1 and has now been re-implemented in v2.

[[#Remote Dynamic Code Injection | v2]]

== API ==
===JAVA::Java===
====class protocol====
=====newWithServer=====
* This will start a local JavaVM, running the JavaBridge, and establishes a connection on a random free port.
: A new connected instance of JAVA::Java class is returned.

=====newWithServerForJavaPath:aJavaPathFilename=====
* This is the same as newWithServer but the path to the java executable can be specified. The JavaVM version must be 1.6 or higher to run the JavaBridge.
:: '''aJavaPathFilename''' - must be a instance of Filename
Smalltalk: JAVA::Java newWithServerForJavaPath:('my\path\to\java.executable'asFilename).
JavaScript: JAVA::Java.newWithServerForJavaPath("my\path\to\java.executable".asFilename());

=====newConnectedTo:aHhostString port:aPortNumber withTimeout:aTimeoutSeconds=====
* This is used to connect to a running JavaBridge on the network. The JavaBridge must be started in server mode on the remote host. After connecting a new connected instance of JAVA::Java is returned.
:: '''aHostString''' - the hostname or IP of the remote machine as String
:: '''aPortNumber ''' - the port on which the remote machine is listening as Number
:: '''aTimeoutSeconds''' - a connect timeout in seconds as Number
Smalltalk: JAVA::Java newConnectedTo:'myHostName' port:4567 withTimeout:30.
JavaScript: JAVA::Java.newConnectedTo_port_withTimeout("myHostName",4567,30);

=====newWaitingForConnectOnHost:aListeningAddressString port:aListeningPortNumber withTimeout:aTimeoutSeconds=====
* This is used to wait for incomming connecions of a running JavaBridge on the network. The JavaBridge must be started in client mode on the remote host. After connecting a new connected instance of JAVA::Java is returned.
:: '''deprecated: aListeningAddressString''' - no longer used. Can be nil.
:: '''aListeningPortNumber ''' - the port on which to listen for incomming connections as Number
:: '''aTimeoutSeconds''' - a connect timeout in seconds as Number, If nil it will wait endless.

=====singletonInstance=====
* This will call newWithServer for the first time and then always returns the same connected JAVA::Java instance until the connection was closed, then a new connected instance is returned.

=====exitAllInstances=====
* This will close all instances of JAVA::Java.

====instance protocol====
=====loadJarByPath:aPath=====
* Adds a jar to the running JavaVM. If the jar depends on other jars or libraries you have to add them too.
:: '''aPath''' - the path to the jar file as String.

=====loadJar:aByteArray=====
* Adds a jar to the running JavaVM. If the jar depends on other jars or libraries you have to add them too.
:: '''aByteArrays''' - a ByteArray containing the JAR file.

=====loadExtension:aPath=====
* Adds a jar to the running JavaVM and caches it for subsequent usages. If the jar depends on other jars you have to add them too.
:: '''aPath''' - the path to the jar file as String.

=====boxedDo:aBlock=====
* Any autoboxed values in aBlock returned from the JavaVM are preserved as such. By default autoboxed values are automatically unboxed. This way, the identity of such objects is preserved.

=====isConnected=====
* Tests if a connection is still established.
:: '''return:''' - true if the connection is still established, else false.

=====isAlive=====
* Tests if a connection is still responding.
:: '''return:''' - true if the connection is still alive, else false. Does a message round trip.

=====closeBridge=====
* This will close the bridge connection. Depending on in which mode the JavaBridge was started, the JavaVM is also closed (-keepAlive startparameter not set).

=====exit=====
* Same as closeBridge.

== See Also==
The [[DOT NET Interface Library| DOTNET Interface Plugin & Library]], which implements a likewise interface for .NET applications/libraries.
 
[[Java Interface Library | Version 1 of the Java Interface Library]]
<hr>
Back to [[Plugins]]

Java Interface Library v2

2016-06-01T11:05:44Z

Javogel: /* General */

== Introduction ==

This article discusses version 2 of the Java Bridge (which is as of expecco v2.9 still experimental).
The article for version 1 can be found [[Java Interface Library | here]].

The Java Interface library ("Java Bridge") is used to interact with Java objects inside an external Java Virtual Machine (JVM).

The access to Java objects, classes and programs is done via a framework called "''Java-Bridge''", which is similar in operation to the [[DOT NET Interface Library| dotNET bridge]]. This framework implements transparent forwarding of method (virtual function) calls to Java objects, which exist in a local or remote Java Virtual Machine (JVM). Also, return values, callBacks and exception information are passed back from the Java program to expecco. This is done by a proxy-object mechanism, which catches all function calls, wraps the arguments, sends a datagram to the other bridge side, awaits the reply and returns the result to the original caller. Thus, remote procedure calls are almost completely transparent to the Smalltalk/JavaScript code inside expecco. In your elementary code, you can write remote function calls as if they were to local objects.

Notice that this document describes the low level framework, which implements the bridge communication. A much easier to use high level interface (called "Groovy Blocks") exists and should normally be used, if you need access to a java application's internals during testing.
Please take a look at
[[Expecco_API#Groovy_Elementary_Blocks | "Groovy Block API"]]
and [[Testing Java Applications using Groovy blocks/en | "Testing Java Applications using Groovy blocks"]].

== Architecture ==

On the expecco side, the bridge consists of a number of Proxy objects,
which behave like regular Smalltalk objects as seen from elementary expecco code.
However, instead of performing an action when one of their methods (virtual functions) is called,
they send a message over a socket connection to the Java VM (actually: to a bridge software inside the
Java application) which decodes the message and sends it to the destination Java object.
The same is done in reverse direction with the return value.

+---------------------+ +----------+ +----------------+ +----------------+ +---------+
| | | | | | | | | Java |
| expecco |---->| Proxy |---->| Bridge |==>>==| Bridge |---->| Object |
| (elementary code) |<----| |<----| (expecco side) |==<<==| (Java side) |<----| |
+---------------------+ +----------+ +----------------+ +----------------+ +---------+

This setup allows for transparent communication with objects inside a local or remote Java VM. This may be either utility functions which happen to be convenient for the test application (for example: file parsing, syntax analysis, protocol implementaitons or access to specific hardware via driver libraries), or the tested application in the system under test itself.

Especially, it allows for the objects of the tested application to be looked into, manipulated and for functions of it or underlying frameworks to be called.

For expecco code, we tried to make this as transparent as possible, however there are a few exceptions, when function names need to be translated (for example, because the function naming syntax is different) or due to the fact that for some operations no corresponding name exists in Smalltalk (array access, for example).

Of course, multiple such connections can coexist and be served/handled in parallel. This enables an expecco test suite to communicate with both sides of a tested client-server Java application, for example.

Notice that a similar mechanism is used in expecco to communicate with DOTNET, Qt (C++) and C applications.

 

== Activating the new Java Bridge ==
To activate the new bridge in expecco navigate to <CODE>Extras -> Settings -> Plugins -> Java Bridge</CODE> and tick the '''Use new Bridge (experimental)''' checkbox.
[[Datei:ActivateNewJavaBridge.png]]

'''Attention:''' Ticking the checkbox will terminate all currently active Bridge connections due to incompatibilities between the new and the old version.

== Initializing / Releasing the Bridge ==

Before any communication can take place between expecco and any Java object, the Java side of the bridge has to be started, and a communication has to be established.
In expecco, all of the bridge classes are found in the <CODE>JAVA</CODE> namespace.

The main interface class is "<CODE>Java</CODE>", in the "<CODE>JAVA</CODE>" namespace:
<CODE><PRE>
java := JAVA::Java newWithServer.
</PRE></CODE>
or (in JavaScript):
<CODE><PRE>
java = JAVA::Java.newWithServer();
</PRE></CODE>

This starts the Java-side of the bridge (actually executes java as a background command) on the local machine, and establishes a connection to that JVM.

The bridge connection should be closed, if the bridge is no longer needed. Release the bridge with:
<CODE><PRE>
java.closeBridge();
</PRE></CODE>
which terminates the connection.

=== Start and Connect to a Remote Machine ===
The above started a Java VM and connected to it. Alternatively, you may want to connect to an already running Java program (typically, your system under test).
In order for your program to be reachable, it must allow for the bridge to connect to it via a special bridge-connection, which is a socket connection. For this, it must execute the server code found in the "JavaBridge.jar" file. To pass [[#Startup Parameters| parameters]] you will typically start it from a command line or a little shell/batch script.

Call (on the shell/cmd level):
$ java -jar <PATH_TO_JAVABRIDGE.JAR> <PARAMETERS>

The "JavaBridge.jar" file is found in the installation directory of expecco at:
\exept\expecco\packages\exept\bridgeFramework\javaBridge\javaBin\JavaBridge.jar

The Javabridge code allows for either side to initiate the connection - i.e. it can be run in server mode,
where it awaits an incoming connection, or in client mode, where it actively initiates a connection.
After connection establishment, there is no difference in the operation of the bridge, however depending on the setup of your network infrastructure, especially firewalls, either mechanism may be easier to be used.

Assuming that the bridge is already running on the remote machine as server (default),
use <CODE>newConnectedTo:port:withTimeout:</CODE> to connect to it from the expecco side:
java := JAVA::Java newConnectedTo:'myHost' port:4567 withTimeout:30.
This will initiate the connection setup from the expecco side.

Alternatively, if started in client mode use <CODE>newWaitingForConnectOnHost:port:withTimeout:</CODE>:
java := JAVA::Java newWaitingForConnectOnHost:'localhost' port:4567 withTimeout:30.
which will open a port on the expecco side, and wait until the Java side connects to it.
[[#JAVA::Java|For more details see API]]

====Startup Parameters====
You can use any parameter in any order.
If no parameter is used then the bridge listenes on port 14014 in server mode without keepAlive.
;<code>-help</code>
* Shows the help

;<code>-ip <aHostnameOrIP></code>
* In client mode this specifies the ip or hostname to connect to. In server mode this specifies the ip or hostname to bind to.

;<code>-port <aPortNumber> </code>
* In client mode this specifies the port to connect to. In server mode this specifies the listening port.

;<code>-asClient</code>
* The bridge will start in client mode. If not set the bridge is started in server mode.

;<code>-keepAlive</code>
* By setting this flag the bridge will not exit after the connection has closed and starts to connect or listen again. Otherwise, it will run for a single connection session only.

== Loading Applications (from the expecco side) ==

Normally, you would start your application with the required command line arguments and include the javabridge as jar there. However, in some situations, it may be required to dynamically load other jars into the connected Java VM.
By accessing a classloader, additional classes, or applications as contained in JAR files can be loaded from the expecco side.

This can be used to add a JAR file to the classloader:
<CODE><PRE>
java loadJarByPath:'pathToJarFile'. "/ assuming "java" is a handle as returned from the above connect
</PRE></CODE>

or, if the JAR file is loaded in memory:
<CODE><PRE>
java loadJar:jarByteArray. "/ where "jarByteArray" is a ByteArray containing the JAR file
</PRE></CODE>

If the JVM is on a remote machine, the path is resolved on the expecco side and the JAR will be transferred to the remote side.

Should transferring the JAR be too much overhead, an additional mechanism is provided:
<CODE><PRE>
java loadExtension:'pathToJarFile'.
</PRE></CODE>
this will cache the JAR file on the bridge side and eliminate the overhead of subsequent invocations.

== Java Class Access ==

This following code sample simply references (i.e. accesses) the class "JFrame" from the <CODE>"javax.swing"</CODE> package. The fully specified class name in Java would be <CODE>"javax.swing.JFrame"</CODE>:
<CODE><PRE>
java getJavaClass:'javax.swing.JFrame'
</PRE></CODE>

Or, if you want to load multiple classes:
<CODE><PRE>
java import:'javax.swing.JFrame' import:'javax.swing.JButton'
do:[:jFrame :jButton | "do something with JButton and JFrame" ].
</PRE></CODE>

v2 also supports dynamic compilation of java source code:
<CODE><PRE>
java getJavaClass:'className' fromSource:'classSource'. "/ where classSource is a String containing valid java source code
</PRE></CODE>

and loading precompiled java bytecode:
<CODE><PRE>
java getJavaClass:'className' fromByteCode:byteCode. "/ where byteCode is a ByteArray containing valid java bytecode
</PRE></CODE>

[[#Remote Dynamic Code Injection | for details see Remote Dynamic Code Injection]]

== Instantiating a Class ==

Object instances are created via the "new"-message, sent to a proxy of a Java class. You can get this proxy as described in the previous section. For example, if we want to create a new instance of a "JFrame" and a "JButton", write:
<CODE><PRE>
frame := java getJavaClass:'javax.swing.JFrame' new.
button := java getJavaClass:'javax.swing.JButton' new.
</PRE></CODE>
The first statement results in a proxy object for the "JFrame" instance. The second line results in a proxy for a new "JButton" object.

== Calling Instance Methods ==

A method call is done by a message send to a proxy object, where the message is the method name to call. For example, to call the <CODE>"setVisible(boolean isVisible)"</CODE> method on the above JFrame object, we send the following message to that proxy:
<CODE><PRE>
frame setVisible:true.
</PRE></CODE>

As method naming is different in Smalltalk and Java, a dynamic translation is applied when sending messages from Smalltalk code to a remote Java object. Smalltalk has arguments embedded inside parts of a so called "keyword" message, such as in "receiver foo:arg1 bar:arg2", where "foo:bar:" would be the message name, and "arg1", "arg2" be the arguments.

In Java, the message name is a single identifier, and arguments are written in an argument list after the message name: "receiver.fooBar(arg1, arg2)".

When message names are translated, only the very first part of the Smalltalk keyword message is taken ("foo" in the above example), and the remaining parts are simpl ignored. Thus, any of the Smalltalk messages "foo:bar:", "foo:xxxx:" and "foo:_:" (a single underscore as second part) all translate to the same Java message name "foo()".

Therefore, to call a method with more than one argument, like <CODE>"setSize(int width,int height)"</CODE> on a JFrame instance we can write:
<CODE><PRE>
frame setSize:300 _:200.
</PRE></CODE>
but just as well:
<CODE><PRE>
frame setSize:300 anyWord:200.
</PRE></CODE>
or any other selector with "setSize:" as its first component.
The selector translation mechanism simply takes the first part as the Java selector.

In practice, you should take a reasonably descriptive name, such as: "frame setSize:300 height:200" or only the Java name as first part, such as "frame setSize:300 _:200".

For a call of a method with 4 arguments, we could write:
<CODE><PRE>
frame setBounds:100 y:50 width:300 height:200.
</PRE></CODE>
or:
<CODE><PRE>
frame setBounds:100 _:50 _:300 _:200.
</PRE></CODE>

Also here the <CODE>"y: width: height:"</CODE> can be named as you want, but the first part must be "setBounds:".

=== Calling Static Methods ===

Calling a static method on an object is not different from calling non static methods. In most cases you will call a static method not on an object but directly on the class. This is done by using the class object as "receiver" of the message. For example, if we want to call the static method <CODE>"isDefaultLookAndFeelDecorated()"</CODE> of the JFrame class, write:
<CODE><PRE>
java getJavaClass:'javax.swing.JFrame' isDefaultLookAndFeelDecorated.
</PRE></CODE>

== Accessing Fields ==

As Smalltalk does not support access of an object's fields from the outside (it is fully encapsulated, and access from outside is ONLY allowed via getters/setters), an additional translation mechanism is provided for field access.

Accessing a field of a Java object or a class's static field uses the same syntax as method calls. To access a field, send a message where the message is the field name. To access the field of a class the field must be static.
For example, to get the value of the static field named <CODE>"EXIT_ON_CLOSE"</CODE> of the "JFrame" class, write
<CODE><PRE>
value := java getJavaClass:'javax.swing.JFrame' EXIT_ON_CLOSE.
</PRE></CODE>
The variable "value" now holds the integer value of the <CODE>"EXIT_ON_CLOSE"</CODE> constant.

Assuming that a "JFrame" object had a field named <CODE>"myField"</CODE>, to access this field, we'd have to write:
<CODE><PRE>
value := frame myField.
</PRE></CODE>
and "value" now holding whatever <CODE>"myField"</CODE> returns. This could be another object reference or any primitive value.

=== Setting Fields ===
To set a field, use a setter-like method call:
<CODE><PRE>
frame myField: newValue.
</PRE></CODE>

=== Name Conflicts ===

In very rare situations, a Java object may contain both a field and a method by the same name.
In this case, the Smalltalk code cannot depend on the dynamic translation mechanism (which actually looks for either a field or method name to match), but instead make it explicit, which operation is wanted:
Use:
<CODE><PRE>
frame getFieldByName:'myField'
</PRE></CODE>
to read a field, and:
<CODE><PRE>
frame setFieldByName:'myField' value:123.
</PRE></CODE>
to write the field.

If there are both fields and methods by the same name, and you use the non-explicit call,
the bridge will always assume that you want to call the getter/setter and perform a method call.
 

== Arrays ==

=== Passing Smalltalk Collections to Java ===

Smalltalk collections can now be directly passed to Java with a few limitations:
* The identity of the Smalltalk collections will not be preserved. passing the same collection to java multiple times will result in multiple instances of the same array on the java side. (to bypass this instantiate a new java array)
* Smalltalk collections need to be explicitly converted to the correct type (e.g. a <CODE>SignedIntegerArray</CODE> on the smalltalk side matches an <CODE>int</CODE>-Array on the java side)

=== Instantiating Arrays ===

The new bridge supports instantiation of arrays (whereas previously reflection had to be used to instantiate arrays from the smalltalk side).
There are two ways an array can be instantiated:

<CODE><PRE>
intArray := (java getJavaClass:'int[]') new:#[ 1 2 3 4 5 ] asSignedIntegerArray. "/ instantiates a new array of type "int" with the contents "1, 2, 3, 4, 5"
</PRE></CODE>

<CODE><PRE>
intArray := (java getJavaClass:'int[]') new:10. "/ instantiates a new empty array of type "int" with 10 elements.
</PRE></CODE>

=== Accessing Arrays ===

To achieve better performance, arrays of primitive types smaller than a certain size have their contents cached on the smalltalk side:
<CODE><PRE>
intArray contents at:1. "/ this will access the first element of the cached contents.
</PRE></CODE>

large arrays are not serialized immediately. large arrays will be serialized when <CODE>contents</CODE> is called the first time.

'''Attention:''' Java arrays are not immutable. changes to an array are not reflected in the cached contents. if an array has been updated, call <CODE>refresh</CODE> on the array to update the cache. arrays will not be updated automatically.

<CODE><PRE>
shortArray := (java getJavaClass:'short[]') new:10. "/ new empty "short" array with 10 elements

"/ copy the contents of the smalltalk collection to the newly instantiated short array
(java getJavaClass:'java.lang.System') arraycopy:(#[ 1 2 3 ] asSignedWordArray) srcPos:0 dest:shortArray destPos:0 length:3.

shortArray at:0. "/ will reflect the changes made to the array

shortArray contents at:1. "/ will still return 0 because the cached contents have not been updated.

shortArray refresh. "/ update the cached contents

shortArray contents at:1. "/ will now correctly reflect the changes made to the array
</PRE></CODE>

== Asynchronous Communication ==

In the new Bridge, everything can be done asynchronously. This is achieved via the <CODE>asyncDo:aBlock</CODE> method.
Every request sent to the Bridge inside of aBlock will immediately return a lazy value.
This lazy value will block upon access until the actual result is received from the java side.
The order of execution is guaranteed to be the same on the java side as on the smalltalk side.

Example:
<CODE><PRE>
java asyncDo:[
lazyInteger := (java getJavaClass:'java.lang.Integer') new:40. "/ this will return immediately
].
actualInteger := lazyInteger value. "/ this will block until the result is available
</PRE></CODE>

== Callbacks from Java ==
Sometimes you may want to execute a piece of Smalltalk code during the execution of the Java code. For example, we may want to install a Smalltalk observer to be notified when a button on a Java GUI was pressed,
or some other callback from a Java framework.

The following code registers a Smalltalk block as a callback for a mouse press event of a button:
<CODE><PRE>
listener := MouseListener new.
listener implementMethod:'mousePressed' as:[ Transcript showCR:'Hello from Java' ].
</PRE></CODE>
The above creates the callback and the listener, which can now be registered on a button:
<CODE><PRE>
button addMouseListener:listener.
</PRE></CODE>
Now, with the press of the button in the Java GUI, the Smalltalk block will be executed and writes <CODE>"Hello from Java"</CODE> to the Smalltalk console.
Of course, any other (Smalltalk-)action code can be made to run via this mechanism.

But be aware, that the callback is possibly called later (when the elementary action, which installed the code, has already finished long ago). Also, as the Java code execution is not synchronized with any of your expecco action execution, the callback may also be called at any arbutrary time, even at times when no activity at all is executed on the expecco side. If you forget to cleanup, and the Java object is still alive, it may even be called after you have finished your test run (if you keep the java bridge handle around and alive, for example in an expecoo environment variable).

So the Smalltalk callback code should not depend on any particular elementary action to be currently running, but instead in most cases write some information into a shared data container, preferably an instance of "SharedQueue", which is thread safe. Then, some other action (an elementary action) would read-wait and read events from that shared queue.

make sure that your test correctly cleans up any such callbacks afterwards. As a last resort, use the "Shutdown Bridge Connection" menu item, which closes the bridge connection, and thereby - as a side effect - removes any leftover callbacks. It does close the connection, and any remaining java proxy object handles become invalid, though.

Another example, using an observer could look like:
<CODE><PRE>
observer := java Observer new.
observer implementMethod:'update'
as:[:sourceObservable :argument|
argument notNil ifTrue:[ Transcript showCR:('I was notifyed with: ',argument toString) ]
ifFalse:[ Transcript showCR:'I was notifyed and the argument was nil' ].
].
myObservable addObserver:observer.
</PRE></CODE>
When the observable calls <CODE>"notifyObservers"</CODE>, the Smalltalk block will be executed.

== Exceptions in Java ==
Exceptions on the Java side are signalled back to the Smalltalk side and raise a corresponding exception there. However, on the Java side, the call stack which lead to the exception has already been unwound at that time (Java exceptions are not proceedable). So a proceed in the Smalltalk-side exception handler only affects the Smalltalk caller, but may leave the Java side in an undefined state.

== Remote Dynamic Code Injection ==
Sometimes we might want to execute code without the overhead of many rpc-messages being sent over the bridge, especially if we want to do something time critical, or want to make execution time measurements.
For this, it is possible to load a class at runtime into the JavaVM. The code of the class will first be sent to the JavaVM, which will compile and load the generated byte code. Then, the class can be accessed via the bridge just like any other preloaded class.

The following example specifies the class code in a smalltalk string and inject the code into the JavaVM. Then an instance of that new class will be instantiated and finally a method of the object instance will be invoked:
<CODE><PRE>
classCode := '
package myPackage.test;

import java.awt.BorderLayout;
import java.awt.event.MouseAdapter;
import java.awt.event.MouseEvent;
import java.util.Calendar;

import javax.swing.JButton;
import javax.swing.JFrame;
import javax.swing.JLabel;;

public class MyInjectedClass {
public void createSampleApp(){
JFrame frame=new JFrame("Hello im injected");
frame.setLayout(new BorderLayout());
JButton button=new JButton("click me");
final JLabel label=new JLabel("Text");
button.addMouseListener(new MouseAdapter() {

@Override
public void mouseClicked(MouseEvent e) {
label.setText(Calendar.getInstance().getTime().toString());
}
});
frame.add(label,BorderLayout.NORTH);
frame.add(button,BorderLayout.SOUTH);
frame.setSize(300, 300);
frame.setVisible(true);
}
}
'.
classObject := java getJavaClass:'myPackage.test.MyInjectedClass' fromSource:classCode.
classObject new createSampleApp.
</PRE></CODE>
After the code has been injected, a new instance of <CODE>"MyInjectedClass"</CODE> is created and the <CODE>"createSampleApp"</CODE> method is called. Because the example implements a GUI, a Java window will open, containing a label and a button. Clicking the button displays the current time in the label.



=== Code Sources for Class injection ===
There are 3 possible types of class code sources which we can use to inject the code. In the examples before we directly used a simple <CODE>"String"</CODE> in the smalltalk code as a code source. We also can use a <CODE>"*.java"</CODE> file as source. Just read the content of the file into a string and use it as in the previous examples.

To inject a <CODE>"*.class"</CODE> file use the following code:
<pre>
java getJavaClass:'the.class.name' fromByteCode:classCode.
</pre>

== Examples ==

This example creates a JFrame with one button inside. Then a Mouselistener is created and registered on the button. When the button is pressed, the title of the window changes to <CODE>"onPressed"</CODE> and the Transcript shows the message <CODE>"onPressed"</CODE>. When the button is released, the title of the window is changed to <CODE>"onReleased"</CODE> and the Transcript shows <CODE>"onReleased"</CODE>. If the button lost the mouse focus, the bridge will exit (disconnect), and the Java side is terminated.
<CODE><PRE>
|java frame button listener|

"/getting a bridge
java := JAVA::JavaBridge newWithServer.

"/creating a new frame and button object
frame := java getJavaClass:'javax.swing.JFrame' new.
button := java JButton new:'Click'.

"/creating a new mouse listener and adding callback blocks
listener := java MouseListener new.

listener implementMethod:'mousePressed' as:[ Transcript showCR:'onPress'. frame setTitle:'onPressed' ].
listener implementMethod:'mouseReleased' as:[ Transcript showCR:'onReleased'. frame setTitle:'onReleased' ].
listener implementMethod:'mouseExited' as:[ Transcript showCR:'onExited'. java closeBridge. ].

"/register the mouse listener on the button and make the frame with button visible
button addMouseListener:listener.
frame add:button.
frame setSize:300 y:100.
frame setVisible: true.
</PRE></CODE>



==Differences between v1 and v2==
===General===
* A Java Bridge instance no longer requires multiple tcp ports to be open. This simplifies connection through ssh tunnels and firewalls.
* The identity of strings and primitve wrappers can now be preserved. (see [[#boxedDo:aBlock | boxedDo]])
* Simplified instantiation and access of arrays. (see [[#Arrays | Arrays]])
* Every request to the java side can now be done asynchronously. (see [[#Asynchronous Communication | Asynchronous Communication]])

===Loading Applications===
* '''addJarByPath:''' and '''addToClassPath:''' are still supported but have been deprecated. use '''loadJar:''', '''loadJarByPath:''' and '''loadExtension:''' instead. The new methods no longer require the jar or library to be present on the remote machine.

[[Java Interface Library#Loading Applications (from the expecco side) | v1]] [[#Loading Applications (from the expecco side) | v2]]

===Java Class Access===
* Sending the fully qualified name with instances of "." replaced by "_" to the bridge handle is still supported, but not recommended.
* A new method '''getJavaClass:''' has been introduced (also available for v1 since expecco v2.9). This solves the side effects of "_" being a legal character in class names.

[[Java Interface Library#Java Package Import and Class Access | v1]] [[#Java Class Access | v2]]
===Callbacks from Java===
* A new method '''implementMethod:as:''' has been introduced to assign callback blocks to method names. The old way is still supported.

[[Java Interface Library#Callbacks from Java | v1]] [[#Callbacks from Java | v2]]

===Remote Dynamic Code Injection===
* Code injection was problematic in v1 and has now been re-implemented in v2.

[[#Remote Dynamic Code Injection | v2]]

== API ==
===JAVA::Java===
====class protocol====
=====newWithServer=====
* This will start a local JavaVM, running the JavaBridge, and establishes a connection on a random free port.
: A new connected instance of JAVA::Java class is returned.

=====newWithServerForJavaPath:aJavaPathFilename=====
* This is the same as newWithServer but the path to the java executable can be specified. The JavaVM version must be 1.6 or higher to run the JavaBridge.
:: '''aJavaPathFilename''' - must be a instance of Filename
Smalltalk: JAVA::Java newWithServerForJavaPath:('my\path\to\java.executable'asFilename).
JavaScript: JAVA::Java.newWithServerForJavaPath("my\path\to\java.executable".asFilename());

=====newConnectedTo:aHhostString port:aPortNumber withTimeout:aTimeoutSeconds=====
* This is used to connect to a running JavaBridge on the network. The JavaBridge must be started in server mode on the remote host. After connecting a new connected instance of JAVA::Java is returned.
:: '''aHostString''' - the hostname or IP of the remote machine as String
:: '''aPortNumber ''' - the port on which the remote machine is listening as Number
:: '''aTimeoutSeconds''' - a connect timeout in seconds as Number
Smalltalk: JAVA::Java newConnectedTo:'myHostName' port:4567 withTimeout:30.
JavaScript: JAVA::Java.newConnectedTo_port_withTimeout("myHostName",4567,30);

=====newWaitingForConnectOnHost:aListeningAddressString port:aListeningPortNumber withTimeout:aTimeoutSeconds=====
* This is used to wait for incomming connecions of a running JavaBridge on the network. The JavaBridge must be started in client mode on the remote host. After connecting a new connected instance of JAVA::Java is returned.
:: '''deprecated: aListeningAddressString''' - no longer used. Can be nil.
:: '''aListeningPortNumber ''' - the port on which to listen for incomming connections as Number
:: '''aTimeoutSeconds''' - a connect timeout in seconds as Number, If nil it will wait endless.

=====singletonInstance=====
* This will call newWithServer for the first time and then always returns the same connected JAVA::Java instance until the connection was closed, then a new connected instance is returned.

=====exitAllInstances=====
* This will close all instances of JAVA::Java.

====instance protocol====
=====loadJarByPath:aPath=====
* Adds a jar to the running JavaVM. If the jar depends on other jars or libraries you have to add them too.
:: '''aPath''' - the path to the jar file as String.

=====loadJar:aByteArray=====
* Adds a jar to the running JavaVM. If the jar depends on other jars or libraries you have to add them too.
:: '''aByteArrays''' - a ByteArray containing the JAR file.

=====loadExtension:aPath=====
* Adds a jar to the running JavaVM and caches it for subsequent usages. If the jar depends on other jars you have to add them too.
:: '''aPath''' - the path to the jar file as String.

=====boxedDo:aBlock=====
* Any autoboxed values in aBlock returned from the JavaVM are preserved as such. By default autoboxed values are automatically unboxed. This way, the identity of such objects is preserved.

=====isConnected=====
* Tests if a connection is still established.
:: '''return:''' - true if the connection is still established, else false.

=====isAlive=====
* Tests if a connection is still responding.
:: '''return:''' - true if the connection is still alive, else false. Does a message round trip.

=====closeBridge=====
* This will close the bridge connection. Depending on in which mode the JavaBridge was started, the JavaVM is also closed (-keepAlive startparameter not set).

=====exit=====
* Same as closeBridge.

== See Also==
The [[DOT NET Interface Library| DOTNET Interface Plugin & Library]], which implements a likewise interface for .NET applications/libraries.
 
[[Java Interface Library | Version 1 of the Java Interface Library]]
<hr>
Back to [[Plugins]]

Java Interface Library v2

2016-06-01T11:00:23Z

Javogel: /* Asynchronous Communication */

== Introduction ==

This article discusses version 2 of the Java Bridge (which is as of expecco v2.9 still experimental).
The article for version 1 can be found [[Java Interface Library | here]].

The Java Interface library ("Java Bridge") is used to interact with Java objects inside an external Java Virtual Machine (JVM).

The access to Java objects, classes and programs is done via a framework called "''Java-Bridge''", which is similar in operation to the [[DOT NET Interface Library| dotNET bridge]]. This framework implements transparent forwarding of method (virtual function) calls to Java objects, which exist in a local or remote Java Virtual Machine (JVM). Also, return values, callBacks and exception information are passed back from the Java program to expecco. This is done by a proxy-object mechanism, which catches all function calls, wraps the arguments, sends a datagram to the other bridge side, awaits the reply and returns the result to the original caller. Thus, remote procedure calls are almost completely transparent to the Smalltalk/JavaScript code inside expecco. In your elementary code, you can write remote function calls as if they were to local objects.

Notice that this document describes the low level framework, which implements the bridge communication. A much easier to use high level interface (called "Groovy Blocks") exists and should normally be used, if you need access to a java application's internals during testing.
Please take a look at
[[Expecco_API#Groovy_Elementary_Blocks | "Groovy Block API"]]
and [[Testing Java Applications using Groovy blocks/en | "Testing Java Applications using Groovy blocks"]].

== Architecture ==

On the expecco side, the bridge consists of a number of Proxy objects,
which behave like regular Smalltalk objects as seen from elementary expecco code.
However, instead of performing an action when one of their methods (virtual functions) is called,
they send a message over a socket connection to the Java VM (actually: to a bridge software inside the
Java application) which decodes the message and sends it to the destination Java object.
The same is done in reverse direction with the return value.

+---------------------+ +----------+ +----------------+ +----------------+ +---------+
| | | | | | | | | Java |
| expecco |---->| Proxy |---->| Bridge |==>>==| Bridge |---->| Object |
| (elementary code) |<----| |<----| (expecco side) |==<<==| (Java side) |<----| |
+---------------------+ +----------+ +----------------+ +----------------+ +---------+

This setup allows for transparent communication with objects inside a local or remote Java VM. This may be either utility functions which happen to be convenient for the test application (for example: file parsing, syntax analysis, protocol implementaitons or access to specific hardware via driver libraries), or the tested application in the system under test itself.

Especially, it allows for the objects of the tested application to be looked into, manipulated and for functions of it or underlying frameworks to be called.

For expecco code, we tried to make this as transparent as possible, however there are a few exceptions, when function names need to be translated (for example, because the function naming syntax is different) or due to the fact that for some operations no corresponding name exists in Smalltalk (array access, for example).

Of course, multiple such connections can coexist and be served/handled in parallel. This enables an expecco test suite to communicate with both sides of a tested client-server Java application, for example.

Notice that a similar mechanism is used in expecco to communicate with DOTNET, Qt (C++) and C applications.

 

== Activating the new Java Bridge ==
To activate the new bridge in expecco navigate to <CODE>Extras -> Settings -> Plugins -> Java Bridge</CODE> and tick the '''Use new Bridge (experimental)''' checkbox.
[[Datei:ActivateNewJavaBridge.png]]

'''Attention:''' Ticking the checkbox will terminate all currently active Bridge connections due to incompatibilities between the new and the old version.

== Initializing / Releasing the Bridge ==

Before any communication can take place between expecco and any Java object, the Java side of the bridge has to be started, and a communication has to be established.
In expecco, all of the bridge classes are found in the <CODE>JAVA</CODE> namespace.

The main interface class is "<CODE>Java</CODE>", in the "<CODE>JAVA</CODE>" namespace:
<CODE><PRE>
java := JAVA::Java newWithServer.
</PRE></CODE>
or (in JavaScript):
<CODE><PRE>
java = JAVA::Java.newWithServer();
</PRE></CODE>

This starts the Java-side of the bridge (actually executes java as a background command) on the local machine, and establishes a connection to that JVM.

The bridge connection should be closed, if the bridge is no longer needed. Release the bridge with:
<CODE><PRE>
java.closeBridge();
</PRE></CODE>
which terminates the connection.

=== Start and Connect to a Remote Machine ===
The above started a Java VM and connected to it. Alternatively, you may want to connect to an already running Java program (typically, your system under test).
In order for your program to be reachable, it must allow for the bridge to connect to it via a special bridge-connection, which is a socket connection. For this, it must execute the server code found in the "JavaBridge.jar" file. To pass [[#Startup Parameters| parameters]] you will typically start it from a command line or a little shell/batch script.

Call (on the shell/cmd level):
$ java -jar <PATH_TO_JAVABRIDGE.JAR> <PARAMETERS>

The "JavaBridge.jar" file is found in the installation directory of expecco at:
\exept\expecco\packages\exept\bridgeFramework\javaBridge\javaBin\JavaBridge.jar

The Javabridge code allows for either side to initiate the connection - i.e. it can be run in server mode,
where it awaits an incoming connection, or in client mode, where it actively initiates a connection.
After connection establishment, there is no difference in the operation of the bridge, however depending on the setup of your network infrastructure, especially firewalls, either mechanism may be easier to be used.

Assuming that the bridge is already running on the remote machine as server (default),
use <CODE>newConnectedTo:port:withTimeout:</CODE> to connect to it from the expecco side:
java := JAVA::Java newConnectedTo:'myHost' port:4567 withTimeout:30.
This will initiate the connection setup from the expecco side.

Alternatively, if started in client mode use <CODE>newWaitingForConnectOnHost:port:withTimeout:</CODE>:
java := JAVA::Java newWaitingForConnectOnHost:'localhost' port:4567 withTimeout:30.
which will open a port on the expecco side, and wait until the Java side connects to it.
[[#JAVA::Java|For more details see API]]

====Startup Parameters====
You can use any parameter in any order.
If no parameter is used then the bridge listenes on port 14014 in server mode without keepAlive.
;<code>-help</code>
* Shows the help

;<code>-ip <aHostnameOrIP></code>
* In client mode this specifies the ip or hostname to connect to. In server mode this specifies the ip or hostname to bind to.

;<code>-port <aPortNumber> </code>
* In client mode this specifies the port to connect to. In server mode this specifies the listening port.

;<code>-asClient</code>
* The bridge will start in client mode. If not set the bridge is started in server mode.

;<code>-keepAlive</code>
* By setting this flag the bridge will not exit after the connection has closed and starts to connect or listen again. Otherwise, it will run for a single connection session only.

== Loading Applications (from the expecco side) ==

Normally, you would start your application with the required command line arguments and include the javabridge as jar there. However, in some situations, it may be required to dynamically load other jars into the connected Java VM.
By accessing a classloader, additional classes, or applications as contained in JAR files can be loaded from the expecco side.

This can be used to add a JAR file to the classloader:
<CODE><PRE>
java loadJarByPath:'pathToJarFile'. "/ assuming "java" is a handle as returned from the above connect
</PRE></CODE>

or, if the JAR file is loaded in memory:
<CODE><PRE>
java loadJar:jarByteArray. "/ where "jarByteArray" is a ByteArray containing the JAR file
</PRE></CODE>

If the JVM is on a remote machine, the path is resolved on the expecco side and the JAR will be transferred to the remote side.

Should transferring the JAR be too much overhead, an additional mechanism is provided:
<CODE><PRE>
java loadExtension:'pathToJarFile'.
</PRE></CODE>
this will cache the JAR file on the bridge side and eliminate the overhead of subsequent invocations.

== Java Class Access ==

This following code sample simply references (i.e. accesses) the class "JFrame" from the <CODE>"javax.swing"</CODE> package. The fully specified class name in Java would be <CODE>"javax.swing.JFrame"</CODE>:
<CODE><PRE>
java getJavaClass:'javax.swing.JFrame'
</PRE></CODE>

Or, if you want to load multiple classes:
<CODE><PRE>
java import:'javax.swing.JFrame' import:'javax.swing.JButton'
do:[:jFrame :jButton | "do something with JButton and JFrame" ].
</PRE></CODE>

v2 also supports dynamic compilation of java source code:
<CODE><PRE>
java getJavaClass:'className' fromSource:'classSource'. "/ where classSource is a String containing valid java source code
</PRE></CODE>

and loading precompiled java bytecode:
<CODE><PRE>
java getJavaClass:'className' fromByteCode:byteCode. "/ where byteCode is a ByteArray containing valid java bytecode
</PRE></CODE>

[[#Remote Dynamic Code Injection | for details see Remote Dynamic Code Injection]]

== Instantiating a Class ==

Object instances are created via the "new"-message, sent to a proxy of a Java class. You can get this proxy as described in the previous section. For example, if we want to create a new instance of a "JFrame" and a "JButton", write:
<CODE><PRE>
frame := java getJavaClass:'javax.swing.JFrame' new.
button := java getJavaClass:'javax.swing.JButton' new.
</PRE></CODE>
The first statement results in a proxy object for the "JFrame" instance. The second line results in a proxy for a new "JButton" object.

== Calling Instance Methods ==

A method call is done by a message send to a proxy object, where the message is the method name to call. For example, to call the <CODE>"setVisible(boolean isVisible)"</CODE> method on the above JFrame object, we send the following message to that proxy:
<CODE><PRE>
frame setVisible:true.
</PRE></CODE>

As method naming is different in Smalltalk and Java, a dynamic translation is applied when sending messages from Smalltalk code to a remote Java object. Smalltalk has arguments embedded inside parts of a so called "keyword" message, such as in "receiver foo:arg1 bar:arg2", where "foo:bar:" would be the message name, and "arg1", "arg2" be the arguments.

In Java, the message name is a single identifier, and arguments are written in an argument list after the message name: "receiver.fooBar(arg1, arg2)".

When message names are translated, only the very first part of the Smalltalk keyword message is taken ("foo" in the above example), and the remaining parts are simpl ignored. Thus, any of the Smalltalk messages "foo:bar:", "foo:xxxx:" and "foo:_:" (a single underscore as second part) all translate to the same Java message name "foo()".

Therefore, to call a method with more than one argument, like <CODE>"setSize(int width,int height)"</CODE> on a JFrame instance we can write:
<CODE><PRE>
frame setSize:300 _:200.
</PRE></CODE>
but just as well:
<CODE><PRE>
frame setSize:300 anyWord:200.
</PRE></CODE>
or any other selector with "setSize:" as its first component.
The selector translation mechanism simply takes the first part as the Java selector.

In practice, you should take a reasonably descriptive name, such as: "frame setSize:300 height:200" or only the Java name as first part, such as "frame setSize:300 _:200".

For a call of a method with 4 arguments, we could write:
<CODE><PRE>
frame setBounds:100 y:50 width:300 height:200.
</PRE></CODE>
or:
<CODE><PRE>
frame setBounds:100 _:50 _:300 _:200.
</PRE></CODE>

Also here the <CODE>"y: width: height:"</CODE> can be named as you want, but the first part must be "setBounds:".

=== Calling Static Methods ===

Calling a static method on an object is not different from calling non static methods. In most cases you will call a static method not on an object but directly on the class. This is done by using the class object as "receiver" of the message. For example, if we want to call the static method <CODE>"isDefaultLookAndFeelDecorated()"</CODE> of the JFrame class, write:
<CODE><PRE>
java getJavaClass:'javax.swing.JFrame' isDefaultLookAndFeelDecorated.
</PRE></CODE>

== Accessing Fields ==

As Smalltalk does not support access of an object's fields from the outside (it is fully encapsulated, and access from outside is ONLY allowed via getters/setters), an additional translation mechanism is provided for field access.

Accessing a field of a Java object or a class's static field uses the same syntax as method calls. To access a field, send a message where the message is the field name. To access the field of a class the field must be static.
For example, to get the value of the static field named <CODE>"EXIT_ON_CLOSE"</CODE> of the "JFrame" class, write
<CODE><PRE>
value := java getJavaClass:'javax.swing.JFrame' EXIT_ON_CLOSE.
</PRE></CODE>
The variable "value" now holds the integer value of the <CODE>"EXIT_ON_CLOSE"</CODE> constant.

Assuming that a "JFrame" object had a field named <CODE>"myField"</CODE>, to access this field, we'd have to write:
<CODE><PRE>
value := frame myField.
</PRE></CODE>
and "value" now holding whatever <CODE>"myField"</CODE> returns. This could be another object reference or any primitive value.

=== Setting Fields ===
To set a field, use a setter-like method call:
<CODE><PRE>
frame myField: newValue.
</PRE></CODE>

=== Name Conflicts ===

In very rare situations, a Java object may contain both a field and a method by the same name.
In this case, the Smalltalk code cannot depend on the dynamic translation mechanism (which actually looks for either a field or method name to match), but instead make it explicit, which operation is wanted:
Use:
<CODE><PRE>
frame getFieldByName:'myField'
</PRE></CODE>
to read a field, and:
<CODE><PRE>
frame setFieldByName:'myField' value:123.
</PRE></CODE>
to write the field.

If there are both fields and methods by the same name, and you use the non-explicit call,
the bridge will always assume that you want to call the getter/setter and perform a method call.
 

== Arrays ==

=== Passing Smalltalk Collections to Java ===

Smalltalk collections can now be directly passed to Java with a few limitations:
* The identity of the Smalltalk collections will not be preserved. passing the same collection to java multiple times will result in multiple instances of the same array on the java side. (to bypass this instantiate a new java array)
* Smalltalk collections need to be explicitly converted to the correct type (e.g. a <CODE>SignedIntegerArray</CODE> on the smalltalk side matches an <CODE>int</CODE>-Array on the java side)

=== Instantiating Arrays ===

The new bridge supports instantiation of arrays (whereas previously reflection had to be used to instantiate arrays from the smalltalk side).
There are two ways an array can be instantiated:

<CODE><PRE>
intArray := (java getJavaClass:'int[]') new:#[ 1 2 3 4 5 ] asSignedIntegerArray. "/ instantiates a new array of type "int" with the contents "1, 2, 3, 4, 5"
</PRE></CODE>

<CODE><PRE>
intArray := (java getJavaClass:'int[]') new:10. "/ instantiates a new empty array of type "int" with 10 elements.
</PRE></CODE>

=== Accessing Arrays ===

To achieve better performance, arrays of primitive types smaller than a certain size have their contents cached on the smalltalk side:
<CODE><PRE>
intArray contents at:1. "/ this will access the first element of the cached contents.
</PRE></CODE>

large arrays are not serialized immediately. large arrays will be serialized when <CODE>contents</CODE> is called the first time.

'''Attention:''' Java arrays are not immutable. changes to an array are not reflected in the cached contents. if an array has been updated, call <CODE>refresh</CODE> on the array to update the cache. arrays will not be updated automatically.

<CODE><PRE>
shortArray := (java getJavaClass:'short[]') new:10. "/ new empty "short" array with 10 elements

"/ copy the contents of the smalltalk collection to the newly instantiated short array
(java getJavaClass:'java.lang.System') arraycopy:(#[ 1 2 3 ] asSignedWordArray) srcPos:0 dest:shortArray destPos:0 length:3.

shortArray at:0. "/ will reflect the changes made to the array

shortArray contents at:1. "/ will still return 0 because the cached contents have not been updated.

shortArray refresh. "/ update the cached contents

shortArray contents at:1. "/ will now correctly reflect the changes made to the array
</PRE></CODE>

== Asynchronous Communication ==

In the new Bridge, everything can be done asynchronously. This is achieved via the <CODE>asyncDo:aBlock</CODE> method.
Every request sent to the Bridge inside of aBlock will immediately return a lazy value.
This lazy value will block upon access until the actual result is received from the java side.
The order of execution is guaranteed to be the same on the java side as on the smalltalk side.

Example:
<CODE><PRE>
java asyncDo:[
lazyInteger := (java getJavaClass:'java.lang.Integer') new:40. "/ this will return immediately
].
actualInteger := lazyInteger value. "/ this will block until the result is available
</PRE></CODE>

== Callbacks from Java ==
Sometimes you may want to execute a piece of Smalltalk code during the execution of the Java code. For example, we may want to install a Smalltalk observer to be notified when a button on a Java GUI was pressed,
or some other callback from a Java framework.

The following code registers a Smalltalk block as a callback for a mouse press event of a button:
<CODE><PRE>
listener := MouseListener new.
listener implementMethod:'mousePressed' as:[ Transcript showCR:'Hello from Java' ].
</PRE></CODE>
The above creates the callback and the listener, which can now be registered on a button:
<CODE><PRE>
button addMouseListener:listener.
</PRE></CODE>
Now, with the press of the button in the Java GUI, the Smalltalk block will be executed and writes <CODE>"Hello from Java"</CODE> to the Smalltalk console.
Of course, any other (Smalltalk-)action code can be made to run via this mechanism.

But be aware, that the callback is possibly called later (when the elementary action, which installed the code, has already finished long ago). Also, as the Java code execution is not synchronized with any of your expecco action execution, the callback may also be called at any arbutrary time, even at times when no activity at all is executed on the expecco side. If you forget to cleanup, and the Java object is still alive, it may even be called after you have finished your test run (if you keep the java bridge handle around and alive, for example in an expecoo environment variable).

So the Smalltalk callback code should not depend on any particular elementary action to be currently running, but instead in most cases write some information into a shared data container, preferably an instance of "SharedQueue", which is thread safe. Then, some other action (an elementary action) would read-wait and read events from that shared queue.

make sure that your test correctly cleans up any such callbacks afterwards. As a last resort, use the "Shutdown Bridge Connection" menu item, which closes the bridge connection, and thereby - as a side effect - removes any leftover callbacks. It does close the connection, and any remaining java proxy object handles become invalid, though.

Another example, using an observer could look like:
<CODE><PRE>
observer := java Observer new.
observer implementMethod:'update'
as:[:sourceObservable :argument|
argument notNil ifTrue:[ Transcript showCR:('I was notifyed with: ',argument toString) ]
ifFalse:[ Transcript showCR:'I was notifyed and the argument was nil' ].
].
myObservable addObserver:observer.
</PRE></CODE>
When the observable calls <CODE>"notifyObservers"</CODE>, the Smalltalk block will be executed.

== Exceptions in Java ==
Exceptions on the Java side are signalled back to the Smalltalk side and raise a corresponding exception there. However, on the Java side, the call stack which lead to the exception has already been unwound at that time (Java exceptions are not proceedable). So a proceed in the Smalltalk-side exception handler only affects the Smalltalk caller, but may leave the Java side in an undefined state.

== Remote Dynamic Code Injection ==
Sometimes we might want to execute code without the overhead of many rpc-messages being sent over the bridge, especially if we want to do something time critical, or want to make execution time measurements.
For this, it is possible to load a class at runtime into the JavaVM. The code of the class will first be sent to the JavaVM, which will compile and load the generated byte code. Then, the class can be accessed via the bridge just like any other preloaded class.

The following example specifies the class code in a smalltalk string and inject the code into the JavaVM. Then an instance of that new class will be instantiated and finally a method of the object instance will be invoked:
<CODE><PRE>
classCode := '
package myPackage.test;

import java.awt.BorderLayout;
import java.awt.event.MouseAdapter;
import java.awt.event.MouseEvent;
import java.util.Calendar;

import javax.swing.JButton;
import javax.swing.JFrame;
import javax.swing.JLabel;;

public class MyInjectedClass {
public void createSampleApp(){
JFrame frame=new JFrame("Hello im injected");
frame.setLayout(new BorderLayout());
JButton button=new JButton("click me");
final JLabel label=new JLabel("Text");
button.addMouseListener(new MouseAdapter() {

@Override
public void mouseClicked(MouseEvent e) {
label.setText(Calendar.getInstance().getTime().toString());
}
});
frame.add(label,BorderLayout.NORTH);
frame.add(button,BorderLayout.SOUTH);
frame.setSize(300, 300);
frame.setVisible(true);
}
}
'.
classObject := java getJavaClass:'myPackage.test.MyInjectedClass' fromSource:classCode.
classObject new createSampleApp.
</PRE></CODE>
After the code has been injected, a new instance of <CODE>"MyInjectedClass"</CODE> is created and the <CODE>"createSampleApp"</CODE> method is called. Because the example implements a GUI, a Java window will open, containing a label and a button. Clicking the button displays the current time in the label.



=== Code Sources for Class injection ===
There are 3 possible types of class code sources which we can use to inject the code. In the examples before we directly used a simple <CODE>"String"</CODE> in the smalltalk code as a code source. We also can use a <CODE>"*.java"</CODE> file as source. Just read the content of the file into a string and use it as in the previous examples.

To inject a <CODE>"*.class"</CODE> file use the following code:
<pre>
java getJavaClass:'the.class.name' fromByteCode:classCode.
</pre>

== Examples ==

This example creates a JFrame with one button inside. Then a Mouselistener is created and registered on the button. When the button is pressed, the title of the window changes to <CODE>"onPressed"</CODE> and the Transcript shows the message <CODE>"onPressed"</CODE>. When the button is released, the title of the window is changed to <CODE>"onReleased"</CODE> and the Transcript shows <CODE>"onReleased"</CODE>. If the button lost the mouse focus, the bridge will exit (disconnect), and the Java side is terminated.
<CODE><PRE>
|java frame button listener|

"/getting a bridge
java := JAVA::JavaBridge newWithServer.

"/creating a new frame and button object
frame := java getJavaClass:'javax.swing.JFrame' new.
button := java JButton new:'Click'.

"/creating a new mouse listener and adding callback blocks
listener := java MouseListener new.

listener implementMethod:'mousePressed' as:[ Transcript showCR:'onPress'. frame setTitle:'onPressed' ].
listener implementMethod:'mouseReleased' as:[ Transcript showCR:'onReleased'. frame setTitle:'onReleased' ].
listener implementMethod:'mouseExited' as:[ Transcript showCR:'onExited'. java closeBridge. ].

"/register the mouse listener on the button and make the frame with button visible
button addMouseListener:listener.
frame add:button.
frame setSize:300 y:100.
frame setVisible: true.
</PRE></CODE>



==Differences between v1 and v2==
===General===
* A Java Bridge instance no longer requires multiple tcp ports to be open. This simplifies connection through ssh tunnels and firewalls.
* The identity of strings and primitve wrappers can now be preserved. (see [[#boxedDo:aBlock | boxedDo]])
* Arrays of primitive types are serialized. (see [[#Arrays | Arrays]])
* Every request to the java side can now be done asynchronously. (see [[#Asynchronous Communication | Asynchronous Communication]])

===Loading Applications===
* '''addJarByPath:''' and '''addToClassPath:''' are still supported but have been deprecated. use '''loadJar:''', '''loadJarByPath:''' and '''loadExtension:''' instead. The new methods no longer require the jar or library to be present on the remote machine.

[[Java Interface Library#Loading Applications (from the expecco side) | v1]] [[#Loading Applications (from the expecco side) | v2]]

===Java Class Access===
* Sending the fully qualified name with instances of "." replaced by "_" to the bridge handle is still supported, but not recommended.
* A new method '''getJavaClass:''' has been introduced (also available for v1 since expecco v2.9). This solves the side effects of "_" being a legal character in class names.

[[Java Interface Library#Java Package Import and Class Access | v1]] [[#Java Class Access | v2]]
===Callbacks from Java===
* A new method '''implementMethod:as:''' has been introduced to assign callback blocks to method names. The old way is still supported.

[[Java Interface Library#Callbacks from Java | v1]] [[#Callbacks from Java | v2]]

===Remote Dynamic Code Injection===
* Code injection was problematic in v1 and has now been re-implemented in v2.

[[#Remote Dynamic Code Injection | v2]]

== API ==
===JAVA::Java===
====class protocol====
=====newWithServer=====
* This will start a local JavaVM, running the JavaBridge, and establishes a connection on a random free port.
: A new connected instance of JAVA::Java class is returned.

=====newWithServerForJavaPath:aJavaPathFilename=====
* This is the same as newWithServer but the path to the java executable can be specified. The JavaVM version must be 1.6 or higher to run the JavaBridge.
:: '''aJavaPathFilename''' - must be a instance of Filename
Smalltalk: JAVA::Java newWithServerForJavaPath:('my\path\to\java.executable'asFilename).
JavaScript: JAVA::Java.newWithServerForJavaPath("my\path\to\java.executable".asFilename());

=====newConnectedTo:aHhostString port:aPortNumber withTimeout:aTimeoutSeconds=====
* This is used to connect to a running JavaBridge on the network. The JavaBridge must be started in server mode on the remote host. After connecting a new connected instance of JAVA::Java is returned.
:: '''aHostString''' - the hostname or IP of the remote machine as String
:: '''aPortNumber ''' - the port on which the remote machine is listening as Number
:: '''aTimeoutSeconds''' - a connect timeout in seconds as Number
Smalltalk: JAVA::Java newConnectedTo:'myHostName' port:4567 withTimeout:30.
JavaScript: JAVA::Java.newConnectedTo_port_withTimeout("myHostName",4567,30);

=====newWaitingForConnectOnHost:aListeningAddressString port:aListeningPortNumber withTimeout:aTimeoutSeconds=====
* This is used to wait for incomming connecions of a running JavaBridge on the network. The JavaBridge must be started in client mode on the remote host. After connecting a new connected instance of JAVA::Java is returned.
:: '''deprecated: aListeningAddressString''' - no longer used. Can be nil.
:: '''aListeningPortNumber ''' - the port on which to listen for incomming connections as Number
:: '''aTimeoutSeconds''' - a connect timeout in seconds as Number, If nil it will wait endless.

=====singletonInstance=====
* This will call newWithServer for the first time and then always returns the same connected JAVA::Java instance until the connection was closed, then a new connected instance is returned.

=====exitAllInstances=====
* This will close all instances of JAVA::Java.

====instance protocol====
=====loadJarByPath:aPath=====
* Adds a jar to the running JavaVM. If the jar depends on other jars or libraries you have to add them too.
:: '''aPath''' - the path to the jar file as String.

=====loadJar:aByteArray=====
* Adds a jar to the running JavaVM. If the jar depends on other jars or libraries you have to add them too.
:: '''aByteArrays''' - a ByteArray containing the JAR file.

=====loadExtension:aPath=====
* Adds a jar to the running JavaVM and caches it for subsequent usages. If the jar depends on other jars you have to add them too.
:: '''aPath''' - the path to the jar file as String.

=====boxedDo:aBlock=====
* Any autoboxed values in aBlock returned from the JavaVM are preserved as such. By default autoboxed values are automatically unboxed. This way, the identity of such objects is preserved.

=====isConnected=====
* Tests if a connection is still established.
:: '''return:''' - true if the connection is still established, else false.

=====isAlive=====
* Tests if a connection is still responding.
:: '''return:''' - true if the connection is still alive, else false. Does a message round trip.

=====closeBridge=====
* This will close the bridge connection. Depending on in which mode the JavaBridge was started, the JavaVM is also closed (-keepAlive startparameter not set).

=====exit=====
* Same as closeBridge.

== See Also==
The [[DOT NET Interface Library| DOTNET Interface Plugin & Library]], which implements a likewise interface for .NET applications/libraries.
 
[[Java Interface Library | Version 1 of the Java Interface Library]]
<hr>
Back to [[Plugins]]

Java Interface Library/en

2016-06-01T10:46:19Z

Javogel: /* See Also */

Documentation for expecco 2.1

== Introduction ==

The Java Interface library ("Java Bridge") is used to interact with Java objects inside an external Java Virtual Machine (JVM).

The access to Java objects, classes and programs is done via a framework called "''Java-Bridge''", which is similar in operation to the [[DOT NET Interface Library| dotNET bridge]]. This framework implements transparent forwarding of method (virtual function) calls to Java objects, which exist in a local or remote Java Virtual Machine (JVM). Also, return values, callBacks and exception information are passed back from the Java program to expecco. This is done by a proxy-object mechanism, which catches all function calls, wraps the arguments, sends a datagram to the other bridge side, awaits the reply and returns the result to the original caller. Thus, remote procedure calls are almost completely transparent to the Smalltalk/JavaScript code inside expecco. In your elementary code, you can write remote function calls as if they were to local objects.



Notice that this document describes the low level framework, which implements the bridge communication. A much easier to use high level interface (called "Groovy Blocks") exists and should normally be used, if you need access to a java application's internals during testing.
Please take a look at
[[Expecco_API#Groovy_Elementary_Blocks | "Groovy Block API"]]
and [[Testing Java Applications using Groovy blocks/en | "Testing Java Applications using Groovy blocks"]].

== Architecture ==

On the expecco side, the bridge consists of a number of Proxy objects,
which behave like regular Smalltalk objects as seen from elementary expecco code.
However, instead of performing an action when one of their methods (virtual functions) is called,
they send a message over a socket connection to the Java VM (actually: to a bridge software inside the
Java application) which decodes the message and sends it to the destination Java object.
The same is done in reverse direction with the return value.

+---------------------+ +----------+ +----------------+ +----------------+ +---------+
| | | | | | | | | Java |
| expecco |---->| Proxy |---->| Bridge |==>>==| Bridge |---->| Object |
| (elementary code) |<----| |<----| (expecco side) |==<<==| (Java side) |<----| |
+---------------------+ +----------+ +----------------+ +----------------+ +---------+

This setup allows for transparent communication with objects inside a local or remote Java VM. This may be either utility functions which happen to be convenient for the test application (for example: file parsing, syntax analysis, protocol implementaitons or access to specific hardware via driver libraries), or the tested application in the system under test itself.

Especially, it allows for the objects of the tested application to be looked into, manipulated and for functions of it or underlying frameworks to be called.

For expecco code, we tried to make this as transparent as possible, however there are a few exceptions, when function names need to be translated (for example, because the function naming syntax is different) or due to the fact that for some operations no corresponding name exists in Smalltalk (array access, for example).

Of course, multiple such connections can coexist and be served/handled in parallel. This enables an expecco test suite to communicate with both sides of a tested client-server Java application, for example.

Notice that a similar mechanism is used in expecco to communicate with DOTNET, Qt (C++) and C applications.

 

== Initializing / Releasing the Bridge ==

Before any communication can take place between expecco and any Java object, the Java side of the bridge has to be started, and a communication has to be established.
In expecco, all of the bridge classes are found in the <CODE>JAVA</CODE> namespace.

The main interface class is "<CODE>Java</CODE>", in the "<CODE>JAVA</CODE>" namespace:
<CODE><PRE>
java := JAVA::Java newWithServer.
</PRE></CODE>
or (in JavaScript):
<CODE><PRE>
java = JAVA::Java.newWithServer();
</PRE></CODE>

This starts the Java-side of the bridge (actually executes java as a background command) on the local machine, and establishes a connection to that JVM.

The bridge connection should be closed, if the bridge is no longer needed. Release the bridge with:
<CODE><PRE>
java.closeBridge();
</PRE></CODE>
which terminates the connection.

=== Start and Connect to a Remote Machine ===
The above started a Java VM and connected to it. Alternatively, you may want to connect to an already running Java program (typically, your system under test).
In order for your program to be reachable, it must allow for the bridge to connect to it via a special bridge-connection, which is a socket connection. For this, it must execute the server code found in the "JavaBridge.jar" file. To pass [[#Startup Parameters| parameters]] you will typically start it from a command line or a little shell/batch script.

Call (on the shell/cmd level):
$ java -jar <PATH_TO_JAVABRIDGE.JAR> <PARAMETERS>

The "JavaBridge.jar" file is found in the installation directory of expecco at:
\exept\expecco\packages\exept\technologyBridge\javaBridge\javaBridge_Server_Client\JavaBridge.jar

The Javabridge code allows for either side to initiate the connection - i.e. it can be run in server mode,
where it awaits an incoming connection, or in client mode, where it actively initiates a connection.
After connection establishment, there is no difference in the operation of the bridge, however depending on the setup of your network infrastructure, especially firewalls, either mechanism may be easier to be used.

Assuming that the bridge is already running on the remote machine as server (default),
use <CODE>newConnectedTo:port:withTimeout:</CODE> to connect to it from the expecco side:
java := JAVA::Java newConnectedTo:'myHost' port:4567 withTimeout:30.
This will initiate the connection setup from the expecco side.

Alternatively, if started in client mode use <CODE>newWaitingForConnectOnHost:port:withTimeout:</CODE>:
java := JAVA::Java newWaitingForConnectOnHost:'localhost' port:4567 withTimeout:30.
which will open a port on the expecco side, and wait until the Java side connects to it.
[[#JAVA::Java|For more details see API]]

====Startup Parameters====
You can use any parameter in any order.
If no parameter is used then the bridge listenes on port 14014 in server mode without keepAlive.
;<code>-help</code>
* Shows the help

;<code>-ip <aHostnameOrIP></code>
* In client mode this specifies the ip or hostname to connect to.

;<code>-port <aPortNumber> </code>
* In client mode this specifies the port to connect to. In server mode this specifies the listening port.

;<code>-asClient</code>
* The bridge will start in client mode. If not set the bridge is started in server mode.

;<code>-keepAlive</code>
* By setting this flag the bridge will not exit after the connection has closed and starts to connect or listen again. Otherwise, it will run for a single connection session only.

== Loading Applications (from the expecco side) ==

Normally, you would start your application with the required command line arguments and include the javabridge as jar there. However, in some situations, it may be required to dynamically load other jars into the connection Java VM.
By accessing a classloader, additional classes, or applications as contained in JAR files can be loaded from the expecco side.

This can be used to add a JAR file to the class path:
<CODE><PRE>
java addJarByPath:'pathToJarFile'. "/ assuming "java" is a handle as returned from the above connect
</PRE></CODE>
be aware, that if the JVM is on a remote machine, you should ensure somehow that the jar file is present on that machine. If required, transfer it to the machine's "tmp" directory, and use that folder as path.
(you can use another expecco block for that file transfer, or write a little batch/shell script to do that).

== Java Package Import and Class Access==

The import (loading) of additional required packages is done automatically in the JVM, when one of the package's classes is accessed for the very first time. In other words, when the Java code references a class for the first time, whose package is not yet loaded, it will search for the package along the class path and load it. Thus the above "addToClassPath:" actually does not yet verify or load the package, but only prepare any future "load on demand". This may be a bit dangerous, as failures may be reported much later, when a missing class is actually loaded (so better double check, that all the class pathes are valid, and the corresponding files are present on the system on which the JVM runs).

This following code sample simple references (i.e. accesses) the class "JFrame" from the <CODE>"javax.swing"</CODE> package. The fully specified class name in Java would be <CODE>"javax.swing.JFrame"</CODE>. Note that in Smalltalk code, the dots are replaced by underscores and the full class name is written as a message send to the java bridge handle:
<CODE><PRE>
java javax_swing_JFrame.
</PRE></CODE>

After that call, the JavaVM has loaded the required package(s) and now knows the package <CODE>"javax.swing"</CODE>. It will lookup short form class names in the set of known packages. Now we can access all classes of that package without a need to provide the full class name. For example, if we now want to access the class <CODE>"javax.swing.JButton"</CODE>, it can be done via the class's short name:
<CODE><PRE>
java JButton.
</PRE></CODE>
'''ATTENTION:''' If a classes' short form exists in more than one package on the Java side, then you still have to specify the full name of the class. Otherwise, the first matching class will be taken and that's probably not the one you were looking for!

== Instantiating a Class ==

Object instances are created via the "new"-message, sent to a proxy of a Java class. You can get this proxy as described in the previous section. For example, if we want to create a new instance of a "JFrame" and a "JButton", write:
<CODE><PRE>
frame := java javax_swing_JFrame new.
button := java JButton new.
</PRE></CODE>
The first statement results in a proxy object for the "JFrame" instance (and as a side effect of referring to the class will import the <CODE>"javax.swing"</CODE> package). The second line results in a proxy for a new "JButton" object.

== Calling Instance Methods ==

A method call is done by a message send to a proxy object, where the message is the method name to call. For example, to call the <CODE>"setVisible(boolean isVisible)"</CODE> method on the above JFrame object, we send the following message to that proxy:
<CODE><PRE>
frame setVisible:true.
</PRE></CODE>

As method naming is different in Smalltalk and Java, a dynamic translation is applied when sending messages from Smalltalk code to a remote Java object. Smalltalk has arguments embedded inside parts of a so called "keyword" message, such as in "receiver foo:arg1 bar:arg2", where "foo:bar:" would be the message name, and "arg1", "arg2" be the arguments.

In Java, the message name is a single identifier, and arguments are written in an argument list after the message name: "receiver.fooBar(arg1, arg2)".

When message names are translated, only the very first part of the Smalltalk keyword message is taken ("foo" in the above example), and the remaining parts are simpl ignored. Thus, any of the Smalltalk messages "foo:bar:", "foo:xxxx:" and "foo:_:" (a single underscore as second part) all translate to the same Java message name "foo()".

Therefore, to call a method with more than one argument, like <CODE>"setSize(int width,int height)"</CODE> on a JFrame instance we can write:
<CODE><PRE>
frame setSize:300 _:200.
</PRE></CODE>
but just as well:
<CODE><PRE>
frame setSize:300 anyWord:200.
</PRE></CODE>
or any other selector with "setSize:" as its first component.
The selector translation mechanism simply takes the first part as the Java selector.

In practice, you should take a reasonably descriptive name, such as: "frame setSize:300 height:200" or only the Java name as first part, such as "frame setSize:300 _:200".

For a call of a method with 4 arguments, we could write:
<CODE><PRE>
frame setBounds:100 y:50 width:300 height:200.
</PRE></CODE>
or:
<CODE><PRE>
frame setBounds:100 _:50 _:300 _:200.
</PRE></CODE>

Also here the <CODE>"y: width: height:"</CODE> can be named as you want, but the first part must be "setBounds:".

=== Calling Static Methods ===

Calling a static method on an object is not different from calling non static methods. In most cases you will call a static method not on an object but directly on the class. This is done by using the class object as "receiver" of the message. For example, if we want to call the static method <CODE>"isDefaultLookAndFeelDecorated()"</CODE> of the JFrame class, write:
<CODE><PRE>
java javax_swing_JFrame isDefaultLookAndFeelDecorated.
</PRE></CODE>
or if the package is already known:
<CODE><PRE>
java JFrame isDefaultLookAndFeelDecorated.
</PRE></CODE>

== Accessing Fields ==

As Smalltalk does not support access of an object's fields from the outside (it is fully encapsulated, and access from outside is ONLY allowed via getters/setters), an additional translation mechanism is provided for field access.

Accessing a field of a Java object or a class's static field uses the same syntax as method calls. To access a field, send a message where the message is the field name. To access the field of a class the field must be static.
For example, to get the value of the static field named <CODE>"EXIT_ON_CLOSE"</CODE> of the "JFrame" class, write
<CODE><PRE>
value := java javax_swing_JFrame EXIT_ON_CLOSE.
</PRE></CODE>
or (using short names):
<CODE><PRE>
value := java JFrame EXIT_ON_CLOSE.
</PRE></CODE>
The variable "value" now holds the integer value of the <CODE>"EXIT_ON_CLOSE"</CODE> constant.

Assuming that a "JFrame" object had a field named <CODE>"myField"</CODE>, to access this field, we'd have to write:
<CODE><PRE>
value := frame myField.
</PRE></CODE>
and "value" now holding whatever <CODE>"myField"</CODE> returns. This could be another object reference or any primitive value.

=== Setting Fields ===
To set a field, use a setter-like method call:
<CODE><PRE>
frame myField: newValue.
</PRE></CODE>

=== Name Conflicts ===

In very rare situations, a Java object may contain both a field and a method by the same name.
In this case, the Smalltalk code cannot depend on the dynamic translation mechanism (which actually looks for either a field or method name to match), but instead make it explicit, which operation is wanted:
Use:
<CODE><PRE>
frame getFieldByName:'myField'
</PRE></CODE>
to read a field, and:
<CODE><PRE>
frame setFieldByName:'myField' value:123.
</PRE></CODE>
to write the field.

If there are both fields and methods by the same name, and you use the non-explicit call,
the bridge will always assume that you want to call the getter/setter and perform a method call.
 

== Callbacks from Java ==
Sometimes you may want to execute a piece of Smalltalk code during the execution of the Java code. For example, we may want to install a Smalltalk observer to be notified when a button on a Java GUI was pressed,
or some other callback from a Java framework.

The following code registers a Smalltalk block as a callback for a mouse press event of a button:
<CODE><PRE>
listener := MouseListener new.
listener mousePressed:[ Transcript showCR:'Hello from Java' ].
</PRE></CODE>
The above creates the callback and the listener, which can now be registered on a button:
<CODE><PRE>
button addMouseListener:listener.
</PRE></CODE>
Now, with the press of the button in the Java GUI, the Smalltalk block will be executed and writes <CODE>"Hello from Java"</CODE> tothe Smalltalk console.
Of course, any other (Smalltalk-)action code can be made to run via this mechanism.

But be aware, that the callback is possibly called later (when the elementary action, which installed the code, has already finished long ago). Also, as the Java code execution is not synchronized with any of your expecco action execution, the callback may also be called at any arbutrary time, even at times when no activity at all is executed on the expecco side. If you forget to cleanup, and the Java object is still alive, it may even be called after you have finished your test run (if you keep the java bridge handle around and alive, for example in an expecoo environment variable).

So the Smalltalk callback code should not depend on any particular elementary action to be currently running, but instead in most cases write some information into a shared data container, preferably an instance of "SharedQueue", which is thread safe. Then, some other action (an elementary action) would read-wait and read events from that shared queue.

make sure that your test correctly cleans up any such callbacks afterwards. As a last resort, use the "Shutdown Bridge Connection" menu item, which closes the bridge connection, and thereby - as a side effect - removes any leftover callbacks. It does close the connection, and any remaininf java proxy object handles become invalid, though.

Another example, using an observer could look like:
<CODE><PRE>
observer := java Observer new.
observer update:[:sourceObservable :argument|
argument notNil ifTrue:[ Transcript showCR:('I was notifyed with: ',argument toString) ]
ifFalse:[ Transcript showCR:'I was notifyed and the argument was nil' ].
].
myObservable addObserver:observer.
</PRE></CODE>
When the observable calls <CODE>"notifyObservers"</CODE>, the Smalltalk block will be executed.

== Exceptions in Java ==
Exceptions on the Java side are signalled back to the Smalltalk side and raise a corresponding exception there. However, on the Java side, the call stack which lead to the exception has already been unwound at that time (Java exceptions are not proceedable). So a proceed in the Smalltalk-side exception handler only affects the Smalltalk caller, but may leave the Java side in an undefined state.



== Examples ==

This example creates a JFrame with one button inside. Then a Mouselistener is created and registered on the button. When the button is pressed, the title of the window changes to <CODE>"onPressed"</CODE> and the Transcript shows the message <CODE>"onPressed"</CODE>. When the button is released, the title of the window is changed to <CODE>"onReleased"</CODE> and the Transcript shows <CODE>"onReleased"</CODE>. If the button lost the mouse focus, the bridge will exit (disconnect), and the Java side is terminated.
<CODE><PRE>
|java frame button listener|

"/getting a bridge
java := JAVA::JavaBridge newWithServer.

"/creating a new frame and button object
frame := java javax_swing_JFrame new.
button := java JButton new:'Click'.

"/creating a new mouse listener and adding callback blocks
listener := java MouseListener new.
listener mousePressed:[ Transcript showCR:'onPress'. frame setTitle:'onPressed' ].
listener mouseReleased:[ Transcript showCR:'onReleased'. frame setTitle:'onReleased' ].
listener mouseExited:[ Transcript showCR:'onExited'. java closeBridge. ].

"/register the mouse listener on the button and make the frame with button visible
button addMouseListener:listener.
frame add:button.
frame setSize:300 y:100.
frame setVisible: true.
</PRE></CODE>

=== Simple RMI Call ===
The next example is written in JavaScript syntax. It shows how an RMI host is queried for an RMI object and then the "getHello" method is called on it. The following code is not directly executable: you must replace the path to the compiled MyRemoteObject class with the directory containing the class file, and replace the RMI host name with a real one in your network:
<CODE><PRE>
var java, reg, myRemoteObject, callResult;

// Start a local JavaVM and connect the Communication-Bridge to it
java = JAVA::Java.singletonInstance;

// Add the class path where the description class of the shared RMI object can be found. RMI could also load the class from the server, but then we would need a RMI SecurityManager with download rights
java.bridgeSide.addClassSearchPath("my\added\class\path");

// java.rmi.registry.LocateRegistry gets us the RMI Registry on the host
reg = java.java_rmi_registry_LocateRegistry.getRegistry("rmiHost",4567);

// get the rmi object
myRemoteObject = reg.lookup("myObject");

// get the hello string that was written by the RMI server into the rmi object
callResult = myRemoteObject.getHello();
</PRE></CODE>
The RMI server written in Java:
<CODE><PRE>
RMIServer.java:

import java.rmi.AlreadyBoundException;
import java.rmi.RemoteException;
import java.rmi.registry.LocateRegistry;
import java.rmi.registry.Registry;

public class RMIServer {

public static void
main( String[] args ) throws RemoteException, AlreadyBoundException, InterruptedException {
int port = 4567;

if(args.length > 0)
port = Integer.parseInt(args[0]);

Registry reg = LocateRegistry.createRegistry(port);
reg.bind("myObject", new MyRemoteObject("Hello from RMIServer: "+port));
while(true) {
Thread.sleep(100);
}
}
}
</PRE></CODE>
The implementation of the shared RMI object written in Java:
<CODE><PRE>
MyRemoteObject.java
import java.io.Serializable;
import java.rmi.Remote;

public class MyRemoteObject implements Remote,Serializable {

private static final long serialVersionUID = 1L;

private String hello;

public MyRemoteObject(String hello) {
this.hello = hello;
}

public String getHello(){
return hello;
}
}
</PRE></CODE>



== API ==
===JAVA::Java===
====class protocol====
=====newWithServer=====
* This will start a local JavaVM, running the JavaBridge, and establishes a connection on a random free port.
: A new connected instance of JAVA::Java class is returned.

=====newWithServerForJavaPath:aJavaPathFilename=====
* This is the same as newWithServer but the path to the java executable can be specified. The JavaVM version must be 1.6 or higher to run the JavaBridge.
:: '''aJavaPathFilename''' - must be a instance of Filename
Smalltalk: JAVA::Java newWithServerForJavaPath:('my\path\to\java.executable'asFilename).
JavaScript: JAVA::Java.newWithServerForJavaPath("my\path\to\java.executable".asFilename());

=====newConnectedTo:aHhostString port:aPortNumber withTimeout:aTimeoutSeconds=====
* This is used to connect to a running JavaBridge on the network. The JavaBridge must be started in server mode on the remote host. After connecting a new connected instance of JAVA::Java is returned.
:: '''aHostString''' - the hostname or IP of the remote machine as String
:: '''aPortNumber ''' - the port on which the remote machine is listening as Number
:: '''aTimeoutSeconds''' - a connect timeout in seconds as Number
Smalltalk: JAVA::Java newConnectedTo:'myHostName' port:4567 withTimeout:30.
JavaScript: JAVA::Java.newConnectedTo_port_withTimeout("myHostName",4567,30);

=====newWaitingForConnectOnHost:aListeningAddressString port:aListeningPortNumber withTimeout:aTimeoutSeconds=====
* This is used to wait for incomming connecions of a running JavaBridge on the network. The JavaBridge must be started in client mode on the remote host. After connecting a new connected instance of JAVA::Java is returned.
:: '''deprecated: aListeningAddressString''' - no longer used. Can be nil.
:: '''aListeningPortNumber ''' - the port on which to listen for incomming connections as Number
:: '''aTimeoutSeconds''' - a connect timeout in seconds as Number, If nil it will wait endless.

=====singletonInstance=====
* This will call newWithServer for the first time and then always returns the same connected JAVA::Java instance until the connection was closed, then a new connected instance is returned.

=====exitAllInstances=====
* This will close all instances of JAVA::Java.

====instance protocol====
=====addJarByPath:aPath=====
* Adds a jar to the class path of the running JavaVM. If the jar depends on other jars or librarys you have to add them too.
:: '''aPath''' - the path to the jar file as String.

=====addLibraryByPath:aPath=====
* Adds a library to the library path of the running JavaVM. If the library depends on other librarys you have to add them too.
:: '''aPath''' - the path to the library file as String.

=====isConnected=====
* Tests if a connection is still established.
:: '''return:''' - true if the connection is still established, else false.

=====isAlive=====
* Tests if a connection is still responding.
:: '''return:''' - true if the connection is still alive, else false. Does a message round trip.

=====closeBridge=====
* This will close the bridge connection. Depending on in which mode the JavaBridge was started, the JavaVM is also closed (-keepAlive startparameter not set).

=====exit=====
* Same as closeBridge.

== See Also==
The [[DOT NET Interface Library| DOTNET Interface Plugin & Library]], which implements a likewise interface for .NET applications/libraries. 
[[Java Interface Library v2 | Version 2 of the Java Interface Library]]

<hr>
Back to [[Plugins]] 
Back to [[OnlineDocumentation#Library and Plugin Overview|Online Documentation]].

Java Interface Library v2

2016-06-01T10:45:06Z

Javogel: /* General */

== Introduction ==

This article discusses version 2 of the Java Bridge (which is as of expecco v2.9 still experimental).
The article for version 1 can be found [[Java Interface Library | here]].

The Java Interface library ("Java Bridge") is used to interact with Java objects inside an external Java Virtual Machine (JVM).

The access to Java objects, classes and programs is done via a framework called "''Java-Bridge''", which is similar in operation to the [[DOT NET Interface Library| dotNET bridge]]. This framework implements transparent forwarding of method (virtual function) calls to Java objects, which exist in a local or remote Java Virtual Machine (JVM). Also, return values, callBacks and exception information are passed back from the Java program to expecco. This is done by a proxy-object mechanism, which catches all function calls, wraps the arguments, sends a datagram to the other bridge side, awaits the reply and returns the result to the original caller. Thus, remote procedure calls are almost completely transparent to the Smalltalk/JavaScript code inside expecco. In your elementary code, you can write remote function calls as if they were to local objects.

Notice that this document describes the low level framework, which implements the bridge communication. A much easier to use high level interface (called "Groovy Blocks") exists and should normally be used, if you need access to a java application's internals during testing.
Please take a look at
[[Expecco_API#Groovy_Elementary_Blocks | "Groovy Block API"]]
and [[Testing Java Applications using Groovy blocks/en | "Testing Java Applications using Groovy blocks"]].

== Architecture ==

On the expecco side, the bridge consists of a number of Proxy objects,
which behave like regular Smalltalk objects as seen from elementary expecco code.
However, instead of performing an action when one of their methods (virtual functions) is called,
they send a message over a socket connection to the Java VM (actually: to a bridge software inside the
Java application) which decodes the message and sends it to the destination Java object.
The same is done in reverse direction with the return value.

+---------------------+ +----------+ +----------------+ +----------------+ +---------+
| | | | | | | | | Java |
| expecco |---->| Proxy |---->| Bridge |==>>==| Bridge |---->| Object |
| (elementary code) |<----| |<----| (expecco side) |==<<==| (Java side) |<----| |
+---------------------+ +----------+ +----------------+ +----------------+ +---------+

This setup allows for transparent communication with objects inside a local or remote Java VM. This may be either utility functions which happen to be convenient for the test application (for example: file parsing, syntax analysis, protocol implementaitons or access to specific hardware via driver libraries), or the tested application in the system under test itself.

Especially, it allows for the objects of the tested application to be looked into, manipulated and for functions of it or underlying frameworks to be called.

For expecco code, we tried to make this as transparent as possible, however there are a few exceptions, when function names need to be translated (for example, because the function naming syntax is different) or due to the fact that for some operations no corresponding name exists in Smalltalk (array access, for example).

Of course, multiple such connections can coexist and be served/handled in parallel. This enables an expecco test suite to communicate with both sides of a tested client-server Java application, for example.

Notice that a similar mechanism is used in expecco to communicate with DOTNET, Qt (C++) and C applications.

 

== Activating the new Java Bridge ==
To activate the new bridge in expecco navigate to <CODE>Extras -> Settings -> Plugins -> Java Bridge</CODE> and tick the '''Use new Bridge (experimental)''' checkbox.
[[Datei:ActivateNewJavaBridge.png]]

'''Attention:''' Ticking the checkbox will terminate all currently active Bridge connections due to incompatibilities between the new and the old version.

== Initializing / Releasing the Bridge ==

Before any communication can take place between expecco and any Java object, the Java side of the bridge has to be started, and a communication has to be established.
In expecco, all of the bridge classes are found in the <CODE>JAVA</CODE> namespace.

The main interface class is "<CODE>Java</CODE>", in the "<CODE>JAVA</CODE>" namespace:
<CODE><PRE>
java := JAVA::Java newWithServer.
</PRE></CODE>
or (in JavaScript):
<CODE><PRE>
java = JAVA::Java.newWithServer();
</PRE></CODE>

This starts the Java-side of the bridge (actually executes java as a background command) on the local machine, and establishes a connection to that JVM.

The bridge connection should be closed, if the bridge is no longer needed. Release the bridge with:
<CODE><PRE>
java.closeBridge();
</PRE></CODE>
which terminates the connection.

=== Start and Connect to a Remote Machine ===
The above started a Java VM and connected to it. Alternatively, you may want to connect to an already running Java program (typically, your system under test).
In order for your program to be reachable, it must allow for the bridge to connect to it via a special bridge-connection, which is a socket connection. For this, it must execute the server code found in the "JavaBridge.jar" file. To pass [[#Startup Parameters| parameters]] you will typically start it from a command line or a little shell/batch script.

Call (on the shell/cmd level):
$ java -jar <PATH_TO_JAVABRIDGE.JAR> <PARAMETERS>

The "JavaBridge.jar" file is found in the installation directory of expecco at:
\exept\expecco\packages\exept\bridgeFramework\javaBridge\javaBin\JavaBridge.jar

The Javabridge code allows for either side to initiate the connection - i.e. it can be run in server mode,
where it awaits an incoming connection, or in client mode, where it actively initiates a connection.
After connection establishment, there is no difference in the operation of the bridge, however depending on the setup of your network infrastructure, especially firewalls, either mechanism may be easier to be used.

Assuming that the bridge is already running on the remote machine as server (default),
use <CODE>newConnectedTo:port:withTimeout:</CODE> to connect to it from the expecco side:
java := JAVA::Java newConnectedTo:'myHost' port:4567 withTimeout:30.
This will initiate the connection setup from the expecco side.

Alternatively, if started in client mode use <CODE>newWaitingForConnectOnHost:port:withTimeout:</CODE>:
java := JAVA::Java newWaitingForConnectOnHost:'localhost' port:4567 withTimeout:30.
which will open a port on the expecco side, and wait until the Java side connects to it.
[[#JAVA::Java|For more details see API]]

====Startup Parameters====
You can use any parameter in any order.
If no parameter is used then the bridge listenes on port 14014 in server mode without keepAlive.
;<code>-help</code>
* Shows the help

;<code>-ip <aHostnameOrIP></code>
* In client mode this specifies the ip or hostname to connect to. In server mode this specifies the ip or hostname to bind to.

;<code>-port <aPortNumber> </code>
* In client mode this specifies the port to connect to. In server mode this specifies the listening port.

;<code>-asClient</code>
* The bridge will start in client mode. If not set the bridge is started in server mode.

;<code>-keepAlive</code>
* By setting this flag the bridge will not exit after the connection has closed and starts to connect or listen again. Otherwise, it will run for a single connection session only.

== Loading Applications (from the expecco side) ==

Normally, you would start your application with the required command line arguments and include the javabridge as jar there. However, in some situations, it may be required to dynamically load other jars into the connected Java VM.
By accessing a classloader, additional classes, or applications as contained in JAR files can be loaded from the expecco side.

This can be used to add a JAR file to the classloader:
<CODE><PRE>
java loadJarByPath:'pathToJarFile'. "/ assuming "java" is a handle as returned from the above connect
</PRE></CODE>

or, if the JAR file is loaded in memory:
<CODE><PRE>
java loadJar:jarByteArray. "/ where "jarByteArray" is a ByteArray containing the JAR file
</PRE></CODE>

If the JVM is on a remote machine, the path is resolved on the expecco side and the JAR will be transferred to the remote side.

Should transferring the JAR be too much overhead, an additional mechanism is provided:
<CODE><PRE>
java loadExtension:'pathToJarFile'.
</PRE></CODE>
this will cache the JAR file on the bridge side and eliminate the overhead of subsequent invocations.

== Java Class Access ==

This following code sample simply references (i.e. accesses) the class "JFrame" from the <CODE>"javax.swing"</CODE> package. The fully specified class name in Java would be <CODE>"javax.swing.JFrame"</CODE>:
<CODE><PRE>
java getJavaClass:'javax.swing.JFrame'
</PRE></CODE>

Or, if you want to load multiple classes:
<CODE><PRE>
java import:'javax.swing.JFrame' import:'javax.swing.JButton'
do:[:jFrame :jButton | "do something with JButton and JFrame" ].
</PRE></CODE>

v2 also supports dynamic compilation of java source code:
<CODE><PRE>
java getJavaClass:'className' fromSource:'classSource'. "/ where classSource is a String containing valid java source code
</PRE></CODE>

and loading precompiled java bytecode:
<CODE><PRE>
java getJavaClass:'className' fromByteCode:byteCode. "/ where byteCode is a ByteArray containing valid java bytecode
</PRE></CODE>

[[#Remote Dynamic Code Injection | for details see Remote Dynamic Code Injection]]

== Instantiating a Class ==

Object instances are created via the "new"-message, sent to a proxy of a Java class. You can get this proxy as described in the previous section. For example, if we want to create a new instance of a "JFrame" and a "JButton", write:
<CODE><PRE>
frame := java getJavaClass:'javax.swing.JFrame' new.
button := java getJavaClass:'javax.swing.JButton' new.
</PRE></CODE>
The first statement results in a proxy object for the "JFrame" instance. The second line results in a proxy for a new "JButton" object.

== Calling Instance Methods ==

A method call is done by a message send to a proxy object, where the message is the method name to call. For example, to call the <CODE>"setVisible(boolean isVisible)"</CODE> method on the above JFrame object, we send the following message to that proxy:
<CODE><PRE>
frame setVisible:true.
</PRE></CODE>

As method naming is different in Smalltalk and Java, a dynamic translation is applied when sending messages from Smalltalk code to a remote Java object. Smalltalk has arguments embedded inside parts of a so called "keyword" message, such as in "receiver foo:arg1 bar:arg2", where "foo:bar:" would be the message name, and "arg1", "arg2" be the arguments.

In Java, the message name is a single identifier, and arguments are written in an argument list after the message name: "receiver.fooBar(arg1, arg2)".

When message names are translated, only the very first part of the Smalltalk keyword message is taken ("foo" in the above example), and the remaining parts are simpl ignored. Thus, any of the Smalltalk messages "foo:bar:", "foo:xxxx:" and "foo:_:" (a single underscore as second part) all translate to the same Java message name "foo()".

Therefore, to call a method with more than one argument, like <CODE>"setSize(int width,int height)"</CODE> on a JFrame instance we can write:
<CODE><PRE>
frame setSize:300 _:200.
</PRE></CODE>
but just as well:
<CODE><PRE>
frame setSize:300 anyWord:200.
</PRE></CODE>
or any other selector with "setSize:" as its first component.
The selector translation mechanism simply takes the first part as the Java selector.

In practice, you should take a reasonably descriptive name, such as: "frame setSize:300 height:200" or only the Java name as first part, such as "frame setSize:300 _:200".

For a call of a method with 4 arguments, we could write:
<CODE><PRE>
frame setBounds:100 y:50 width:300 height:200.
</PRE></CODE>
or:
<CODE><PRE>
frame setBounds:100 _:50 _:300 _:200.
</PRE></CODE>

Also here the <CODE>"y: width: height:"</CODE> can be named as you want, but the first part must be "setBounds:".

=== Calling Static Methods ===

Calling a static method on an object is not different from calling non static methods. In most cases you will call a static method not on an object but directly on the class. This is done by using the class object as "receiver" of the message. For example, if we want to call the static method <CODE>"isDefaultLookAndFeelDecorated()"</CODE> of the JFrame class, write:
<CODE><PRE>
java getJavaClass:'javax.swing.JFrame' isDefaultLookAndFeelDecorated.
</PRE></CODE>

== Accessing Fields ==

As Smalltalk does not support access of an object's fields from the outside (it is fully encapsulated, and access from outside is ONLY allowed via getters/setters), an additional translation mechanism is provided for field access.

Accessing a field of a Java object or a class's static field uses the same syntax as method calls. To access a field, send a message where the message is the field name. To access the field of a class the field must be static.
For example, to get the value of the static field named <CODE>"EXIT_ON_CLOSE"</CODE> of the "JFrame" class, write
<CODE><PRE>
value := java getJavaClass:'javax.swing.JFrame' EXIT_ON_CLOSE.
</PRE></CODE>
The variable "value" now holds the integer value of the <CODE>"EXIT_ON_CLOSE"</CODE> constant.

Assuming that a "JFrame" object had a field named <CODE>"myField"</CODE>, to access this field, we'd have to write:
<CODE><PRE>
value := frame myField.
</PRE></CODE>
and "value" now holding whatever <CODE>"myField"</CODE> returns. This could be another object reference or any primitive value.

=== Setting Fields ===
To set a field, use a setter-like method call:
<CODE><PRE>
frame myField: newValue.
</PRE></CODE>

=== Name Conflicts ===

In very rare situations, a Java object may contain both a field and a method by the same name.
In this case, the Smalltalk code cannot depend on the dynamic translation mechanism (which actually looks for either a field or method name to match), but instead make it explicit, which operation is wanted:
Use:
<CODE><PRE>
frame getFieldByName:'myField'
</PRE></CODE>
to read a field, and:
<CODE><PRE>
frame setFieldByName:'myField' value:123.
</PRE></CODE>
to write the field.

If there are both fields and methods by the same name, and you use the non-explicit call,
the bridge will always assume that you want to call the getter/setter and perform a method call.
 

== Arrays ==

=== Passing Smalltalk Collections to Java ===

Smalltalk collections can now be directly passed to Java with a few limitations:
* The identity of the Smalltalk collections will not be preserved. passing the same collection to java multiple times will result in multiple instances of the same array on the java side. (to bypass this instantiate a new java array)
* Smalltalk collections need to be explicitly converted to the correct type (e.g. a <CODE>SignedIntegerArray</CODE> on the smalltalk side matches an <CODE>int</CODE>-Array on the java side)

=== Instantiating Arrays ===

The new bridge supports instantiation of arrays (whereas previously reflection had to be used to instantiate arrays from the smalltalk side).
There are two ways an array can be instantiated:

<CODE><PRE>
intArray := (java getJavaClass:'int[]') new:#[ 1 2 3 4 5 ] asSignedIntegerArray. "/ instantiates a new array of type "int" with the contents "1, 2, 3, 4, 5"
</PRE></CODE>

<CODE><PRE>
intArray := (java getJavaClass:'int[]') new:10. "/ instantiates a new empty array of type "int" with 10 elements.
</PRE></CODE>

=== Accessing Arrays ===

To achieve better performance, arrays of primitive types smaller than a certain size have their contents cached on the smalltalk side:
<CODE><PRE>
intArray contents at:1. "/ this will access the first element of the cached contents.
</PRE></CODE>

large arrays are not serialized immediately. large arrays will be serialized when <CODE>contents</CODE> is called the first time.

'''Attention:''' Java arrays are not immutable. changes to an array are not reflected in the cached contents. if an array has been updated, call <CODE>refresh</CODE> on the array to update the cache. arrays will not be updated automatically.

<CODE><PRE>
shortArray := (java getJavaClass:'short[]') new:10. "/ new empty "short" array with 10 elements

"/ copy the contents of the smalltalk collection to the newly instantiated short array
(java getJavaClass:'java.lang.System') arraycopy:(#[ 1 2 3 ] asSignedWordArray) srcPos:0 dest:shortArray destPos:0 length:3.

shortArray at:0. "/ will reflect the changes made to the array

shortArray contents at:1. "/ will still return 0 because the cached contents have not been updated.

shortArray refresh. "/ update the cached contents

shortArray contents at:1. "/ will now correctly reflect the changes made to the array
</PRE></CODE>

== Asynchronous Communication ==

In the new Bridge, everything can be done asynchronously. This is achieved via the <CODE>asyncDo:aBlock</CODE> method.
Every request sent to the Bridge inside of aBlock will immediately return a lazy value.
This lazy value will block upon access until the actual result is received from the java side.
The order of execution is guaranteed to be the same on the java side as on the smalltalk side.

Example:
<CODE><PRE>
java asyncDo:[
lazyInteger := (java getJavaClass:'java.lang.Integer') new:40. "/ this will return immediately
].
actualInteger := lazyInteger value. "/ this will block until the result of the previous call is available
</PRE></CODE>

== Callbacks from Java ==
Sometimes you may want to execute a piece of Smalltalk code during the execution of the Java code. For example, we may want to install a Smalltalk observer to be notified when a button on a Java GUI was pressed,
or some other callback from a Java framework.

The following code registers a Smalltalk block as a callback for a mouse press event of a button:
<CODE><PRE>
listener := MouseListener new.
listener implementMethod:'mousePressed' as:[ Transcript showCR:'Hello from Java' ].
</PRE></CODE>
The above creates the callback and the listener, which can now be registered on a button:
<CODE><PRE>
button addMouseListener:listener.
</PRE></CODE>
Now, with the press of the button in the Java GUI, the Smalltalk block will be executed and writes <CODE>"Hello from Java"</CODE> to the Smalltalk console.
Of course, any other (Smalltalk-)action code can be made to run via this mechanism.

But be aware, that the callback is possibly called later (when the elementary action, which installed the code, has already finished long ago). Also, as the Java code execution is not synchronized with any of your expecco action execution, the callback may also be called at any arbutrary time, even at times when no activity at all is executed on the expecco side. If you forget to cleanup, and the Java object is still alive, it may even be called after you have finished your test run (if you keep the java bridge handle around and alive, for example in an expecoo environment variable).

So the Smalltalk callback code should not depend on any particular elementary action to be currently running, but instead in most cases write some information into a shared data container, preferably an instance of "SharedQueue", which is thread safe. Then, some other action (an elementary action) would read-wait and read events from that shared queue.

make sure that your test correctly cleans up any such callbacks afterwards. As a last resort, use the "Shutdown Bridge Connection" menu item, which closes the bridge connection, and thereby - as a side effect - removes any leftover callbacks. It does close the connection, and any remaining java proxy object handles become invalid, though.

Another example, using an observer could look like:
<CODE><PRE>
observer := java Observer new.
observer implementMethod:'update'
as:[:sourceObservable :argument|
argument notNil ifTrue:[ Transcript showCR:('I was notifyed with: ',argument toString) ]
ifFalse:[ Transcript showCR:'I was notifyed and the argument was nil' ].
].
myObservable addObserver:observer.
</PRE></CODE>
When the observable calls <CODE>"notifyObservers"</CODE>, the Smalltalk block will be executed.

== Exceptions in Java ==
Exceptions on the Java side are signalled back to the Smalltalk side and raise a corresponding exception there. However, on the Java side, the call stack which lead to the exception has already been unwound at that time (Java exceptions are not proceedable). So a proceed in the Smalltalk-side exception handler only affects the Smalltalk caller, but may leave the Java side in an undefined state.

== Remote Dynamic Code Injection ==
Sometimes we might want to execute code without the overhead of many rpc-messages being sent over the bridge, especially if we want to do something time critical, or want to make execution time measurements.
For this, it is possible to load a class at runtime into the JavaVM. The code of the class will first be sent to the JavaVM, which will compile and load the generated byte code. Then, the class can be accessed via the bridge just like any other preloaded class.

The following example specifies the class code in a smalltalk string and inject the code into the JavaVM. Then an instance of that new class will be instantiated and finally a method of the object instance will be invoked:
<CODE><PRE>
classCode := '
package myPackage.test;

import java.awt.BorderLayout;
import java.awt.event.MouseAdapter;
import java.awt.event.MouseEvent;
import java.util.Calendar;

import javax.swing.JButton;
import javax.swing.JFrame;
import javax.swing.JLabel;;

public class MyInjectedClass {
public void createSampleApp(){
JFrame frame=new JFrame("Hello im injected");
frame.setLayout(new BorderLayout());
JButton button=new JButton("click me");
final JLabel label=new JLabel("Text");
button.addMouseListener(new MouseAdapter() {

@Override
public void mouseClicked(MouseEvent e) {
label.setText(Calendar.getInstance().getTime().toString());
}
});
frame.add(label,BorderLayout.NORTH);
frame.add(button,BorderLayout.SOUTH);
frame.setSize(300, 300);
frame.setVisible(true);
}
}
'.
classObject := java getJavaClass:'myPackage.test.MyInjectedClass' fromSource:classCode.
classObject new createSampleApp.
</PRE></CODE>
After the code has been injected, a new instance of <CODE>"MyInjectedClass"</CODE> is created and the <CODE>"createSampleApp"</CODE> method is called. Because the example implements a GUI, a Java window will open, containing a label and a button. Clicking the button displays the current time in the label.



=== Code Sources for Class injection ===
There are 3 possible types of class code sources which we can use to inject the code. In the examples before we directly used a simple <CODE>"String"</CODE> in the smalltalk code as a code source. We also can use a <CODE>"*.java"</CODE> file as source. Just read the content of the file into a string and use it as in the previous examples.

To inject a <CODE>"*.class"</CODE> file use the following code:
<pre>
java getJavaClass:'the.class.name' fromByteCode:classCode.
</pre>

== Examples ==

This example creates a JFrame with one button inside. Then a Mouselistener is created and registered on the button. When the button is pressed, the title of the window changes to <CODE>"onPressed"</CODE> and the Transcript shows the message <CODE>"onPressed"</CODE>. When the button is released, the title of the window is changed to <CODE>"onReleased"</CODE> and the Transcript shows <CODE>"onReleased"</CODE>. If the button lost the mouse focus, the bridge will exit (disconnect), and the Java side is terminated.
<CODE><PRE>
|java frame button listener|

"/getting a bridge
java := JAVA::JavaBridge newWithServer.

"/creating a new frame and button object
frame := java getJavaClass:'javax.swing.JFrame' new.
button := java JButton new:'Click'.

"/creating a new mouse listener and adding callback blocks
listener := java MouseListener new.

listener implementMethod:'mousePressed' as:[ Transcript showCR:'onPress'. frame setTitle:'onPressed' ].
listener implementMethod:'mouseReleased' as:[ Transcript showCR:'onReleased'. frame setTitle:'onReleased' ].
listener implementMethod:'mouseExited' as:[ Transcript showCR:'onExited'. java closeBridge. ].

"/register the mouse listener on the button and make the frame with button visible
button addMouseListener:listener.
frame add:button.
frame setSize:300 y:100.
frame setVisible: true.
</PRE></CODE>



==Differences between v1 and v2==
===General===
* A Java Bridge instance no longer requires multiple tcp ports to be open. This simplifies connection through ssh tunnels and firewalls.
* The identity of strings and primitve wrappers can now be preserved. (see [[#boxedDo:aBlock | boxedDo]])
* Arrays of primitive types are serialized. (see [[#Arrays | Arrays]])
* Every request to the java side can now be done asynchronously. (see [[#Asynchronous Communication | Asynchronous Communication]])

===Loading Applications===
* '''addJarByPath:''' and '''addToClassPath:''' are still supported but have been deprecated. use '''loadJar:''', '''loadJarByPath:''' and '''loadExtension:''' instead. The new methods no longer require the jar or library to be present on the remote machine.

[[Java Interface Library#Loading Applications (from the expecco side) | v1]] [[#Loading Applications (from the expecco side) | v2]]

===Java Class Access===
* Sending the fully qualified name with instances of "." replaced by "_" to the bridge handle is still supported, but not recommended.
* A new method '''getJavaClass:''' has been introduced (also available for v1 since expecco v2.9). This solves the side effects of "_" being a legal character in class names.

[[Java Interface Library#Java Package Import and Class Access | v1]] [[#Java Class Access | v2]]
===Callbacks from Java===
* A new method '''implementMethod:as:''' has been introduced to assign callback blocks to method names. The old way is still supported.

[[Java Interface Library#Callbacks from Java | v1]] [[#Callbacks from Java | v2]]

===Remote Dynamic Code Injection===
* Code injection was problematic in v1 and has now been re-implemented in v2.

[[#Remote Dynamic Code Injection | v2]]

== API ==
===JAVA::Java===
====class protocol====
=====newWithServer=====
* This will start a local JavaVM, running the JavaBridge, and establishes a connection on a random free port.
: A new connected instance of JAVA::Java class is returned.

=====newWithServerForJavaPath:aJavaPathFilename=====
* This is the same as newWithServer but the path to the java executable can be specified. The JavaVM version must be 1.6 or higher to run the JavaBridge.
:: '''aJavaPathFilename''' - must be a instance of Filename
Smalltalk: JAVA::Java newWithServerForJavaPath:('my\path\to\java.executable'asFilename).
JavaScript: JAVA::Java.newWithServerForJavaPath("my\path\to\java.executable".asFilename());

=====newConnectedTo:aHhostString port:aPortNumber withTimeout:aTimeoutSeconds=====
* This is used to connect to a running JavaBridge on the network. The JavaBridge must be started in server mode on the remote host. After connecting a new connected instance of JAVA::Java is returned.
:: '''aHostString''' - the hostname or IP of the remote machine as String
:: '''aPortNumber ''' - the port on which the remote machine is listening as Number
:: '''aTimeoutSeconds''' - a connect timeout in seconds as Number
Smalltalk: JAVA::Java newConnectedTo:'myHostName' port:4567 withTimeout:30.
JavaScript: JAVA::Java.newConnectedTo_port_withTimeout("myHostName",4567,30);

=====newWaitingForConnectOnHost:aListeningAddressString port:aListeningPortNumber withTimeout:aTimeoutSeconds=====
* This is used to wait for incomming connecions of a running JavaBridge on the network. The JavaBridge must be started in client mode on the remote host. After connecting a new connected instance of JAVA::Java is returned.
:: '''deprecated: aListeningAddressString''' - no longer used. Can be nil.
:: '''aListeningPortNumber ''' - the port on which to listen for incomming connections as Number
:: '''aTimeoutSeconds''' - a connect timeout in seconds as Number, If nil it will wait endless.

=====singletonInstance=====
* This will call newWithServer for the first time and then always returns the same connected JAVA::Java instance until the connection was closed, then a new connected instance is returned.

=====exitAllInstances=====
* This will close all instances of JAVA::Java.

====instance protocol====
=====loadJarByPath:aPath=====
* Adds a jar to the running JavaVM. If the jar depends on other jars or libraries you have to add them too.
:: '''aPath''' - the path to the jar file as String.

=====loadJar:aByteArray=====
* Adds a jar to the running JavaVM. If the jar depends on other jars or libraries you have to add them too.
:: '''aByteArrays''' - a ByteArray containing the JAR file.

=====loadExtension:aPath=====
* Adds a jar to the running JavaVM and caches it for subsequent usages. If the jar depends on other jars you have to add them too.
:: '''aPath''' - the path to the jar file as String.

=====boxedDo:aBlock=====
* Any autoboxed values in aBlock returned from the JavaVM are preserved as such. By default autoboxed values are automatically unboxed. This way, the identity of such objects is preserved.

=====isConnected=====
* Tests if a connection is still established.
:: '''return:''' - true if the connection is still established, else false.

=====isAlive=====
* Tests if a connection is still responding.
:: '''return:''' - true if the connection is still alive, else false. Does a message round trip.

=====closeBridge=====
* This will close the bridge connection. Depending on in which mode the JavaBridge was started, the JavaVM is also closed (-keepAlive startparameter not set).

=====exit=====
* Same as closeBridge.

== See Also==
The [[DOT NET Interface Library| DOTNET Interface Plugin & Library]], which implements a likewise interface for .NET applications/libraries.
 
[[Java Interface Library | Version 1 of the Java Interface Library]]
<hr>
Back to [[Plugins]]

Java Interface Library v2

2016-06-01T10:43:32Z

Javogel: /* See Also */

== Introduction ==

This article discusses version 2 of the Java Bridge (which is as of expecco v2.9 still experimental).
The article for version 1 can be found [[Java Interface Library | here]].

The Java Interface library ("Java Bridge") is used to interact with Java objects inside an external Java Virtual Machine (JVM).

The access to Java objects, classes and programs is done via a framework called "''Java-Bridge''", which is similar in operation to the [[DOT NET Interface Library| dotNET bridge]]. This framework implements transparent forwarding of method (virtual function) calls to Java objects, which exist in a local or remote Java Virtual Machine (JVM). Also, return values, callBacks and exception information are passed back from the Java program to expecco. This is done by a proxy-object mechanism, which catches all function calls, wraps the arguments, sends a datagram to the other bridge side, awaits the reply and returns the result to the original caller. Thus, remote procedure calls are almost completely transparent to the Smalltalk/JavaScript code inside expecco. In your elementary code, you can write remote function calls as if they were to local objects.

Notice that this document describes the low level framework, which implements the bridge communication. A much easier to use high level interface (called "Groovy Blocks") exists and should normally be used, if you need access to a java application's internals during testing.
Please take a look at
[[Expecco_API#Groovy_Elementary_Blocks | "Groovy Block API"]]
and [[Testing Java Applications using Groovy blocks/en | "Testing Java Applications using Groovy blocks"]].

== Architecture ==

On the expecco side, the bridge consists of a number of Proxy objects,
which behave like regular Smalltalk objects as seen from elementary expecco code.
However, instead of performing an action when one of their methods (virtual functions) is called,
they send a message over a socket connection to the Java VM (actually: to a bridge software inside the
Java application) which decodes the message and sends it to the destination Java object.
The same is done in reverse direction with the return value.

+---------------------+ +----------+ +----------------+ +----------------+ +---------+
| | | | | | | | | Java |
| expecco |---->| Proxy |---->| Bridge |==>>==| Bridge |---->| Object |
| (elementary code) |<----| |<----| (expecco side) |==<<==| (Java side) |<----| |
+---------------------+ +----------+ +----------------+ +----------------+ +---------+

This setup allows for transparent communication with objects inside a local or remote Java VM. This may be either utility functions which happen to be convenient for the test application (for example: file parsing, syntax analysis, protocol implementaitons or access to specific hardware via driver libraries), or the tested application in the system under test itself.

Especially, it allows for the objects of the tested application to be looked into, manipulated and for functions of it or underlying frameworks to be called.

For expecco code, we tried to make this as transparent as possible, however there are a few exceptions, when function names need to be translated (for example, because the function naming syntax is different) or due to the fact that for some operations no corresponding name exists in Smalltalk (array access, for example).

Of course, multiple such connections can coexist and be served/handled in parallel. This enables an expecco test suite to communicate with both sides of a tested client-server Java application, for example.

Notice that a similar mechanism is used in expecco to communicate with DOTNET, Qt (C++) and C applications.

 

== Activating the new Java Bridge ==
To activate the new bridge in expecco navigate to <CODE>Extras -> Settings -> Plugins -> Java Bridge</CODE> and tick the '''Use new Bridge (experimental)''' checkbox.
[[Datei:ActivateNewJavaBridge.png]]

'''Attention:''' Ticking the checkbox will terminate all currently active Bridge connections due to incompatibilities between the new and the old version.

== Initializing / Releasing the Bridge ==

Before any communication can take place between expecco and any Java object, the Java side of the bridge has to be started, and a communication has to be established.
In expecco, all of the bridge classes are found in the <CODE>JAVA</CODE> namespace.

The main interface class is "<CODE>Java</CODE>", in the "<CODE>JAVA</CODE>" namespace:
<CODE><PRE>
java := JAVA::Java newWithServer.
</PRE></CODE>
or (in JavaScript):
<CODE><PRE>
java = JAVA::Java.newWithServer();
</PRE></CODE>

This starts the Java-side of the bridge (actually executes java as a background command) on the local machine, and establishes a connection to that JVM.

The bridge connection should be closed, if the bridge is no longer needed. Release the bridge with:
<CODE><PRE>
java.closeBridge();
</PRE></CODE>
which terminates the connection.

=== Start and Connect to a Remote Machine ===
The above started a Java VM and connected to it. Alternatively, you may want to connect to an already running Java program (typically, your system under test).
In order for your program to be reachable, it must allow for the bridge to connect to it via a special bridge-connection, which is a socket connection. For this, it must execute the server code found in the "JavaBridge.jar" file. To pass [[#Startup Parameters| parameters]] you will typically start it from a command line or a little shell/batch script.

Call (on the shell/cmd level):
$ java -jar <PATH_TO_JAVABRIDGE.JAR> <PARAMETERS>

The "JavaBridge.jar" file is found in the installation directory of expecco at:
\exept\expecco\packages\exept\bridgeFramework\javaBridge\javaBin\JavaBridge.jar

The Javabridge code allows for either side to initiate the connection - i.e. it can be run in server mode,
where it awaits an incoming connection, or in client mode, where it actively initiates a connection.
After connection establishment, there is no difference in the operation of the bridge, however depending on the setup of your network infrastructure, especially firewalls, either mechanism may be easier to be used.

Assuming that the bridge is already running on the remote machine as server (default),
use <CODE>newConnectedTo:port:withTimeout:</CODE> to connect to it from the expecco side:
java := JAVA::Java newConnectedTo:'myHost' port:4567 withTimeout:30.
This will initiate the connection setup from the expecco side.

Alternatively, if started in client mode use <CODE>newWaitingForConnectOnHost:port:withTimeout:</CODE>:
java := JAVA::Java newWaitingForConnectOnHost:'localhost' port:4567 withTimeout:30.
which will open a port on the expecco side, and wait until the Java side connects to it.
[[#JAVA::Java|For more details see API]]

====Startup Parameters====
You can use any parameter in any order.
If no parameter is used then the bridge listenes on port 14014 in server mode without keepAlive.
;<code>-help</code>
* Shows the help

;<code>-ip <aHostnameOrIP></code>
* In client mode this specifies the ip or hostname to connect to. In server mode this specifies the ip or hostname to bind to.

;<code>-port <aPortNumber> </code>
* In client mode this specifies the port to connect to. In server mode this specifies the listening port.

;<code>-asClient</code>
* The bridge will start in client mode. If not set the bridge is started in server mode.

;<code>-keepAlive</code>
* By setting this flag the bridge will not exit after the connection has closed and starts to connect or listen again. Otherwise, it will run for a single connection session only.

== Loading Applications (from the expecco side) ==

Normally, you would start your application with the required command line arguments and include the javabridge as jar there. However, in some situations, it may be required to dynamically load other jars into the connected Java VM.
By accessing a classloader, additional classes, or applications as contained in JAR files can be loaded from the expecco side.

This can be used to add a JAR file to the classloader:
<CODE><PRE>
java loadJarByPath:'pathToJarFile'. "/ assuming "java" is a handle as returned from the above connect
</PRE></CODE>

or, if the JAR file is loaded in memory:
<CODE><PRE>
java loadJar:jarByteArray. "/ where "jarByteArray" is a ByteArray containing the JAR file
</PRE></CODE>

If the JVM is on a remote machine, the path is resolved on the expecco side and the JAR will be transferred to the remote side.

Should transferring the JAR be too much overhead, an additional mechanism is provided:
<CODE><PRE>
java loadExtension:'pathToJarFile'.
</PRE></CODE>
this will cache the JAR file on the bridge side and eliminate the overhead of subsequent invocations.

== Java Class Access ==

This following code sample simply references (i.e. accesses) the class "JFrame" from the <CODE>"javax.swing"</CODE> package. The fully specified class name in Java would be <CODE>"javax.swing.JFrame"</CODE>:
<CODE><PRE>
java getJavaClass:'javax.swing.JFrame'
</PRE></CODE>

Or, if you want to load multiple classes:
<CODE><PRE>
java import:'javax.swing.JFrame' import:'javax.swing.JButton'
do:[:jFrame :jButton | "do something with JButton and JFrame" ].
</PRE></CODE>

v2 also supports dynamic compilation of java source code:
<CODE><PRE>
java getJavaClass:'className' fromSource:'classSource'. "/ where classSource is a String containing valid java source code
</PRE></CODE>

and loading precompiled java bytecode:
<CODE><PRE>
java getJavaClass:'className' fromByteCode:byteCode. "/ where byteCode is a ByteArray containing valid java bytecode
</PRE></CODE>

[[#Remote Dynamic Code Injection | for details see Remote Dynamic Code Injection]]

== Instantiating a Class ==

Object instances are created via the "new"-message, sent to a proxy of a Java class. You can get this proxy as described in the previous section. For example, if we want to create a new instance of a "JFrame" and a "JButton", write:
<CODE><PRE>
frame := java getJavaClass:'javax.swing.JFrame' new.
button := java getJavaClass:'javax.swing.JButton' new.
</PRE></CODE>
The first statement results in a proxy object for the "JFrame" instance. The second line results in a proxy for a new "JButton" object.

== Calling Instance Methods ==

A method call is done by a message send to a proxy object, where the message is the method name to call. For example, to call the <CODE>"setVisible(boolean isVisible)"</CODE> method on the above JFrame object, we send the following message to that proxy:
<CODE><PRE>
frame setVisible:true.
</PRE></CODE>

As method naming is different in Smalltalk and Java, a dynamic translation is applied when sending messages from Smalltalk code to a remote Java object. Smalltalk has arguments embedded inside parts of a so called "keyword" message, such as in "receiver foo:arg1 bar:arg2", where "foo:bar:" would be the message name, and "arg1", "arg2" be the arguments.

In Java, the message name is a single identifier, and arguments are written in an argument list after the message name: "receiver.fooBar(arg1, arg2)".

When message names are translated, only the very first part of the Smalltalk keyword message is taken ("foo" in the above example), and the remaining parts are simpl ignored. Thus, any of the Smalltalk messages "foo:bar:", "foo:xxxx:" and "foo:_:" (a single underscore as second part) all translate to the same Java message name "foo()".

Therefore, to call a method with more than one argument, like <CODE>"setSize(int width,int height)"</CODE> on a JFrame instance we can write:
<CODE><PRE>
frame setSize:300 _:200.
</PRE></CODE>
but just as well:
<CODE><PRE>
frame setSize:300 anyWord:200.
</PRE></CODE>
or any other selector with "setSize:" as its first component.
The selector translation mechanism simply takes the first part as the Java selector.

In practice, you should take a reasonably descriptive name, such as: "frame setSize:300 height:200" or only the Java name as first part, such as "frame setSize:300 _:200".

For a call of a method with 4 arguments, we could write:
<CODE><PRE>
frame setBounds:100 y:50 width:300 height:200.
</PRE></CODE>
or:
<CODE><PRE>
frame setBounds:100 _:50 _:300 _:200.
</PRE></CODE>

Also here the <CODE>"y: width: height:"</CODE> can be named as you want, but the first part must be "setBounds:".

=== Calling Static Methods ===

Calling a static method on an object is not different from calling non static methods. In most cases you will call a static method not on an object but directly on the class. This is done by using the class object as "receiver" of the message. For example, if we want to call the static method <CODE>"isDefaultLookAndFeelDecorated()"</CODE> of the JFrame class, write:
<CODE><PRE>
java getJavaClass:'javax.swing.JFrame' isDefaultLookAndFeelDecorated.
</PRE></CODE>

== Accessing Fields ==

As Smalltalk does not support access of an object's fields from the outside (it is fully encapsulated, and access from outside is ONLY allowed via getters/setters), an additional translation mechanism is provided for field access.

Accessing a field of a Java object or a class's static field uses the same syntax as method calls. To access a field, send a message where the message is the field name. To access the field of a class the field must be static.
For example, to get the value of the static field named <CODE>"EXIT_ON_CLOSE"</CODE> of the "JFrame" class, write
<CODE><PRE>
value := java getJavaClass:'javax.swing.JFrame' EXIT_ON_CLOSE.
</PRE></CODE>
The variable "value" now holds the integer value of the <CODE>"EXIT_ON_CLOSE"</CODE> constant.

Assuming that a "JFrame" object had a field named <CODE>"myField"</CODE>, to access this field, we'd have to write:
<CODE><PRE>
value := frame myField.
</PRE></CODE>
and "value" now holding whatever <CODE>"myField"</CODE> returns. This could be another object reference or any primitive value.

=== Setting Fields ===
To set a field, use a setter-like method call:
<CODE><PRE>
frame myField: newValue.
</PRE></CODE>

=== Name Conflicts ===

In very rare situations, a Java object may contain both a field and a method by the same name.
In this case, the Smalltalk code cannot depend on the dynamic translation mechanism (which actually looks for either a field or method name to match), but instead make it explicit, which operation is wanted:
Use:
<CODE><PRE>
frame getFieldByName:'myField'
</PRE></CODE>
to read a field, and:
<CODE><PRE>
frame setFieldByName:'myField' value:123.
</PRE></CODE>
to write the field.

If there are both fields and methods by the same name, and you use the non-explicit call,
the bridge will always assume that you want to call the getter/setter and perform a method call.
 

== Arrays ==

=== Passing Smalltalk Collections to Java ===

Smalltalk collections can now be directly passed to Java with a few limitations:
* The identity of the Smalltalk collections will not be preserved. passing the same collection to java multiple times will result in multiple instances of the same array on the java side. (to bypass this instantiate a new java array)
* Smalltalk collections need to be explicitly converted to the correct type (e.g. a <CODE>SignedIntegerArray</CODE> on the smalltalk side matches an <CODE>int</CODE>-Array on the java side)

=== Instantiating Arrays ===

The new bridge supports instantiation of arrays (whereas previously reflection had to be used to instantiate arrays from the smalltalk side).
There are two ways an array can be instantiated:

<CODE><PRE>
intArray := (java getJavaClass:'int[]') new:#[ 1 2 3 4 5 ] asSignedIntegerArray. "/ instantiates a new array of type "int" with the contents "1, 2, 3, 4, 5"
</PRE></CODE>

<CODE><PRE>
intArray := (java getJavaClass:'int[]') new:10. "/ instantiates a new empty array of type "int" with 10 elements.
</PRE></CODE>

=== Accessing Arrays ===

To achieve better performance, arrays of primitive types smaller than a certain size have their contents cached on the smalltalk side:
<CODE><PRE>
intArray contents at:1. "/ this will access the first element of the cached contents.
</PRE></CODE>

large arrays are not serialized immediately. large arrays will be serialized when <CODE>contents</CODE> is called the first time.

'''Attention:''' Java arrays are not immutable. changes to an array are not reflected in the cached contents. if an array has been updated, call <CODE>refresh</CODE> on the array to update the cache. arrays will not be updated automatically.

<CODE><PRE>
shortArray := (java getJavaClass:'short[]') new:10. "/ new empty "short" array with 10 elements

"/ copy the contents of the smalltalk collection to the newly instantiated short array
(java getJavaClass:'java.lang.System') arraycopy:(#[ 1 2 3 ] asSignedWordArray) srcPos:0 dest:shortArray destPos:0 length:3.

shortArray at:0. "/ will reflect the changes made to the array

shortArray contents at:1. "/ will still return 0 because the cached contents have not been updated.

shortArray refresh. "/ update the cached contents

shortArray contents at:1. "/ will now correctly reflect the changes made to the array
</PRE></CODE>

== Asynchronous Communication ==

In the new Bridge, everything can be done asynchronously. This is achieved via the <CODE>asyncDo:aBlock</CODE> method.
Every request sent to the Bridge inside of aBlock will immediately return a lazy value.
This lazy value will block upon access until the actual result is received from the java side.
The order of execution is guaranteed to be the same on the java side as on the smalltalk side.

Example:
<CODE><PRE>
java asyncDo:[
lazyInteger := (java getJavaClass:'java.lang.Integer') new:40. "/ this will return immediately
].
actualInteger := lazyInteger value. "/ this will block until the result of the previous call is available
</PRE></CODE>

== Callbacks from Java ==
Sometimes you may want to execute a piece of Smalltalk code during the execution of the Java code. For example, we may want to install a Smalltalk observer to be notified when a button on a Java GUI was pressed,
or some other callback from a Java framework.

The following code registers a Smalltalk block as a callback for a mouse press event of a button:
<CODE><PRE>
listener := MouseListener new.
listener implementMethod:'mousePressed' as:[ Transcript showCR:'Hello from Java' ].
</PRE></CODE>
The above creates the callback and the listener, which can now be registered on a button:
<CODE><PRE>
button addMouseListener:listener.
</PRE></CODE>
Now, with the press of the button in the Java GUI, the Smalltalk block will be executed and writes <CODE>"Hello from Java"</CODE> to the Smalltalk console.
Of course, any other (Smalltalk-)action code can be made to run via this mechanism.

But be aware, that the callback is possibly called later (when the elementary action, which installed the code, has already finished long ago). Also, as the Java code execution is not synchronized with any of your expecco action execution, the callback may also be called at any arbutrary time, even at times when no activity at all is executed on the expecco side. If you forget to cleanup, and the Java object is still alive, it may even be called after you have finished your test run (if you keep the java bridge handle around and alive, for example in an expecoo environment variable).

So the Smalltalk callback code should not depend on any particular elementary action to be currently running, but instead in most cases write some information into a shared data container, preferably an instance of "SharedQueue", which is thread safe. Then, some other action (an elementary action) would read-wait and read events from that shared queue.

make sure that your test correctly cleans up any such callbacks afterwards. As a last resort, use the "Shutdown Bridge Connection" menu item, which closes the bridge connection, and thereby - as a side effect - removes any leftover callbacks. It does close the connection, and any remaining java proxy object handles become invalid, though.

Another example, using an observer could look like:
<CODE><PRE>
observer := java Observer new.
observer implementMethod:'update'
as:[:sourceObservable :argument|
argument notNil ifTrue:[ Transcript showCR:('I was notifyed with: ',argument toString) ]
ifFalse:[ Transcript showCR:'I was notifyed and the argument was nil' ].
].
myObservable addObserver:observer.
</PRE></CODE>
When the observable calls <CODE>"notifyObservers"</CODE>, the Smalltalk block will be executed.

== Exceptions in Java ==
Exceptions on the Java side are signalled back to the Smalltalk side and raise a corresponding exception there. However, on the Java side, the call stack which lead to the exception has already been unwound at that time (Java exceptions are not proceedable). So a proceed in the Smalltalk-side exception handler only affects the Smalltalk caller, but may leave the Java side in an undefined state.

== Remote Dynamic Code Injection ==
Sometimes we might want to execute code without the overhead of many rpc-messages being sent over the bridge, especially if we want to do something time critical, or want to make execution time measurements.
For this, it is possible to load a class at runtime into the JavaVM. The code of the class will first be sent to the JavaVM, which will compile and load the generated byte code. Then, the class can be accessed via the bridge just like any other preloaded class.

The following example specifies the class code in a smalltalk string and inject the code into the JavaVM. Then an instance of that new class will be instantiated and finally a method of the object instance will be invoked:
<CODE><PRE>
classCode := '
package myPackage.test;

import java.awt.BorderLayout;
import java.awt.event.MouseAdapter;
import java.awt.event.MouseEvent;
import java.util.Calendar;

import javax.swing.JButton;
import javax.swing.JFrame;
import javax.swing.JLabel;;

public class MyInjectedClass {
public void createSampleApp(){
JFrame frame=new JFrame("Hello im injected");
frame.setLayout(new BorderLayout());
JButton button=new JButton("click me");
final JLabel label=new JLabel("Text");
button.addMouseListener(new MouseAdapter() {

@Override
public void mouseClicked(MouseEvent e) {
label.setText(Calendar.getInstance().getTime().toString());
}
});
frame.add(label,BorderLayout.NORTH);
frame.add(button,BorderLayout.SOUTH);
frame.setSize(300, 300);
frame.setVisible(true);
}
}
'.
classObject := java getJavaClass:'myPackage.test.MyInjectedClass' fromSource:classCode.
classObject new createSampleApp.
</PRE></CODE>
After the code has been injected, a new instance of <CODE>"MyInjectedClass"</CODE> is created and the <CODE>"createSampleApp"</CODE> method is called. Because the example implements a GUI, a Java window will open, containing a label and a button. Clicking the button displays the current time in the label.



=== Code Sources for Class injection ===
There are 3 possible types of class code sources which we can use to inject the code. In the examples before we directly used a simple <CODE>"String"</CODE> in the smalltalk code as a code source. We also can use a <CODE>"*.java"</CODE> file as source. Just read the content of the file into a string and use it as in the previous examples.

To inject a <CODE>"*.class"</CODE> file use the following code:
<pre>
java getJavaClass:'the.class.name' fromByteCode:classCode.
</pre>

== Examples ==

This example creates a JFrame with one button inside. Then a Mouselistener is created and registered on the button. When the button is pressed, the title of the window changes to <CODE>"onPressed"</CODE> and the Transcript shows the message <CODE>"onPressed"</CODE>. When the button is released, the title of the window is changed to <CODE>"onReleased"</CODE> and the Transcript shows <CODE>"onReleased"</CODE>. If the button lost the mouse focus, the bridge will exit (disconnect), and the Java side is terminated.
<CODE><PRE>
|java frame button listener|

"/getting a bridge
java := JAVA::JavaBridge newWithServer.

"/creating a new frame and button object
frame := java getJavaClass:'javax.swing.JFrame' new.
button := java JButton new:'Click'.

"/creating a new mouse listener and adding callback blocks
listener := java MouseListener new.

listener implementMethod:'mousePressed' as:[ Transcript showCR:'onPress'. frame setTitle:'onPressed' ].
listener implementMethod:'mouseReleased' as:[ Transcript showCR:'onReleased'. frame setTitle:'onReleased' ].
listener implementMethod:'mouseExited' as:[ Transcript showCR:'onExited'. java closeBridge. ].

"/register the mouse listener on the button and make the frame with button visible
button addMouseListener:listener.
frame add:button.
frame setSize:300 y:100.
frame setVisible: true.
</PRE></CODE>



==Differences between v1 and v2==
===General===
* A Java Bridge instance no longer requires multiple tcp ports to be open. This simplifies connection through ssh tunnels and firewalls.
* The identity of strings and primitve wrappers can now be preserved. (see [[#boxedDo:aBlock | boxedDo]])
* Arrays of primitive types are serialized. (see [[#Arrays | Arrays]])

===Loading Applications===
* '''addJarByPath:''' and '''addToClassPath:''' are still supported but have been deprecated. use '''loadJar:''', '''loadJarByPath:''' and '''loadExtension:''' instead. The new methods no longer require the jar or library to be present on the remote machine.

[[Java Interface Library#Loading Applications (from the expecco side) | v1]] [[#Loading Applications (from the expecco side) | v2]]

===Java Class Access===
* Sending the fully qualified name with instances of "." replaced by "_" to the bridge handle is still supported, but not recommended.
* A new method '''getJavaClass:''' has been introduced (also available for v1 since expecco v2.9). This solves the side effects of "_" being a legal character in class names.

[[Java Interface Library#Java Package Import and Class Access | v1]] [[#Java Class Access | v2]]
===Callbacks from Java===
* A new method '''implementMethod:as:''' has been introduced to assign callback blocks to method names. The old way is still supported.

[[Java Interface Library#Callbacks from Java | v1]] [[#Callbacks from Java | v2]]

===Remote Dynamic Code Injection===
* Code injection was problematic in v1 and has now been re-implemented in v2.

[[#Remote Dynamic Code Injection | v2]]

== API ==
===JAVA::Java===
====class protocol====
=====newWithServer=====
* This will start a local JavaVM, running the JavaBridge, and establishes a connection on a random free port.
: A new connected instance of JAVA::Java class is returned.

=====newWithServerForJavaPath:aJavaPathFilename=====
* This is the same as newWithServer but the path to the java executable can be specified. The JavaVM version must be 1.6 or higher to run the JavaBridge.
:: '''aJavaPathFilename''' - must be a instance of Filename
Smalltalk: JAVA::Java newWithServerForJavaPath:('my\path\to\java.executable'asFilename).
JavaScript: JAVA::Java.newWithServerForJavaPath("my\path\to\java.executable".asFilename());

=====newConnectedTo:aHhostString port:aPortNumber withTimeout:aTimeoutSeconds=====
* This is used to connect to a running JavaBridge on the network. The JavaBridge must be started in server mode on the remote host. After connecting a new connected instance of JAVA::Java is returned.
:: '''aHostString''' - the hostname or IP of the remote machine as String
:: '''aPortNumber ''' - the port on which the remote machine is listening as Number
:: '''aTimeoutSeconds''' - a connect timeout in seconds as Number
Smalltalk: JAVA::Java newConnectedTo:'myHostName' port:4567 withTimeout:30.
JavaScript: JAVA::Java.newConnectedTo_port_withTimeout("myHostName",4567,30);

=====newWaitingForConnectOnHost:aListeningAddressString port:aListeningPortNumber withTimeout:aTimeoutSeconds=====
* This is used to wait for incomming connecions of a running JavaBridge on the network. The JavaBridge must be started in client mode on the remote host. After connecting a new connected instance of JAVA::Java is returned.
:: '''deprecated: aListeningAddressString''' - no longer used. Can be nil.
:: '''aListeningPortNumber ''' - the port on which to listen for incomming connections as Number
:: '''aTimeoutSeconds''' - a connect timeout in seconds as Number, If nil it will wait endless.

=====singletonInstance=====
* This will call newWithServer for the first time and then always returns the same connected JAVA::Java instance until the connection was closed, then a new connected instance is returned.

=====exitAllInstances=====
* This will close all instances of JAVA::Java.

====instance protocol====
=====loadJarByPath:aPath=====
* Adds a jar to the running JavaVM. If the jar depends on other jars or libraries you have to add them too.
:: '''aPath''' - the path to the jar file as String.

=====loadJar:aByteArray=====
* Adds a jar to the running JavaVM. If the jar depends on other jars or libraries you have to add them too.
:: '''aByteArrays''' - a ByteArray containing the JAR file.

=====loadExtension:aPath=====
* Adds a jar to the running JavaVM and caches it for subsequent usages. If the jar depends on other jars you have to add them too.
:: '''aPath''' - the path to the jar file as String.

=====boxedDo:aBlock=====
* Any autoboxed values in aBlock returned from the JavaVM are preserved as such. By default autoboxed values are automatically unboxed. This way, the identity of such objects is preserved.

=====isConnected=====
* Tests if a connection is still established.
:: '''return:''' - true if the connection is still established, else false.

=====isAlive=====
* Tests if a connection is still responding.
:: '''return:''' - true if the connection is still alive, else false. Does a message round trip.

=====closeBridge=====
* This will close the bridge connection. Depending on in which mode the JavaBridge was started, the JavaVM is also closed (-keepAlive startparameter not set).

=====exit=====
* Same as closeBridge.

== See Also==
The [[DOT NET Interface Library| DOTNET Interface Plugin & Library]], which implements a likewise interface for .NET applications/libraries.
 
[[Java Interface Library | Version 1 of the Java Interface Library]]
<hr>
Back to [[Plugins]]

Java Interface Library v2

2016-06-01T10:36:26Z

Javogel:

== Introduction ==

This article discusses version 2 of the Java Bridge (which is as of expecco v2.9 still experimental).
The article for version 1 can be found [[Java Interface Library | here]].

The Java Interface library ("Java Bridge") is used to interact with Java objects inside an external Java Virtual Machine (JVM).

The access to Java objects, classes and programs is done via a framework called "''Java-Bridge''", which is similar in operation to the [[DOT NET Interface Library| dotNET bridge]]. This framework implements transparent forwarding of method (virtual function) calls to Java objects, which exist in a local or remote Java Virtual Machine (JVM). Also, return values, callBacks and exception information are passed back from the Java program to expecco. This is done by a proxy-object mechanism, which catches all function calls, wraps the arguments, sends a datagram to the other bridge side, awaits the reply and returns the result to the original caller. Thus, remote procedure calls are almost completely transparent to the Smalltalk/JavaScript code inside expecco. In your elementary code, you can write remote function calls as if they were to local objects.

Notice that this document describes the low level framework, which implements the bridge communication. A much easier to use high level interface (called "Groovy Blocks") exists and should normally be used, if you need access to a java application's internals during testing.
Please take a look at
[[Expecco_API#Groovy_Elementary_Blocks | "Groovy Block API"]]
and [[Testing Java Applications using Groovy blocks/en | "Testing Java Applications using Groovy blocks"]].

== Architecture ==

On the expecco side, the bridge consists of a number of Proxy objects,
which behave like regular Smalltalk objects as seen from elementary expecco code.
However, instead of performing an action when one of their methods (virtual functions) is called,
they send a message over a socket connection to the Java VM (actually: to a bridge software inside the
Java application) which decodes the message and sends it to the destination Java object.
The same is done in reverse direction with the return value.

+---------------------+ +----------+ +----------------+ +----------------+ +---------+
| | | | | | | | | Java |
| expecco |---->| Proxy |---->| Bridge |==>>==| Bridge |---->| Object |
| (elementary code) |<----| |<----| (expecco side) |==<<==| (Java side) |<----| |
+---------------------+ +----------+ +----------------+ +----------------+ +---------+

This setup allows for transparent communication with objects inside a local or remote Java VM. This may be either utility functions which happen to be convenient for the test application (for example: file parsing, syntax analysis, protocol implementaitons or access to specific hardware via driver libraries), or the tested application in the system under test itself.

Especially, it allows for the objects of the tested application to be looked into, manipulated and for functions of it or underlying frameworks to be called.

For expecco code, we tried to make this as transparent as possible, however there are a few exceptions, when function names need to be translated (for example, because the function naming syntax is different) or due to the fact that for some operations no corresponding name exists in Smalltalk (array access, for example).

Of course, multiple such connections can coexist and be served/handled in parallel. This enables an expecco test suite to communicate with both sides of a tested client-server Java application, for example.

Notice that a similar mechanism is used in expecco to communicate with DOTNET, Qt (C++) and C applications.

 

== Activating the new Java Bridge ==
To activate the new bridge in expecco navigate to <CODE>Extras -> Settings -> Plugins -> Java Bridge</CODE> and tick the '''Use new Bridge (experimental)''' checkbox.
[[Datei:ActivateNewJavaBridge.png]]

'''Attention:''' Ticking the checkbox will terminate all currently active Bridge connections due to incompatibilities between the new and the old version.

== Initializing / Releasing the Bridge ==

Before any communication can take place between expecco and any Java object, the Java side of the bridge has to be started, and a communication has to be established.
In expecco, all of the bridge classes are found in the <CODE>JAVA</CODE> namespace.

The main interface class is "<CODE>Java</CODE>", in the "<CODE>JAVA</CODE>" namespace:
<CODE><PRE>
java := JAVA::Java newWithServer.
</PRE></CODE>
or (in JavaScript):
<CODE><PRE>
java = JAVA::Java.newWithServer();
</PRE></CODE>

This starts the Java-side of the bridge (actually executes java as a background command) on the local machine, and establishes a connection to that JVM.

The bridge connection should be closed, if the bridge is no longer needed. Release the bridge with:
<CODE><PRE>
java.closeBridge();
</PRE></CODE>
which terminates the connection.

=== Start and Connect to a Remote Machine ===
The above started a Java VM and connected to it. Alternatively, you may want to connect to an already running Java program (typically, your system under test).
In order for your program to be reachable, it must allow for the bridge to connect to it via a special bridge-connection, which is a socket connection. For this, it must execute the server code found in the "JavaBridge.jar" file. To pass [[#Startup Parameters| parameters]] you will typically start it from a command line or a little shell/batch script.

Call (on the shell/cmd level):
$ java -jar <PATH_TO_JAVABRIDGE.JAR> <PARAMETERS>

The "JavaBridge.jar" file is found in the installation directory of expecco at:
\exept\expecco\packages\exept\bridgeFramework\javaBridge\javaBin\JavaBridge.jar

The Javabridge code allows for either side to initiate the connection - i.e. it can be run in server mode,
where it awaits an incoming connection, or in client mode, where it actively initiates a connection.
After connection establishment, there is no difference in the operation of the bridge, however depending on the setup of your network infrastructure, especially firewalls, either mechanism may be easier to be used.

Assuming that the bridge is already running on the remote machine as server (default),
use <CODE>newConnectedTo:port:withTimeout:</CODE> to connect to it from the expecco side:
java := JAVA::Java newConnectedTo:'myHost' port:4567 withTimeout:30.
This will initiate the connection setup from the expecco side.

Alternatively, if started in client mode use <CODE>newWaitingForConnectOnHost:port:withTimeout:</CODE>:
java := JAVA::Java newWaitingForConnectOnHost:'localhost' port:4567 withTimeout:30.
which will open a port on the expecco side, and wait until the Java side connects to it.
[[#JAVA::Java|For more details see API]]

====Startup Parameters====
You can use any parameter in any order.
If no parameter is used then the bridge listenes on port 14014 in server mode without keepAlive.
;<code>-help</code>
* Shows the help

;<code>-ip <aHostnameOrIP></code>
* In client mode this specifies the ip or hostname to connect to. In server mode this specifies the ip or hostname to bind to.

;<code>-port <aPortNumber> </code>
* In client mode this specifies the port to connect to. In server mode this specifies the listening port.

;<code>-asClient</code>
* The bridge will start in client mode. If not set the bridge is started in server mode.

;<code>-keepAlive</code>
* By setting this flag the bridge will not exit after the connection has closed and starts to connect or listen again. Otherwise, it will run for a single connection session only.

== Loading Applications (from the expecco side) ==

Normally, you would start your application with the required command line arguments and include the javabridge as jar there. However, in some situations, it may be required to dynamically load other jars into the connected Java VM.
By accessing a classloader, additional classes, or applications as contained in JAR files can be loaded from the expecco side.

This can be used to add a JAR file to the classloader:
<CODE><PRE>
java loadJarByPath:'pathToJarFile'. "/ assuming "java" is a handle as returned from the above connect
</PRE></CODE>

or, if the JAR file is loaded in memory:
<CODE><PRE>
java loadJar:jarByteArray. "/ where "jarByteArray" is a ByteArray containing the JAR file
</PRE></CODE>

If the JVM is on a remote machine, the path is resolved on the expecco side and the JAR will be transferred to the remote side.

Should transferring the JAR be too much overhead, an additional mechanism is provided:
<CODE><PRE>
java loadExtension:'pathToJarFile'.
</PRE></CODE>
this will cache the JAR file on the bridge side and eliminate the overhead of subsequent invocations.

== Java Class Access ==

This following code sample simply references (i.e. accesses) the class "JFrame" from the <CODE>"javax.swing"</CODE> package. The fully specified class name in Java would be <CODE>"javax.swing.JFrame"</CODE>:
<CODE><PRE>
java getJavaClass:'javax.swing.JFrame'
</PRE></CODE>

Or, if you want to load multiple classes:
<CODE><PRE>
java import:'javax.swing.JFrame' import:'javax.swing.JButton'
do:[:jFrame :jButton | "do something with JButton and JFrame" ].
</PRE></CODE>

v2 also supports dynamic compilation of java source code:
<CODE><PRE>
java getJavaClass:'className' fromSource:'classSource'. "/ where classSource is a String containing valid java source code
</PRE></CODE>

and loading precompiled java bytecode:
<CODE><PRE>
java getJavaClass:'className' fromByteCode:byteCode. "/ where byteCode is a ByteArray containing valid java bytecode
</PRE></CODE>

[[#Remote Dynamic Code Injection | for details see Remote Dynamic Code Injection]]

== Instantiating a Class ==

Object instances are created via the "new"-message, sent to a proxy of a Java class. You can get this proxy as described in the previous section. For example, if we want to create a new instance of a "JFrame" and a "JButton", write:
<CODE><PRE>
frame := java getJavaClass:'javax.swing.JFrame' new.
button := java getJavaClass:'javax.swing.JButton' new.
</PRE></CODE>
The first statement results in a proxy object for the "JFrame" instance. The second line results in a proxy for a new "JButton" object.

== Calling Instance Methods ==

A method call is done by a message send to a proxy object, where the message is the method name to call. For example, to call the <CODE>"setVisible(boolean isVisible)"</CODE> method on the above JFrame object, we send the following message to that proxy:
<CODE><PRE>
frame setVisible:true.
</PRE></CODE>

As method naming is different in Smalltalk and Java, a dynamic translation is applied when sending messages from Smalltalk code to a remote Java object. Smalltalk has arguments embedded inside parts of a so called "keyword" message, such as in "receiver foo:arg1 bar:arg2", where "foo:bar:" would be the message name, and "arg1", "arg2" be the arguments.

In Java, the message name is a single identifier, and arguments are written in an argument list after the message name: "receiver.fooBar(arg1, arg2)".

When message names are translated, only the very first part of the Smalltalk keyword message is taken ("foo" in the above example), and the remaining parts are simpl ignored. Thus, any of the Smalltalk messages "foo:bar:", "foo:xxxx:" and "foo:_:" (a single underscore as second part) all translate to the same Java message name "foo()".

Therefore, to call a method with more than one argument, like <CODE>"setSize(int width,int height)"</CODE> on a JFrame instance we can write:
<CODE><PRE>
frame setSize:300 _:200.
</PRE></CODE>
but just as well:
<CODE><PRE>
frame setSize:300 anyWord:200.
</PRE></CODE>
or any other selector with "setSize:" as its first component.
The selector translation mechanism simply takes the first part as the Java selector.

In practice, you should take a reasonably descriptive name, such as: "frame setSize:300 height:200" or only the Java name as first part, such as "frame setSize:300 _:200".

For a call of a method with 4 arguments, we could write:
<CODE><PRE>
frame setBounds:100 y:50 width:300 height:200.
</PRE></CODE>
or:
<CODE><PRE>
frame setBounds:100 _:50 _:300 _:200.
</PRE></CODE>

Also here the <CODE>"y: width: height:"</CODE> can be named as you want, but the first part must be "setBounds:".

=== Calling Static Methods ===

Calling a static method on an object is not different from calling non static methods. In most cases you will call a static method not on an object but directly on the class. This is done by using the class object as "receiver" of the message. For example, if we want to call the static method <CODE>"isDefaultLookAndFeelDecorated()"</CODE> of the JFrame class, write:
<CODE><PRE>
java getJavaClass:'javax.swing.JFrame' isDefaultLookAndFeelDecorated.
</PRE></CODE>

== Accessing Fields ==

As Smalltalk does not support access of an object's fields from the outside (it is fully encapsulated, and access from outside is ONLY allowed via getters/setters), an additional translation mechanism is provided for field access.

Accessing a field of a Java object or a class's static field uses the same syntax as method calls. To access a field, send a message where the message is the field name. To access the field of a class the field must be static.
For example, to get the value of the static field named <CODE>"EXIT_ON_CLOSE"</CODE> of the "JFrame" class, write
<CODE><PRE>
value := java getJavaClass:'javax.swing.JFrame' EXIT_ON_CLOSE.
</PRE></CODE>
The variable "value" now holds the integer value of the <CODE>"EXIT_ON_CLOSE"</CODE> constant.

Assuming that a "JFrame" object had a field named <CODE>"myField"</CODE>, to access this field, we'd have to write:
<CODE><PRE>
value := frame myField.
</PRE></CODE>
and "value" now holding whatever <CODE>"myField"</CODE> returns. This could be another object reference or any primitive value.

=== Setting Fields ===
To set a field, use a setter-like method call:
<CODE><PRE>
frame myField: newValue.
</PRE></CODE>

=== Name Conflicts ===

In very rare situations, a Java object may contain both a field and a method by the same name.
In this case, the Smalltalk code cannot depend on the dynamic translation mechanism (which actually looks for either a field or method name to match), but instead make it explicit, which operation is wanted:
Use:
<CODE><PRE>
frame getFieldByName:'myField'
</PRE></CODE>
to read a field, and:
<CODE><PRE>
frame setFieldByName:'myField' value:123.
</PRE></CODE>
to write the field.

If there are both fields and methods by the same name, and you use the non-explicit call,
the bridge will always assume that you want to call the getter/setter and perform a method call.
 

== Arrays ==

=== Passing Smalltalk Collections to Java ===

Smalltalk collections can now be directly passed to Java with a few limitations:
* The identity of the Smalltalk collections will not be preserved. passing the same collection to java multiple times will result in multiple instances of the same array on the java side. (to bypass this instantiate a new java array)
* Smalltalk collections need to be explicitly converted to the correct type (e.g. a <CODE>SignedIntegerArray</CODE> on the smalltalk side matches an <CODE>int</CODE>-Array on the java side)

=== Instantiating Arrays ===

The new bridge supports instantiation of arrays (whereas previously reflection had to be used to instantiate arrays from the smalltalk side).
There are two ways an array can be instantiated:

<CODE><PRE>
intArray := (java getJavaClass:'int[]') new:#[ 1 2 3 4 5 ] asSignedIntegerArray. "/ instantiates a new array of type "int" with the contents "1, 2, 3, 4, 5"
</PRE></CODE>

<CODE><PRE>
intArray := (java getJavaClass:'int[]') new:10. "/ instantiates a new empty array of type "int" with 10 elements.
</PRE></CODE>

=== Accessing Arrays ===

To achieve better performance, arrays of primitive types smaller than a certain size have their contents cached on the smalltalk side:
<CODE><PRE>
intArray contents at:1. "/ this will access the first element of the cached contents.
</PRE></CODE>

large arrays are not serialized immediately. large arrays will be serialized when <CODE>contents</CODE> is called the first time.

'''Attention:''' Java arrays are not immutable. changes to an array are not reflected in the cached contents. if an array has been updated, call <CODE>refresh</CODE> on the array to update the cache. arrays will not be updated automatically.

<CODE><PRE>
shortArray := (java getJavaClass:'short[]') new:10. "/ new empty "short" array with 10 elements

"/ copy the contents of the smalltalk collection to the newly instantiated short array
(java getJavaClass:'java.lang.System') arraycopy:(#[ 1 2 3 ] asSignedWordArray) srcPos:0 dest:shortArray destPos:0 length:3.

shortArray at:0. "/ will reflect the changes made to the array

shortArray contents at:1. "/ will still return 0 because the cached contents have not been updated.

shortArray refresh. "/ update the cached contents

shortArray contents at:1. "/ will now correctly reflect the changes made to the array
</PRE></CODE>

== Asynchronous Communication ==

In the new Bridge, everything can be done asynchronously. This is achieved via the <CODE>asyncDo:aBlock</CODE> method.
Every request sent to the Bridge inside of aBlock will immediately return a lazy value.
This lazy value will block upon access until the actual result is received from the java side.
The order of execution is guaranteed to be the same on the java side as on the smalltalk side.

Example:
<CODE><PRE>
java asyncDo:[
lazyInteger := (java getJavaClass:'java.lang.Integer') new:40. "/ this will return immediately
].
actualInteger := lazyInteger value. "/ this will block until the result of the previous call is available
</PRE></CODE>

== Callbacks from Java ==
Sometimes you may want to execute a piece of Smalltalk code during the execution of the Java code. For example, we may want to install a Smalltalk observer to be notified when a button on a Java GUI was pressed,
or some other callback from a Java framework.

The following code registers a Smalltalk block as a callback for a mouse press event of a button:
<CODE><PRE>
listener := MouseListener new.
listener implementMethod:'mousePressed' as:[ Transcript showCR:'Hello from Java' ].
</PRE></CODE>
The above creates the callback and the listener, which can now be registered on a button:
<CODE><PRE>
button addMouseListener:listener.
</PRE></CODE>
Now, with the press of the button in the Java GUI, the Smalltalk block will be executed and writes <CODE>"Hello from Java"</CODE> to the Smalltalk console.
Of course, any other (Smalltalk-)action code can be made to run via this mechanism.

But be aware, that the callback is possibly called later (when the elementary action, which installed the code, has already finished long ago). Also, as the Java code execution is not synchronized with any of your expecco action execution, the callback may also be called at any arbutrary time, even at times when no activity at all is executed on the expecco side. If you forget to cleanup, and the Java object is still alive, it may even be called after you have finished your test run (if you keep the java bridge handle around and alive, for example in an expecoo environment variable).

So the Smalltalk callback code should not depend on any particular elementary action to be currently running, but instead in most cases write some information into a shared data container, preferably an instance of "SharedQueue", which is thread safe. Then, some other action (an elementary action) would read-wait and read events from that shared queue.

make sure that your test correctly cleans up any such callbacks afterwards. As a last resort, use the "Shutdown Bridge Connection" menu item, which closes the bridge connection, and thereby - as a side effect - removes any leftover callbacks. It does close the connection, and any remaining java proxy object handles become invalid, though.

Another example, using an observer could look like:
<CODE><PRE>
observer := java Observer new.
observer implementMethod:'update'
as:[:sourceObservable :argument|
argument notNil ifTrue:[ Transcript showCR:('I was notifyed with: ',argument toString) ]
ifFalse:[ Transcript showCR:'I was notifyed and the argument was nil' ].
].
myObservable addObserver:observer.
</PRE></CODE>
When the observable calls <CODE>"notifyObservers"</CODE>, the Smalltalk block will be executed.

== Exceptions in Java ==
Exceptions on the Java side are signalled back to the Smalltalk side and raise a corresponding exception there. However, on the Java side, the call stack which lead to the exception has already been unwound at that time (Java exceptions are not proceedable). So a proceed in the Smalltalk-side exception handler only affects the Smalltalk caller, but may leave the Java side in an undefined state.

== Remote Dynamic Code Injection ==
Sometimes we might want to execute code without the overhead of many rpc-messages being sent over the bridge, especially if we want to do something time critical, or want to make execution time measurements.
For this, it is possible to load a class at runtime into the JavaVM. The code of the class will first be sent to the JavaVM, which will compile and load the generated byte code. Then, the class can be accessed via the bridge just like any other preloaded class.

The following example specifies the class code in a smalltalk string and inject the code into the JavaVM. Then an instance of that new class will be instantiated and finally a method of the object instance will be invoked:
<CODE><PRE>
classCode := '
package myPackage.test;

import java.awt.BorderLayout;
import java.awt.event.MouseAdapter;
import java.awt.event.MouseEvent;
import java.util.Calendar;

import javax.swing.JButton;
import javax.swing.JFrame;
import javax.swing.JLabel;;

public class MyInjectedClass {
public void createSampleApp(){
JFrame frame=new JFrame("Hello im injected");
frame.setLayout(new BorderLayout());
JButton button=new JButton("click me");
final JLabel label=new JLabel("Text");
button.addMouseListener(new MouseAdapter() {

@Override
public void mouseClicked(MouseEvent e) {
label.setText(Calendar.getInstance().getTime().toString());
}
});
frame.add(label,BorderLayout.NORTH);
frame.add(button,BorderLayout.SOUTH);
frame.setSize(300, 300);
frame.setVisible(true);
}
}
'.
classObject := java getJavaClass:'myPackage.test.MyInjectedClass' fromSource:classCode.
classObject new createSampleApp.
</PRE></CODE>
After the code has been injected, a new instance of <CODE>"MyInjectedClass"</CODE> is created and the <CODE>"createSampleApp"</CODE> method is called. Because the example implements a GUI, a Java window will open, containing a label and a button. Clicking the button displays the current time in the label.



=== Code Sources for Class injection ===
There are 3 possible types of class code sources which we can use to inject the code. In the examples before we directly used a simple <CODE>"String"</CODE> in the smalltalk code as a code source. We also can use a <CODE>"*.java"</CODE> file as source. Just read the content of the file into a string and use it as in the previous examples.

To inject a <CODE>"*.class"</CODE> file use the following code:
<pre>
java getJavaClass:'the.class.name' fromByteCode:classCode.
</pre>

== Examples ==

This example creates a JFrame with one button inside. Then a Mouselistener is created and registered on the button. When the button is pressed, the title of the window changes to <CODE>"onPressed"</CODE> and the Transcript shows the message <CODE>"onPressed"</CODE>. When the button is released, the title of the window is changed to <CODE>"onReleased"</CODE> and the Transcript shows <CODE>"onReleased"</CODE>. If the button lost the mouse focus, the bridge will exit (disconnect), and the Java side is terminated.
<CODE><PRE>
|java frame button listener|

"/getting a bridge
java := JAVA::JavaBridge newWithServer.

"/creating a new frame and button object
frame := java getJavaClass:'javax.swing.JFrame' new.
button := java JButton new:'Click'.

"/creating a new mouse listener and adding callback blocks
listener := java MouseListener new.

listener implementMethod:'mousePressed' as:[ Transcript showCR:'onPress'. frame setTitle:'onPressed' ].
listener implementMethod:'mouseReleased' as:[ Transcript showCR:'onReleased'. frame setTitle:'onReleased' ].
listener implementMethod:'mouseExited' as:[ Transcript showCR:'onExited'. java closeBridge. ].

"/register the mouse listener on the button and make the frame with button visible
button addMouseListener:listener.
frame add:button.
frame setSize:300 y:100.
frame setVisible: true.
</PRE></CODE>



==Differences between v1 and v2==
===General===
* A Java Bridge instance no longer requires multiple tcp ports to be open. This simplifies connection through ssh tunnels and firewalls.
* The identity of strings and primitve wrappers can now be preserved. (see [[#boxedDo:aBlock | boxedDo]])
* Arrays of primitive types are serialized. (see [[#Arrays | Arrays]])

===Loading Applications===
* '''addJarByPath:''' and '''addToClassPath:''' are still supported but have been deprecated. use '''loadJar:''', '''loadJarByPath:''' and '''loadExtension:''' instead. The new methods no longer require the jar or library to be present on the remote machine.

[[Java Interface Library#Loading Applications (from the expecco side) | v1]] [[#Loading Applications (from the expecco side) | v2]]

===Java Class Access===
* Sending the fully qualified name with instances of "." replaced by "_" to the bridge handle is still supported, but not recommended.
* A new method '''getJavaClass:''' has been introduced (also available for v1 since expecco v2.9). This solves the side effects of "_" being a legal character in class names.

[[Java Interface Library#Java Package Import and Class Access | v1]] [[#Java Class Access | v2]]
===Callbacks from Java===
* A new method '''implementMethod:as:''' has been introduced to assign callback blocks to method names. The old way is still supported.

[[Java Interface Library#Callbacks from Java | v1]] [[#Callbacks from Java | v2]]

===Remote Dynamic Code Injection===
* Code injection was problematic in v1 and has now been re-implemented in v2.

[[#Remote Dynamic Code Injection | v2]]

== API ==
===JAVA::Java===
====class protocol====
=====newWithServer=====
* This will start a local JavaVM, running the JavaBridge, and establishes a connection on a random free port.
: A new connected instance of JAVA::Java class is returned.

=====newWithServerForJavaPath:aJavaPathFilename=====
* This is the same as newWithServer but the path to the java executable can be specified. The JavaVM version must be 1.6 or higher to run the JavaBridge.
:: '''aJavaPathFilename''' - must be a instance of Filename
Smalltalk: JAVA::Java newWithServerForJavaPath:('my\path\to\java.executable'asFilename).
JavaScript: JAVA::Java.newWithServerForJavaPath("my\path\to\java.executable".asFilename());

=====newConnectedTo:aHhostString port:aPortNumber withTimeout:aTimeoutSeconds=====
* This is used to connect to a running JavaBridge on the network. The JavaBridge must be started in server mode on the remote host. After connecting a new connected instance of JAVA::Java is returned.
:: '''aHostString''' - the hostname or IP of the remote machine as String
:: '''aPortNumber ''' - the port on which the remote machine is listening as Number
:: '''aTimeoutSeconds''' - a connect timeout in seconds as Number
Smalltalk: JAVA::Java newConnectedTo:'myHostName' port:4567 withTimeout:30.
JavaScript: JAVA::Java.newConnectedTo_port_withTimeout("myHostName",4567,30);

=====newWaitingForConnectOnHost:aListeningAddressString port:aListeningPortNumber withTimeout:aTimeoutSeconds=====
* This is used to wait for incomming connecions of a running JavaBridge on the network. The JavaBridge must be started in client mode on the remote host. After connecting a new connected instance of JAVA::Java is returned.
:: '''deprecated: aListeningAddressString''' - no longer used. Can be nil.
:: '''aListeningPortNumber ''' - the port on which to listen for incomming connections as Number
:: '''aTimeoutSeconds''' - a connect timeout in seconds as Number, If nil it will wait endless.

=====singletonInstance=====
* This will call newWithServer for the first time and then always returns the same connected JAVA::Java instance until the connection was closed, then a new connected instance is returned.

=====exitAllInstances=====
* This will close all instances of JAVA::Java.

====instance protocol====
=====loadJarByPath:aPath=====
* Adds a jar to the running JavaVM. If the jar depends on other jars or libraries you have to add them too.
:: '''aPath''' - the path to the jar file as String.

=====loadJar:aByteArray=====
* Adds a jar to the running JavaVM. If the jar depends on other jars or libraries you have to add them too.
:: '''aByteArrays''' - a ByteArray containing the JAR file.

=====loadExtension:aPath=====
* Adds a jar to the running JavaVM and caches it for subsequent usages. If the jar depends on other jars you have to add them too.
:: '''aPath''' - the path to the jar file as String.

=====boxedDo:aBlock=====
* Any autoboxed values in aBlock returned from the JavaVM are preserved as such. By default autoboxed values are automatically unboxed. This way, the identity of such objects is preserved.

=====isConnected=====
* Tests if a connection is still established.
:: '''return:''' - true if the connection is still established, else false.

=====isAlive=====
* Tests if a connection is still responding.
:: '''return:''' - true if the connection is still alive, else false. Does a message round trip.

=====closeBridge=====
* This will close the bridge connection. Depending on in which mode the JavaBridge was started, the JavaVM is also closed (-keepAlive startparameter not set).

=====exit=====
* Same as closeBridge.

== See Also==
The [[DOT NET Interface Library| DOTNET Interface Plugin & Library]], which implements a likewise interface for .NET applications/libraries.

<hr>
Back to [[Plugins]]

Java Interface Library v2

2016-06-01T09:37:40Z

Javogel: /* General */

== Introduction ==

This article discusses version 2 of the Java Bridge (which is as of expecco v2.9 still experimental).
The article for version 1 can be found [[Java Interface Library | here]].

The Java Interface library ("Java Bridge") is used to interact with Java objects inside an external Java Virtual Machine (JVM).

The access to Java objects, classes and programs is done via a framework called "''Java-Bridge''", which is similar in operation to the [[DOT NET Interface Library| dotNET bridge]]. This framework implements transparent forwarding of method (virtual function) calls to Java objects, which exist in a local or remote Java Virtual Machine (JVM). Also, return values, callBacks and exception information are passed back from the Java program to expecco. This is done by a proxy-object mechanism, which catches all function calls, wraps the arguments, sends a datagram to the other bridge side, awaits the reply and returns the result to the original caller. Thus, remote procedure calls are almost completely transparent to the Smalltalk/JavaScript code inside expecco. In your elementary code, you can write remote function calls as if they were to local objects.

Notice that this document describes the low level framework, which implements the bridge communication. A much easier to use high level interface (called "Groovy Blocks") exists and should normally be used, if you need access to a java application's internals during testing.
Please take a look at
[[Expecco_API#Groovy_Elementary_Blocks | "Groovy Block API"]]
and [[Testing Java Applications using Groovy blocks/en | "Testing Java Applications using Groovy blocks"]].

== Architecture ==

On the expecco side, the bridge consists of a number of Proxy objects,
which behave like regular Smalltalk objects as seen from elementary expecco code.
However, instead of performing an action when one of their methods (virtual functions) is called,
they send a message over a socket connection to the Java VM (actually: to a bridge software inside the
Java application) which decodes the message and sends it to the destination Java object.
The same is done in reverse direction with the return value.

+---------------------+ +----------+ +----------------+ +----------------+ +---------+
| | | | | | | | | Java |
| expecco |---->| Proxy |---->| Bridge |==>>==| Bridge |---->| Object |
| (elementary code) |<----| |<----| (expecco side) |==<<==| (Java side) |<----| |
+---------------------+ +----------+ +----------------+ +----------------+ +---------+

This setup allows for transparent communication with objects inside a local or remote Java VM. This may be either utility functions which happen to be convenient for the test application (for example: file parsing, syntax analysis, protocol implementaitons or access to specific hardware via driver libraries), or the tested application in the system under test itself.

Especially, it allows for the objects of the tested application to be looked into, manipulated and for functions of it or underlying frameworks to be called.

For expecco code, we tried to make this as transparent as possible, however there are a few exceptions, when function names need to be translated (for example, because the function naming syntax is different) or due to the fact that for some operations no corresponding name exists in Smalltalk (array access, for example).

Of course, multiple such connections can coexist and be served/handled in parallel. This enables an expecco test suite to communicate with both sides of a tested client-server Java application, for example.

Notice that a similar mechanism is used in expecco to communicate with DOTNET, Qt (C++) and C applications.

 

== Activating the new Java Bridge ==
To activate the new bridge in expecco navigate to <CODE>Extras -> Settings -> Plugins -> Java Bridge</CODE> and tick the '''Use new Bridge (experimental)''' checkbox.
[[Datei:ActivateNewJavaBridge.png]]

'''Attention:''' Ticking the checkbox will terminate all currently active Bridge connections due to incompatibilities between the new and the old version.

== Initializing / Releasing the Bridge ==

Before any communication can take place between expecco and any Java object, the Java side of the bridge has to be started, and a communication has to be established.
In expecco, all of the bridge classes are found in the <CODE>JAVA</CODE> namespace.

The main interface class is "<CODE>Java</CODE>", in the "<CODE>JAVA</CODE>" namespace:
<CODE><PRE>
java := JAVA::Java newWithServer.
</PRE></CODE>
or (in JavaScript):
<CODE><PRE>
java = JAVA::Java.newWithServer();
</PRE></CODE>

This starts the Java-side of the bridge (actually executes java as a background command) on the local machine, and establishes a connection to that JVM.

The bridge connection should be closed, if the bridge is no longer needed. Release the bridge with:
<CODE><PRE>
java.closeBridge();
</PRE></CODE>
which terminates the connection.

=== Start and Connect to a Remote Machine ===
The above started a Java VM and connected to it. Alternatively, you may want to connect to an already running Java program (typically, your system under test).
In order for your program to be reachable, it must allow for the bridge to connect to it via a special bridge-connection, which is a socket connection. For this, it must execute the server code found in the "JavaBridge.jar" file. To pass [[#Startup Parameters| parameters]] you will typically start it from a command line or a little shell/batch script.

Call (on the shell/cmd level):
$ java -jar <PATH_TO_JAVABRIDGE.JAR> <PARAMETERS>

The "JavaBridge.jar" file is found in the installation directory of expecco at:
\exept\expecco\packages\exept\bridgeFramework\javaBridge\javaBin\JavaBridge.jar

The Javabridge code allows for either side to initiate the connection - i.e. it can be run in server mode,
where it awaits an incoming connection, or in client mode, where it actively initiates a connection.
After connection establishment, there is no difference in the operation of the bridge, however depending on the setup of your network infrastructure, especially firewalls, either mechanism may be easier to be used.

Assuming that the bridge is already running on the remote machine as server (default),
use <CODE>newConnectedTo:port:withTimeout:</CODE> to connect to it from the expecco side:
java := JAVA::Java newConnectedTo:'myHost' port:4567 withTimeout:30.
This will initiate the connection setup from the expecco side.

Alternatively, if started in client mode use <CODE>newWaitingForConnectOnHost:port:withTimeout:</CODE>:
java := JAVA::Java newWaitingForConnectOnHost:'localhost' port:4567 withTimeout:30.
which will open a port on the expecco side, and wait until the Java side connects to it.
[[#JAVA::Java|For more details see API]]

====Startup Parameters====
You can use any parameter in any order.
If no parameter is used then the bridge listenes on port 14014 in server mode without keepAlive.
;<code>-help</code>
* Shows the help

;<code>-ip <aHostnameOrIP></code>
* In client mode this specifies the ip or hostname to connect to. In server mode this specifies the ip or hostname to bind to.

;<code>-port <aPortNumber> </code>
* In client mode this specifies the port to connect to. In server mode this specifies the listening port.

;<code>-asClient</code>
* The bridge will start in client mode. If not set the bridge is started in server mode.

;<code>-keepAlive</code>
* By setting this flag the bridge will not exit after the connection has closed and starts to connect or listen again. Otherwise, it will run for a single connection session only.

== Loading Applications (from the expecco side) ==

Normally, you would start your application with the required command line arguments and include the javabridge as jar there. However, in some situations, it may be required to dynamically load other jars into the connected Java VM.
By accessing a classloader, additional classes, or applications as contained in JAR files can be loaded from the expecco side.

This can be used to add a JAR file to the classloader:
<CODE><PRE>
java loadJarByPath:'pathToJarFile'. "/ assuming "java" is a handle as returned from the above connect
</PRE></CODE>

or, if the JAR file is loaded in memory:
<CODE><PRE>
java loadJar:jarByteArray. "/ where "jarByteArray" is a ByteArray containing the JAR file
</PRE></CODE>

If the JVM is on a remote machine, the path is resolved on the expecco side and the JAR will be transferred to the remote side.

Should transferring the JAR be too much overhead, an additional mechanism is provided:
<CODE><PRE>
java loadExtension:'pathToJarFile'.
</PRE></CODE>
this will cache the JAR file on the bridge side and eliminate the overhead of subsequent invocations.

== Java Class Access ==

This following code sample simply references (i.e. accesses) the class "JFrame" from the <CODE>"javax.swing"</CODE> package. The fully specified class name in Java would be <CODE>"javax.swing.JFrame"</CODE>:
<CODE><PRE>
java getJavaClass:'javax.swing.JFrame'
</PRE></CODE>

Or, if you want to load multiple classes:
<CODE><PRE>
java import:'javax.swing.JFrame' import:'javax.swing.JButton'
do:[:jFrame :jButton | "do something with JButton and JFrame" ].
</PRE></CODE>

v2 also supports dynamic compilation of java source code:
<CODE><PRE>
java getJavaClass:'className' fromSource:'classSource'. "/ where classSource is a String containing valid java source code
</PRE></CODE>

and loading precompiled java bytecode:
<CODE><PRE>
java getJavaClass:'className' fromByteCode:byteCode. "/ where byteCode is a ByteArray containing valid java bytecode
</PRE></CODE>

[[#Remote Dynamic Code Injection | for details see Remote Dynamic Code Injection]]

== Instantiating a Class ==

Object instances are created via the "new"-message, sent to a proxy of a Java class. You can get this proxy as described in the previous section. For example, if we want to create a new instance of a "JFrame" and a "JButton", write:
<CODE><PRE>
frame := java getJavaClass:'javax.swing.JFrame' new.
button := java getJavaClass:'javax.swing.JButton' new.
</PRE></CODE>
The first statement results in a proxy object for the "JFrame" instance. The second line results in a proxy for a new "JButton" object.

== Calling Instance Methods ==

A method call is done by a message send to a proxy object, where the message is the method name to call. For example, to call the <CODE>"setVisible(boolean isVisible)"</CODE> method on the above JFrame object, we send the following message to that proxy:
<CODE><PRE>
frame setVisible:true.
</PRE></CODE>

As method naming is different in Smalltalk and Java, a dynamic translation is applied when sending messages from Smalltalk code to a remote Java object. Smalltalk has arguments embedded inside parts of a so called "keyword" message, such as in "receiver foo:arg1 bar:arg2", where "foo:bar:" would be the message name, and "arg1", "arg2" be the arguments.

In Java, the message name is a single identifier, and arguments are written in an argument list after the message name: "receiver.fooBar(arg1, arg2)".

When message names are translated, only the very first part of the Smalltalk keyword message is taken ("foo" in the above example), and the remaining parts are simpl ignored. Thus, any of the Smalltalk messages "foo:bar:", "foo:xxxx:" and "foo:_:" (a single underscore as second part) all translate to the same Java message name "foo()".

Therefore, to call a method with more than one argument, like <CODE>"setSize(int width,int height)"</CODE> on a JFrame instance we can write:
<CODE><PRE>
frame setSize:300 _:200.
</PRE></CODE>
but just as well:
<CODE><PRE>
frame setSize:300 anyWord:200.
</PRE></CODE>
or any other selector with "setSize:" as its first component.
The selector translation mechanism simply takes the first part as the Java selector.

In practice, you should take a reasonably descriptive name, such as: "frame setSize:300 height:200" or only the Java name as first part, such as "frame setSize:300 _:200".

For a call of a method with 4 arguments, we could write:
<CODE><PRE>
frame setBounds:100 y:50 width:300 height:200.
</PRE></CODE>
or:
<CODE><PRE>
frame setBounds:100 _:50 _:300 _:200.
</PRE></CODE>

Also here the <CODE>"y: width: height:"</CODE> can be named as you want, but the first part must be "setBounds:".

=== Calling Static Methods ===

Calling a static method on an object is not different from calling non static methods. In most cases you will call a static method not on an object but directly on the class. This is done by using the class object as "receiver" of the message. For example, if we want to call the static method <CODE>"isDefaultLookAndFeelDecorated()"</CODE> of the JFrame class, write:
<CODE><PRE>
java getJavaClass:'javax.swing.JFrame' isDefaultLookAndFeelDecorated.
</PRE></CODE>

== Accessing Fields ==

As Smalltalk does not support access of an object's fields from the outside (it is fully encapsulated, and access from outside is ONLY allowed via getters/setters), an additional translation mechanism is provided for field access.

Accessing a field of a Java object or a class's static field uses the same syntax as method calls. To access a field, send a message where the message is the field name. To access the field of a class the field must be static.
For example, to get the value of the static field named <CODE>"EXIT_ON_CLOSE"</CODE> of the "JFrame" class, write
<CODE><PRE>
value := java getJavaClass:'javax.swing.JFrame' EXIT_ON_CLOSE.
</PRE></CODE>
The variable "value" now holds the integer value of the <CODE>"EXIT_ON_CLOSE"</CODE> constant.

Assuming that a "JFrame" object had a field named <CODE>"myField"</CODE>, to access this field, we'd have to write:
<CODE><PRE>
value := frame myField.
</PRE></CODE>
and "value" now holding whatever <CODE>"myField"</CODE> returns. This could be another object reference or any primitive value.

=== Setting Fields ===
To set a field, use a setter-like method call:
<CODE><PRE>
frame myField: newValue.
</PRE></CODE>

=== Name Conflicts ===

In very rare situations, a Java object may contain both a field and a method by the same name.
In this case, the Smalltalk code cannot depend on the dynamic translation mechanism (which actually looks for either a field or method name to match), but instead make it explicit, which operation is wanted:
Use:
<CODE><PRE>
frame getFieldByName:'myField'
</PRE></CODE>
to read a field, and:
<CODE><PRE>
frame setFieldByName:'myField' value:123.
</PRE></CODE>
to write the field.

If there are both fields and methods by the same name, and you use the non-explicit call,
the bridge will always assume that you want to call the getter/setter and perform a method call.
 

== Arrays ==

=== Passing Smalltalk Collections to Java ===

Smalltalk collections can now be directly passed to Java with a few limitations:
* The identity of the Smalltalk collections will not be preserved. passing the same collection to java multiple times will result in multiple instances of the same array on the java side. (to bypass this instantiate a new java array)
* Smalltalk collections need to be explicitly converted to the correct type (e.g. a <CODE>SignedIntegerArray</CODE> on the smalltalk side matches an <CODE>int</CODE>-Array on the java side)

=== Instantiating Arrays ===

The new bridge supports instantiation of arrays (whereas previously reflection had to be used to instantiate arrays from the smalltalk side).
There are two ways an array can be instantiated:

<CODE><PRE>
intArray := (java getJavaClass:'int[]') new:#[ 1 2 3 4 5 ] asSignedIntegerArray. "/ instantiates a new array of type "int" with the contents "1, 2, 3, 4, 5"
</PRE></CODE>

<CODE><PRE>
intArray := (java getJavaClass:'int[]') new:10. "/ instantiates a new empty array of type "int" with 10 elements.
</PRE></CODE>

=== Accessing Arrays ===

To achieve better performance, arrays of primitive types smaller than a certain size have their contents cached on the smalltalk side:
<CODE><PRE>
intArray contents at:1. "/ this will access the first element of the cached contents.
</PRE></CODE>

large arrays are not serialized immediately. large arrays will be serialized when <CODE>contents</CODE> is called the first time.

'''Attention:''' Java arrays are not immutable. changes to an array are not reflected in the cached contents. if an array has been updated, call <CODE>refresh</CODE> on the array to update the cache. arrays will not be updated automatically.

<CODE><PRE>
shortArray := (java getJavaClass:'short[]') new:10. "/ new empty "short" array with 10 elements

"/ copy the contents of the smalltalk collection to the newly instantiated short array
(java getJavaClass:'java.lang.System') arraycopy:(#[ 1 2 3 ] asSignedWordArray) srcPos:0 dest:shortArray destPos:0 length:3.

shortArray at:0. "/ will reflect the changes made to the array

shortArray contents at:1. "/ will still return 0 because the cached contents have not been updated.

shortArray refresh. "/ update the cached contents

shortArray contents at:1. "/ will now correctly reflect the changes made to the array
</PRE></CODE>

== Callbacks from Java ==
Sometimes you may want to execute a piece of Smalltalk code during the execution of the Java code. For example, we may want to install a Smalltalk observer to be notified when a button on a Java GUI was pressed,
or some other callback from a Java framework.

The following code registers a Smalltalk block as a callback for a mouse press event of a button:
<CODE><PRE>
listener := MouseListener new.
listener implementMethod:'mousePressed' as:[ Transcript showCR:'Hello from Java' ].
</PRE></CODE>
The above creates the callback and the listener, which can now be registered on a button:
<CODE><PRE>
button addMouseListener:listener.
</PRE></CODE>
Now, with the press of the button in the Java GUI, the Smalltalk block will be executed and writes <CODE>"Hello from Java"</CODE> to the Smalltalk console.
Of course, any other (Smalltalk-)action code can be made to run via this mechanism.

But be aware, that the callback is possibly called later (when the elementary action, which installed the code, has already finished long ago). Also, as the Java code execution is not synchronized with any of your expecco action execution, the callback may also be called at any arbutrary time, even at times when no activity at all is executed on the expecco side. If you forget to cleanup, and the Java object is still alive, it may even be called after you have finished your test run (if you keep the java bridge handle around and alive, for example in an expecoo environment variable).

So the Smalltalk callback code should not depend on any particular elementary action to be currently running, but instead in most cases write some information into a shared data container, preferably an instance of "SharedQueue", which is thread safe. Then, some other action (an elementary action) would read-wait and read events from that shared queue.

make sure that your test correctly cleans up any such callbacks afterwards. As a last resort, use the "Shutdown Bridge Connection" menu item, which closes the bridge connection, and thereby - as a side effect - removes any leftover callbacks. It does close the connection, and any remaining java proxy object handles become invalid, though.

Another example, using an observer could look like:
<CODE><PRE>
observer := java Observer new.
observer implementMethod:'update'
as:[:sourceObservable :argument|
argument notNil ifTrue:[ Transcript showCR:('I was notifyed with: ',argument toString) ]
ifFalse:[ Transcript showCR:'I was notifyed and the argument was nil' ].
].
myObservable addObserver:observer.
</PRE></CODE>
When the observable calls <CODE>"notifyObservers"</CODE>, the Smalltalk block will be executed.

== Exceptions in Java ==
Exceptions on the Java side are signalled back to the Smalltalk side and raise a corresponding exception there. However, on the Java side, the call stack which lead to the exception has already been unwound at that time (Java exceptions are not proceedable). So a proceed in the Smalltalk-side exception handler only affects the Smalltalk caller, but may leave the Java side in an undefined state.

== Remote Dynamic Code Injection ==
Sometimes we might want to execute code without the overhead of many rpc-messages being sent over the bridge, especially if we want to do something time critical, or want to make execution time measurements.
For this, it is possible to load a class at runtime into the JavaVM. The code of the class will first be sent to the JavaVM, which will compile and load the generated byte code. Then, the class can be accessed via the bridge just like any other preloaded class.

The following example specifies the class code in a smalltalk string and inject the code into the JavaVM. Then an instance of that new class will be instantiated and finally a method of the object instance will be invoked:
<CODE><PRE>
classCode := '
package myPackage.test;

import java.awt.BorderLayout;
import java.awt.event.MouseAdapter;
import java.awt.event.MouseEvent;
import java.util.Calendar;

import javax.swing.JButton;
import javax.swing.JFrame;
import javax.swing.JLabel;;

public class MyInjectedClass {
public void createSampleApp(){
JFrame frame=new JFrame("Hello im injected");
frame.setLayout(new BorderLayout());
JButton button=new JButton("click me");
final JLabel label=new JLabel("Text");
button.addMouseListener(new MouseAdapter() {

@Override
public void mouseClicked(MouseEvent e) {
label.setText(Calendar.getInstance().getTime().toString());
}
});
frame.add(label,BorderLayout.NORTH);
frame.add(button,BorderLayout.SOUTH);
frame.setSize(300, 300);
frame.setVisible(true);
}
}
'.
classObject := java getJavaClass:'myPackage.test.MyInjectedClass' fromSource:classCode.
classObject new createSampleApp.
</PRE></CODE>
After the code has been injected, a new instance of <CODE>"MyInjectedClass"</CODE> is created and the <CODE>"createSampleApp"</CODE> method is called. Because the example implements a GUI, a Java window will open, containing a label and a button. Clicking the button displays the current time in the label.



=== Code Sources for Class injection ===
There are 3 possible types of class code sources which we can use to inject the code. In the examples before we directly used a simple <CODE>"String"</CODE> in the smalltalk code as a code source. We also can use a <CODE>"*.java"</CODE> file as source. Just read the content of the file into a string and use it as in the previous examples.

To inject a <CODE>"*.class"</CODE> file use the following code:
<pre>
java getJavaClass:'the.class.name' fromByteCode:classCode.
</pre>

== Examples ==

This example creates a JFrame with one button inside. Then a Mouselistener is created and registered on the button. When the button is pressed, the title of the window changes to <CODE>"onPressed"</CODE> and the Transcript shows the message <CODE>"onPressed"</CODE>. When the button is released, the title of the window is changed to <CODE>"onReleased"</CODE> and the Transcript shows <CODE>"onReleased"</CODE>. If the button lost the mouse focus, the bridge will exit (disconnect), and the Java side is terminated.
<CODE><PRE>
|java frame button listener|

"/getting a bridge
java := JAVA::JavaBridge newWithServer.

"/creating a new frame and button object
frame := java getJavaClass:'javax.swing.JFrame' new.
button := java JButton new:'Click'.

"/creating a new mouse listener and adding callback blocks
listener := java MouseListener new.

listener implementMethod:'mousePressed' as:[ Transcript showCR:'onPress'. frame setTitle:'onPressed' ].
listener implementMethod:'mouseReleased' as:[ Transcript showCR:'onReleased'. frame setTitle:'onReleased' ].
listener implementMethod:'mouseExited' as:[ Transcript showCR:'onExited'. java closeBridge. ].

"/register the mouse listener on the button and make the frame with button visible
button addMouseListener:listener.
frame add:button.
frame setSize:300 y:100.
frame setVisible: true.
</PRE></CODE>



==Differences between v1 and v2==
===General===
* A Java Bridge instance no longer requires multiple tcp ports to be open. This simplifies connection through ssh tunnels and firewalls.
* The identity of strings and primitve wrappers can now be preserved. (see [[#boxedDo:aBlock | boxedDo]])
* Arrays of primitive types are serialized. (see [[#Arrays | Arrays]])

===Loading Applications===
* '''addJarByPath:''' and '''addToClassPath:''' are still supported but have been deprecated. use '''loadJar:''', '''loadJarByPath:''' and '''loadExtension:''' instead. The new methods no longer require the jar or library to be present on the remote machine.

[[Java Interface Library#Loading Applications (from the expecco side) | v1]] [[#Loading Applications (from the expecco side) | v2]]

===Java Class Access===
* Sending the fully qualified name with instances of "." replaced by "_" to the bridge handle is still supported, but not recommended.
* A new method '''getJavaClass:''' has been introduced (also available for v1 since expecco v2.9). This solves the side effects of "_" being a legal character in class names.

[[Java Interface Library#Java Package Import and Class Access | v1]] [[#Java Class Access | v2]]
===Callbacks from Java===
* A new method '''implementMethod:as:''' has been introduced to assign callback blocks to method names. The old way is still supported.

[[Java Interface Library#Callbacks from Java | v1]] [[#Callbacks from Java | v2]]

===Remote Dynamic Code Injection===
* Code injection was problematic in v1 and has now been re-implemented in v2.

[[#Remote Dynamic Code Injection | v2]]

== API ==
===JAVA::Java===
====class protocol====
=====newWithServer=====
* This will start a local JavaVM, running the JavaBridge, and establishes a connection on a random free port.
: A new connected instance of JAVA::Java class is returned.

=====newWithServerForJavaPath:aJavaPathFilename=====
* This is the same as newWithServer but the path to the java executable can be specified. The JavaVM version must be 1.6 or higher to run the JavaBridge.
:: '''aJavaPathFilename''' - must be a instance of Filename
Smalltalk: JAVA::Java newWithServerForJavaPath:('my\path\to\java.executable'asFilename).
JavaScript: JAVA::Java.newWithServerForJavaPath("my\path\to\java.executable".asFilename());

=====newConnectedTo:aHhostString port:aPortNumber withTimeout:aTimeoutSeconds=====
* This is used to connect to a running JavaBridge on the network. The JavaBridge must be started in server mode on the remote host. After connecting a new connected instance of JAVA::Java is returned.
:: '''aHostString''' - the hostname or IP of the remote machine as String
:: '''aPortNumber ''' - the port on which the remote machine is listening as Number
:: '''aTimeoutSeconds''' - a connect timeout in seconds as Number
Smalltalk: JAVA::Java newConnectedTo:'myHostName' port:4567 withTimeout:30.
JavaScript: JAVA::Java.newConnectedTo_port_withTimeout("myHostName",4567,30);

=====newWaitingForConnectOnHost:aListeningAddressString port:aListeningPortNumber withTimeout:aTimeoutSeconds=====
* This is used to wait for incomming connecions of a running JavaBridge on the network. The JavaBridge must be started in client mode on the remote host. After connecting a new connected instance of JAVA::Java is returned.
:: '''deprecated: aListeningAddressString''' - no longer used. Can be nil.
:: '''aListeningPortNumber ''' - the port on which to listen for incomming connections as Number
:: '''aTimeoutSeconds''' - a connect timeout in seconds as Number, If nil it will wait endless.

=====singletonInstance=====
* This will call newWithServer for the first time and then always returns the same connected JAVA::Java instance until the connection was closed, then a new connected instance is returned.

=====exitAllInstances=====
* This will close all instances of JAVA::Java.

====instance protocol====
=====loadJarByPath:aPath=====
* Adds a jar to the running JavaVM. If the jar depends on other jars or libraries you have to add them too.
:: '''aPath''' - the path to the jar file as String.

=====loadJar:aByteArray=====
* Adds a jar to the running JavaVM. If the jar depends on other jars or libraries you have to add them too.
:: '''aByteArrays''' - a ByteArray containing the JAR file.

=====loadExtension:aPath=====
* Adds a jar to the running JavaVM and caches it for subsequent usages. If the jar depends on other jars you have to add them too.
:: '''aPath''' - the path to the jar file as String.

=====boxedDo:aBlock=====
* Any autoboxed values in aBlock returned from the JavaVM are preserved as such. By default autoboxed values are automatically unboxed. This way, the identity of such objects is preserved.

=====isConnected=====
* Tests if a connection is still established.
:: '''return:''' - true if the connection is still established, else false.

=====isAlive=====
* Tests if a connection is still responding.
:: '''return:''' - true if the connection is still alive, else false. Does a message round trip.

=====closeBridge=====
* This will close the bridge connection. Depending on in which mode the JavaBridge was started, the JavaVM is also closed (-keepAlive startparameter not set).

=====exit=====
* Same as closeBridge.

== See Also==
The [[DOT NET Interface Library| DOTNET Interface Plugin & Library]], which implements a likewise interface for .NET applications/libraries.

<hr>
Back to [[Plugins]]

Java Interface Library v2

2016-06-01T09:26:39Z

Javogel: /* Passing Smalltalk Collections to Java */

== Introduction ==

This article discusses version 2 of the Java Bridge (which is as of expecco v2.9 still experimental).
The article for version 1 can be found [[Java Interface Library | here]].

The Java Interface library ("Java Bridge") is used to interact with Java objects inside an external Java Virtual Machine (JVM).

The access to Java objects, classes and programs is done via a framework called "''Java-Bridge''", which is similar in operation to the [[DOT NET Interface Library| dotNET bridge]]. This framework implements transparent forwarding of method (virtual function) calls to Java objects, which exist in a local or remote Java Virtual Machine (JVM). Also, return values, callBacks and exception information are passed back from the Java program to expecco. This is done by a proxy-object mechanism, which catches all function calls, wraps the arguments, sends a datagram to the other bridge side, awaits the reply and returns the result to the original caller. Thus, remote procedure calls are almost completely transparent to the Smalltalk/JavaScript code inside expecco. In your elementary code, you can write remote function calls as if they were to local objects.

Notice that this document describes the low level framework, which implements the bridge communication. A much easier to use high level interface (called "Groovy Blocks") exists and should normally be used, if you need access to a java application's internals during testing.
Please take a look at
[[Expecco_API#Groovy_Elementary_Blocks | "Groovy Block API"]]
and [[Testing Java Applications using Groovy blocks/en | "Testing Java Applications using Groovy blocks"]].

== Architecture ==

On the expecco side, the bridge consists of a number of Proxy objects,
which behave like regular Smalltalk objects as seen from elementary expecco code.
However, instead of performing an action when one of their methods (virtual functions) is called,
they send a message over a socket connection to the Java VM (actually: to a bridge software inside the
Java application) which decodes the message and sends it to the destination Java object.
The same is done in reverse direction with the return value.

+---------------------+ +----------+ +----------------+ +----------------+ +---------+
| | | | | | | | | Java |
| expecco |---->| Proxy |---->| Bridge |==>>==| Bridge |---->| Object |
| (elementary code) |<----| |<----| (expecco side) |==<<==| (Java side) |<----| |
+---------------------+ +----------+ +----------------+ +----------------+ +---------+

This setup allows for transparent communication with objects inside a local or remote Java VM. This may be either utility functions which happen to be convenient for the test application (for example: file parsing, syntax analysis, protocol implementaitons or access to specific hardware via driver libraries), or the tested application in the system under test itself.

Especially, it allows for the objects of the tested application to be looked into, manipulated and for functions of it or underlying frameworks to be called.

For expecco code, we tried to make this as transparent as possible, however there are a few exceptions, when function names need to be translated (for example, because the function naming syntax is different) or due to the fact that for some operations no corresponding name exists in Smalltalk (array access, for example).

Of course, multiple such connections can coexist and be served/handled in parallel. This enables an expecco test suite to communicate with both sides of a tested client-server Java application, for example.

Notice that a similar mechanism is used in expecco to communicate with DOTNET, Qt (C++) and C applications.

 

== Activating the new Java Bridge ==
To activate the new bridge in expecco navigate to <CODE>Extras -> Settings -> Plugins -> Java Bridge</CODE> and tick the '''Use new Bridge (experimental)''' checkbox.
[[Datei:ActivateNewJavaBridge.png]]

'''Attention:''' Ticking the checkbox will terminate all currently active Bridge connections due to incompatibilities between the new and the old version.

== Initializing / Releasing the Bridge ==

Before any communication can take place between expecco and any Java object, the Java side of the bridge has to be started, and a communication has to be established.
In expecco, all of the bridge classes are found in the <CODE>JAVA</CODE> namespace.

The main interface class is "<CODE>Java</CODE>", in the "<CODE>JAVA</CODE>" namespace:
<CODE><PRE>
java := JAVA::Java newWithServer.
</PRE></CODE>
or (in JavaScript):
<CODE><PRE>
java = JAVA::Java.newWithServer();
</PRE></CODE>

This starts the Java-side of the bridge (actually executes java as a background command) on the local machine, and establishes a connection to that JVM.

The bridge connection should be closed, if the bridge is no longer needed. Release the bridge with:
<CODE><PRE>
java.closeBridge();
</PRE></CODE>
which terminates the connection.

=== Start and Connect to a Remote Machine ===
The above started a Java VM and connected to it. Alternatively, you may want to connect to an already running Java program (typically, your system under test).
In order for your program to be reachable, it must allow for the bridge to connect to it via a special bridge-connection, which is a socket connection. For this, it must execute the server code found in the "JavaBridge.jar" file. To pass [[#Startup Parameters| parameters]] you will typically start it from a command line or a little shell/batch script.

Call (on the shell/cmd level):
$ java -jar <PATH_TO_JAVABRIDGE.JAR> <PARAMETERS>

The "JavaBridge.jar" file is found in the installation directory of expecco at:
\exept\expecco\packages\exept\bridgeFramework\javaBridge\javaBin\JavaBridge.jar

The Javabridge code allows for either side to initiate the connection - i.e. it can be run in server mode,
where it awaits an incoming connection, or in client mode, where it actively initiates a connection.
After connection establishment, there is no difference in the operation of the bridge, however depending on the setup of your network infrastructure, especially firewalls, either mechanism may be easier to be used.

Assuming that the bridge is already running on the remote machine as server (default),
use <CODE>newConnectedTo:port:withTimeout:</CODE> to connect to it from the expecco side:
java := JAVA::Java newConnectedTo:'myHost' port:4567 withTimeout:30.
This will initiate the connection setup from the expecco side.

Alternatively, if started in client mode use <CODE>newWaitingForConnectOnHost:port:withTimeout:</CODE>:
java := JAVA::Java newWaitingForConnectOnHost:'localhost' port:4567 withTimeout:30.
which will open a port on the expecco side, and wait until the Java side connects to it.
[[#JAVA::Java|For more details see API]]

====Startup Parameters====
You can use any parameter in any order.
If no parameter is used then the bridge listenes on port 14014 in server mode without keepAlive.
;<code>-help</code>
* Shows the help

;<code>-ip <aHostnameOrIP></code>
* In client mode this specifies the ip or hostname to connect to. In server mode this specifies the ip or hostname to bind to.

;<code>-port <aPortNumber> </code>
* In client mode this specifies the port to connect to. In server mode this specifies the listening port.

;<code>-asClient</code>
* The bridge will start in client mode. If not set the bridge is started in server mode.

;<code>-keepAlive</code>
* By setting this flag the bridge will not exit after the connection has closed and starts to connect or listen again. Otherwise, it will run for a single connection session only.

== Loading Applications (from the expecco side) ==

Normally, you would start your application with the required command line arguments and include the javabridge as jar there. However, in some situations, it may be required to dynamically load other jars into the connected Java VM.
By accessing a classloader, additional classes, or applications as contained in JAR files can be loaded from the expecco side.

This can be used to add a JAR file to the classloader:
<CODE><PRE>
java loadJarByPath:'pathToJarFile'. "/ assuming "java" is a handle as returned from the above connect
</PRE></CODE>

or, if the JAR file is loaded in memory:
<CODE><PRE>
java loadJar:jarByteArray. "/ where "jarByteArray" is a ByteArray containing the JAR file
</PRE></CODE>

If the JVM is on a remote machine, the path is resolved on the expecco side and the JAR will be transferred to the remote side.

Should transferring the JAR be too much overhead, an additional mechanism is provided:
<CODE><PRE>
java loadExtension:'pathToJarFile'.
</PRE></CODE>
this will cache the JAR file on the bridge side and eliminate the overhead of subsequent invocations.

== Java Class Access ==

This following code sample simply references (i.e. accesses) the class "JFrame" from the <CODE>"javax.swing"</CODE> package. The fully specified class name in Java would be <CODE>"javax.swing.JFrame"</CODE>:
<CODE><PRE>
java getJavaClass:'javax.swing.JFrame'
</PRE></CODE>

Or, if you want to load multiple classes:
<CODE><PRE>
java import:'javax.swing.JFrame' import:'javax.swing.JButton'
do:[:jFrame :jButton | "do something with JButton and JFrame" ].
</PRE></CODE>

v2 also supports dynamic compilation of java source code:
<CODE><PRE>
java getJavaClass:'className' fromSource:'classSource'. "/ where classSource is a String containing valid java source code
</PRE></CODE>

and loading precompiled java bytecode:
<CODE><PRE>
java getJavaClass:'className' fromByteCode:byteCode. "/ where byteCode is a ByteArray containing valid java bytecode
</PRE></CODE>

[[#Remote Dynamic Code Injection | for details see Remote Dynamic Code Injection]]

== Instantiating a Class ==

Object instances are created via the "new"-message, sent to a proxy of a Java class. You can get this proxy as described in the previous section. For example, if we want to create a new instance of a "JFrame" and a "JButton", write:
<CODE><PRE>
frame := java getJavaClass:'javax.swing.JFrame' new.
button := java getJavaClass:'javax.swing.JButton' new.
</PRE></CODE>
The first statement results in a proxy object for the "JFrame" instance. The second line results in a proxy for a new "JButton" object.

== Calling Instance Methods ==

A method call is done by a message send to a proxy object, where the message is the method name to call. For example, to call the <CODE>"setVisible(boolean isVisible)"</CODE> method on the above JFrame object, we send the following message to that proxy:
<CODE><PRE>
frame setVisible:true.
</PRE></CODE>

As method naming is different in Smalltalk and Java, a dynamic translation is applied when sending messages from Smalltalk code to a remote Java object. Smalltalk has arguments embedded inside parts of a so called "keyword" message, such as in "receiver foo:arg1 bar:arg2", where "foo:bar:" would be the message name, and "arg1", "arg2" be the arguments.

In Java, the message name is a single identifier, and arguments are written in an argument list after the message name: "receiver.fooBar(arg1, arg2)".

When message names are translated, only the very first part of the Smalltalk keyword message is taken ("foo" in the above example), and the remaining parts are simpl ignored. Thus, any of the Smalltalk messages "foo:bar:", "foo:xxxx:" and "foo:_:" (a single underscore as second part) all translate to the same Java message name "foo()".

Therefore, to call a method with more than one argument, like <CODE>"setSize(int width,int height)"</CODE> on a JFrame instance we can write:
<CODE><PRE>
frame setSize:300 _:200.
</PRE></CODE>
but just as well:
<CODE><PRE>
frame setSize:300 anyWord:200.
</PRE></CODE>
or any other selector with "setSize:" as its first component.
The selector translation mechanism simply takes the first part as the Java selector.

In practice, you should take a reasonably descriptive name, such as: "frame setSize:300 height:200" or only the Java name as first part, such as "frame setSize:300 _:200".

For a call of a method with 4 arguments, we could write:
<CODE><PRE>
frame setBounds:100 y:50 width:300 height:200.
</PRE></CODE>
or:
<CODE><PRE>
frame setBounds:100 _:50 _:300 _:200.
</PRE></CODE>

Also here the <CODE>"y: width: height:"</CODE> can be named as you want, but the first part must be "setBounds:".

=== Calling Static Methods ===

Calling a static method on an object is not different from calling non static methods. In most cases you will call a static method not on an object but directly on the class. This is done by using the class object as "receiver" of the message. For example, if we want to call the static method <CODE>"isDefaultLookAndFeelDecorated()"</CODE> of the JFrame class, write:
<CODE><PRE>
java getJavaClass:'javax.swing.JFrame' isDefaultLookAndFeelDecorated.
</PRE></CODE>

== Accessing Fields ==

As Smalltalk does not support access of an object's fields from the outside (it is fully encapsulated, and access from outside is ONLY allowed via getters/setters), an additional translation mechanism is provided for field access.

Accessing a field of a Java object or a class's static field uses the same syntax as method calls. To access a field, send a message where the message is the field name. To access the field of a class the field must be static.
For example, to get the value of the static field named <CODE>"EXIT_ON_CLOSE"</CODE> of the "JFrame" class, write
<CODE><PRE>
value := java getJavaClass:'javax.swing.JFrame' EXIT_ON_CLOSE.
</PRE></CODE>
The variable "value" now holds the integer value of the <CODE>"EXIT_ON_CLOSE"</CODE> constant.

Assuming that a "JFrame" object had a field named <CODE>"myField"</CODE>, to access this field, we'd have to write:
<CODE><PRE>
value := frame myField.
</PRE></CODE>
and "value" now holding whatever <CODE>"myField"</CODE> returns. This could be another object reference or any primitive value.

=== Setting Fields ===
To set a field, use a setter-like method call:
<CODE><PRE>
frame myField: newValue.
</PRE></CODE>

=== Name Conflicts ===

In very rare situations, a Java object may contain both a field and a method by the same name.
In this case, the Smalltalk code cannot depend on the dynamic translation mechanism (which actually looks for either a field or method name to match), but instead make it explicit, which operation is wanted:
Use:
<CODE><PRE>
frame getFieldByName:'myField'
</PRE></CODE>
to read a field, and:
<CODE><PRE>
frame setFieldByName:'myField' value:123.
</PRE></CODE>
to write the field.

If there are both fields and methods by the same name, and you use the non-explicit call,
the bridge will always assume that you want to call the getter/setter and perform a method call.
 

== Arrays ==

=== Passing Smalltalk Collections to Java ===

Smalltalk collections can now be directly passed to Java with a few limitations:
* The identity of the Smalltalk collections will not be preserved. passing the same collection to java multiple times will result in multiple instances of the same array on the java side. (to bypass this instantiate a new java array)
* Smalltalk collections need to be explicitly converted to the correct type (e.g. a <CODE>SignedIntegerArray</CODE> on the smalltalk side matches an <CODE>int</CODE>-Array on the java side)

=== Instantiating Arrays ===

The new bridge supports instantiation of arrays (whereas previously reflection had to be used to instantiate arrays from the smalltalk side).
There are two ways an array can be instantiated:

<CODE><PRE>
intArray := (java getJavaClass:'int[]') new:#[ 1 2 3 4 5 ] asSignedIntegerArray. "/ instantiates a new array of type "int" with the contents "1, 2, 3, 4, 5"
</PRE></CODE>

<CODE><PRE>
intArray := (java getJavaClass:'int[]') new:10. "/ instantiates a new empty array of type "int" with 10 elements.
</PRE></CODE>

=== Accessing Arrays ===

To achieve better performance, arrays of primitive types smaller than a certain size have their contents cached on the smalltalk side:
<CODE><PRE>
intArray contents at:1. "/ this will access the first element of the cached contents.
</PRE></CODE>

large arrays are not serialized immediately. large arrays will be serialized when <CODE>contents</CODE> is called the first time.

'''Attention:''' Java arrays are not immutable. changes to an array are not reflected in the cached contents. if an array has been updated, call <CODE>refresh</CODE> on the array to update the cache. arrays will not be updated automatically.

<CODE><PRE>
shortArray := (java getJavaClass:'short[]') new:10. "/ new empty "short" array with 10 elements

"/ copy the contents of the smalltalk collection to the newly instantiated short array
(java getJavaClass:'java.lang.System') arraycopy:(#[ 1 2 3 ] asSignedWordArray) srcPos:0 dest:shortArray destPos:0 length:3.

shortArray at:0. "/ will reflect the changes made to the array

shortArray contents at:1. "/ will still return 0 because the cached contents have not been updated.

shortArray refresh. "/ update the cached contents

shortArray contents at:1. "/ will now correctly reflect the changes made to the array
</PRE></CODE>

== Callbacks from Java ==
Sometimes you may want to execute a piece of Smalltalk code during the execution of the Java code. For example, we may want to install a Smalltalk observer to be notified when a button on a Java GUI was pressed,
or some other callback from a Java framework.

The following code registers a Smalltalk block as a callback for a mouse press event of a button:
<CODE><PRE>
listener := MouseListener new.
listener implementMethod:'mousePressed' as:[ Transcript showCR:'Hello from Java' ].
</PRE></CODE>
The above creates the callback and the listener, which can now be registered on a button:
<CODE><PRE>
button addMouseListener:listener.
</PRE></CODE>
Now, with the press of the button in the Java GUI, the Smalltalk block will be executed and writes <CODE>"Hello from Java"</CODE> to the Smalltalk console.
Of course, any other (Smalltalk-)action code can be made to run via this mechanism.

But be aware, that the callback is possibly called later (when the elementary action, which installed the code, has already finished long ago). Also, as the Java code execution is not synchronized with any of your expecco action execution, the callback may also be called at any arbutrary time, even at times when no activity at all is executed on the expecco side. If you forget to cleanup, and the Java object is still alive, it may even be called after you have finished your test run (if you keep the java bridge handle around and alive, for example in an expecoo environment variable).

So the Smalltalk callback code should not depend on any particular elementary action to be currently running, but instead in most cases write some information into a shared data container, preferably an instance of "SharedQueue", which is thread safe. Then, some other action (an elementary action) would read-wait and read events from that shared queue.

make sure that your test correctly cleans up any such callbacks afterwards. As a last resort, use the "Shutdown Bridge Connection" menu item, which closes the bridge connection, and thereby - as a side effect - removes any leftover callbacks. It does close the connection, and any remaining java proxy object handles become invalid, though.

Another example, using an observer could look like:
<CODE><PRE>
observer := java Observer new.
observer implementMethod:'update'
as:[:sourceObservable :argument|
argument notNil ifTrue:[ Transcript showCR:('I was notifyed with: ',argument toString) ]
ifFalse:[ Transcript showCR:'I was notifyed and the argument was nil' ].
].
myObservable addObserver:observer.
</PRE></CODE>
When the observable calls <CODE>"notifyObservers"</CODE>, the Smalltalk block will be executed.

== Exceptions in Java ==
Exceptions on the Java side are signalled back to the Smalltalk side and raise a corresponding exception there. However, on the Java side, the call stack which lead to the exception has already been unwound at that time (Java exceptions are not proceedable). So a proceed in the Smalltalk-side exception handler only affects the Smalltalk caller, but may leave the Java side in an undefined state.

== Remote Dynamic Code Injection ==
Sometimes we might want to execute code without the overhead of many rpc-messages being sent over the bridge, especially if we want to do something time critical, or want to make execution time measurements.
For this, it is possible to load a class at runtime into the JavaVM. The code of the class will first be sent to the JavaVM, which will compile and load the generated byte code. Then, the class can be accessed via the bridge just like any other preloaded class.

The following example specifies the class code in a smalltalk string and inject the code into the JavaVM. Then an instance of that new class will be instantiated and finally a method of the object instance will be invoked:
<CODE><PRE>
classCode := '
package myPackage.test;

import java.awt.BorderLayout;
import java.awt.event.MouseAdapter;
import java.awt.event.MouseEvent;
import java.util.Calendar;

import javax.swing.JButton;
import javax.swing.JFrame;
import javax.swing.JLabel;;

public class MyInjectedClass {
public void createSampleApp(){
JFrame frame=new JFrame("Hello im injected");
frame.setLayout(new BorderLayout());
JButton button=new JButton("click me");
final JLabel label=new JLabel("Text");
button.addMouseListener(new MouseAdapter() {

@Override
public void mouseClicked(MouseEvent e) {
label.setText(Calendar.getInstance().getTime().toString());
}
});
frame.add(label,BorderLayout.NORTH);
frame.add(button,BorderLayout.SOUTH);
frame.setSize(300, 300);
frame.setVisible(true);
}
}
'.
classObject := java getJavaClass:'myPackage.test.MyInjectedClass' fromSource:classCode.
classObject new createSampleApp.
</PRE></CODE>
After the code has been injected, a new instance of <CODE>"MyInjectedClass"</CODE> is created and the <CODE>"createSampleApp"</CODE> method is called. Because the example implements a GUI, a Java window will open, containing a label and a button. Clicking the button displays the current time in the label.



=== Code Sources for Class injection ===
There are 3 possible types of class code sources which we can use to inject the code. In the examples before we directly used a simple <CODE>"String"</CODE> in the smalltalk code as a code source. We also can use a <CODE>"*.java"</CODE> file as source. Just read the content of the file into a string and use it as in the previous examples.

To inject a <CODE>"*.class"</CODE> file use the following code:
<pre>
java getJavaClass:'the.class.name' fromByteCode:classCode.
</pre>

== Examples ==

This example creates a JFrame with one button inside. Then a Mouselistener is created and registered on the button. When the button is pressed, the title of the window changes to <CODE>"onPressed"</CODE> and the Transcript shows the message <CODE>"onPressed"</CODE>. When the button is released, the title of the window is changed to <CODE>"onReleased"</CODE> and the Transcript shows <CODE>"onReleased"</CODE>. If the button lost the mouse focus, the bridge will exit (disconnect), and the Java side is terminated.
<CODE><PRE>
|java frame button listener|

"/getting a bridge
java := JAVA::JavaBridge newWithServer.

"/creating a new frame and button object
frame := java getJavaClass:'javax.swing.JFrame' new.
button := java JButton new:'Click'.

"/creating a new mouse listener and adding callback blocks
listener := java MouseListener new.

listener implementMethod:'mousePressed' as:[ Transcript showCR:'onPress'. frame setTitle:'onPressed' ].
listener implementMethod:'mouseReleased' as:[ Transcript showCR:'onReleased'. frame setTitle:'onReleased' ].
listener implementMethod:'mouseExited' as:[ Transcript showCR:'onExited'. java closeBridge. ].

"/register the mouse listener on the button and make the frame with button visible
button addMouseListener:listener.
frame add:button.
frame setSize:300 y:100.
frame setVisible: true.
</PRE></CODE>



==Differences between v1 and v2==
===General===
* A Java Bridge instance no longer requires multiple tcp ports to be open. This simplifies connection through ssh tunnels and firewalls.
* The identity of strings and primitve wrappers can be preserved. (see [[#boxedDo:aBlock | boxedDo]])
* Arrays of primitive types are serialized. (see [[#Arrays | Arrays]])

===Loading Applications===
* '''addJarByPath:''' and '''addToClassPath:''' are still supported but have been deprecated. use '''loadJar:''', '''loadJarByPath:''' and '''loadExtension:''' instead. The new methods no longer require the jar or library to be present on the remote machine.

[[Java Interface Library#Loading Applications (from the expecco side) | v1]] [[#Loading Applications (from the expecco side) | v2]]

===Java Class Access===
* Sending the fully qualified name with instances of "." replaced by "_" to the bridge handle is still supported, but not recommended.
* A new method '''getJavaClass:''' has been introduced (also available for v1 since expecco v2.9). This solves the side effects of "_" being a legal character in class names.

[[Java Interface Library#Java Package Import and Class Access | v1]] [[#Java Class Access | v2]]
===Callbacks from Java===
* A new method '''implementMethod:as:''' has been introduced to assign callback blocks to method names. The old way is still supported.

[[Java Interface Library#Callbacks from Java | v1]] [[#Callbacks from Java | v2]]

===Remote Dynamic Code Injection===
* Code injection was problematic in v1 and has now been re-implemented in v2.

[[#Remote Dynamic Code Injection | v2]]

== API ==
===JAVA::Java===
====class protocol====
=====newWithServer=====
* This will start a local JavaVM, running the JavaBridge, and establishes a connection on a random free port.
: A new connected instance of JAVA::Java class is returned.

=====newWithServerForJavaPath:aJavaPathFilename=====
* This is the same as newWithServer but the path to the java executable can be specified. The JavaVM version must be 1.6 or higher to run the JavaBridge.
:: '''aJavaPathFilename''' - must be a instance of Filename
Smalltalk: JAVA::Java newWithServerForJavaPath:('my\path\to\java.executable'asFilename).
JavaScript: JAVA::Java.newWithServerForJavaPath("my\path\to\java.executable".asFilename());

=====newConnectedTo:aHhostString port:aPortNumber withTimeout:aTimeoutSeconds=====
* This is used to connect to a running JavaBridge on the network. The JavaBridge must be started in server mode on the remote host. After connecting a new connected instance of JAVA::Java is returned.
:: '''aHostString''' - the hostname or IP of the remote machine as String
:: '''aPortNumber ''' - the port on which the remote machine is listening as Number
:: '''aTimeoutSeconds''' - a connect timeout in seconds as Number
Smalltalk: JAVA::Java newConnectedTo:'myHostName' port:4567 withTimeout:30.
JavaScript: JAVA::Java.newConnectedTo_port_withTimeout("myHostName",4567,30);

=====newWaitingForConnectOnHost:aListeningAddressString port:aListeningPortNumber withTimeout:aTimeoutSeconds=====
* This is used to wait for incomming connecions of a running JavaBridge on the network. The JavaBridge must be started in client mode on the remote host. After connecting a new connected instance of JAVA::Java is returned.
:: '''deprecated: aListeningAddressString''' - no longer used. Can be nil.
:: '''aListeningPortNumber ''' - the port on which to listen for incomming connections as Number
:: '''aTimeoutSeconds''' - a connect timeout in seconds as Number, If nil it will wait endless.

=====singletonInstance=====
* This will call newWithServer for the first time and then always returns the same connected JAVA::Java instance until the connection was closed, then a new connected instance is returned.

=====exitAllInstances=====
* This will close all instances of JAVA::Java.

====instance protocol====
=====loadJarByPath:aPath=====
* Adds a jar to the running JavaVM. If the jar depends on other jars or libraries you have to add them too.
:: '''aPath''' - the path to the jar file as String.

=====loadJar:aByteArray=====
* Adds a jar to the running JavaVM. If the jar depends on other jars or libraries you have to add them too.
:: '''aByteArrays''' - a ByteArray containing the JAR file.

=====loadExtension:aPath=====
* Adds a jar to the running JavaVM and caches it for subsequent usages. If the jar depends on other jars you have to add them too.
:: '''aPath''' - the path to the jar file as String.

=====boxedDo:aBlock=====
* Any autoboxed values in aBlock returned from the JavaVM are preserved as such. By default autoboxed values are automatically unboxed. This way, the identity of such objects is preserved.

=====isConnected=====
* Tests if a connection is still established.
:: '''return:''' - true if the connection is still established, else false.

=====isAlive=====
* Tests if a connection is still responding.
:: '''return:''' - true if the connection is still alive, else false. Does a message round trip.

=====closeBridge=====
* This will close the bridge connection. Depending on in which mode the JavaBridge was started, the JavaVM is also closed (-keepAlive startparameter not set).

=====exit=====
* Same as closeBridge.

== See Also==
The [[DOT NET Interface Library| DOTNET Interface Plugin & Library]], which implements a likewise interface for .NET applications/libraries.

<hr>
Back to [[Plugins]]

Java Interface Library v2

2016-06-01T09:23:30Z

Javogel: /* Accessing Arrays */

== Introduction ==

This article discusses version 2 of the Java Bridge (which is as of expecco v2.9 still experimental).
The article for version 1 can be found [[Java Interface Library | here]].

The Java Interface library ("Java Bridge") is used to interact with Java objects inside an external Java Virtual Machine (JVM).

The access to Java objects, classes and programs is done via a framework called "''Java-Bridge''", which is similar in operation to the [[DOT NET Interface Library| dotNET bridge]]. This framework implements transparent forwarding of method (virtual function) calls to Java objects, which exist in a local or remote Java Virtual Machine (JVM). Also, return values, callBacks and exception information are passed back from the Java program to expecco. This is done by a proxy-object mechanism, which catches all function calls, wraps the arguments, sends a datagram to the other bridge side, awaits the reply and returns the result to the original caller. Thus, remote procedure calls are almost completely transparent to the Smalltalk/JavaScript code inside expecco. In your elementary code, you can write remote function calls as if they were to local objects.

Notice that this document describes the low level framework, which implements the bridge communication. A much easier to use high level interface (called "Groovy Blocks") exists and should normally be used, if you need access to a java application's internals during testing.
Please take a look at
[[Expecco_API#Groovy_Elementary_Blocks | "Groovy Block API"]]
and [[Testing Java Applications using Groovy blocks/en | "Testing Java Applications using Groovy blocks"]].

== Architecture ==

On the expecco side, the bridge consists of a number of Proxy objects,
which behave like regular Smalltalk objects as seen from elementary expecco code.
However, instead of performing an action when one of their methods (virtual functions) is called,
they send a message over a socket connection to the Java VM (actually: to a bridge software inside the
Java application) which decodes the message and sends it to the destination Java object.
The same is done in reverse direction with the return value.

+---------------------+ +----------+ +----------------+ +----------------+ +---------+
| | | | | | | | | Java |
| expecco |---->| Proxy |---->| Bridge |==>>==| Bridge |---->| Object |
| (elementary code) |<----| |<----| (expecco side) |==<<==| (Java side) |<----| |
+---------------------+ +----------+ +----------------+ +----------------+ +---------+

This setup allows for transparent communication with objects inside a local or remote Java VM. This may be either utility functions which happen to be convenient for the test application (for example: file parsing, syntax analysis, protocol implementaitons or access to specific hardware via driver libraries), or the tested application in the system under test itself.

Especially, it allows for the objects of the tested application to be looked into, manipulated and for functions of it or underlying frameworks to be called.

For expecco code, we tried to make this as transparent as possible, however there are a few exceptions, when function names need to be translated (for example, because the function naming syntax is different) or due to the fact that for some operations no corresponding name exists in Smalltalk (array access, for example).

Of course, multiple such connections can coexist and be served/handled in parallel. This enables an expecco test suite to communicate with both sides of a tested client-server Java application, for example.

Notice that a similar mechanism is used in expecco to communicate with DOTNET, Qt (C++) and C applications.

 

== Activating the new Java Bridge ==
To activate the new bridge in expecco navigate to <CODE>Extras -> Settings -> Plugins -> Java Bridge</CODE> and tick the '''Use new Bridge (experimental)''' checkbox.
[[Datei:ActivateNewJavaBridge.png]]

'''Attention:''' Ticking the checkbox will terminate all currently active Bridge connections due to incompatibilities between the new and the old version.

== Initializing / Releasing the Bridge ==

Before any communication can take place between expecco and any Java object, the Java side of the bridge has to be started, and a communication has to be established.
In expecco, all of the bridge classes are found in the <CODE>JAVA</CODE> namespace.

The main interface class is "<CODE>Java</CODE>", in the "<CODE>JAVA</CODE>" namespace:
<CODE><PRE>
java := JAVA::Java newWithServer.
</PRE></CODE>
or (in JavaScript):
<CODE><PRE>
java = JAVA::Java.newWithServer();
</PRE></CODE>

This starts the Java-side of the bridge (actually executes java as a background command) on the local machine, and establishes a connection to that JVM.

The bridge connection should be closed, if the bridge is no longer needed. Release the bridge with:
<CODE><PRE>
java.closeBridge();
</PRE></CODE>
which terminates the connection.

=== Start and Connect to a Remote Machine ===
The above started a Java VM and connected to it. Alternatively, you may want to connect to an already running Java program (typically, your system under test).
In order for your program to be reachable, it must allow for the bridge to connect to it via a special bridge-connection, which is a socket connection. For this, it must execute the server code found in the "JavaBridge.jar" file. To pass [[#Startup Parameters| parameters]] you will typically start it from a command line or a little shell/batch script.

Call (on the shell/cmd level):
$ java -jar <PATH_TO_JAVABRIDGE.JAR> <PARAMETERS>

The "JavaBridge.jar" file is found in the installation directory of expecco at:
\exept\expecco\packages\exept\bridgeFramework\javaBridge\javaBin\JavaBridge.jar

The Javabridge code allows for either side to initiate the connection - i.e. it can be run in server mode,
where it awaits an incoming connection, or in client mode, where it actively initiates a connection.
After connection establishment, there is no difference in the operation of the bridge, however depending on the setup of your network infrastructure, especially firewalls, either mechanism may be easier to be used.

Assuming that the bridge is already running on the remote machine as server (default),
use <CODE>newConnectedTo:port:withTimeout:</CODE> to connect to it from the expecco side:
java := JAVA::Java newConnectedTo:'myHost' port:4567 withTimeout:30.
This will initiate the connection setup from the expecco side.

Alternatively, if started in client mode use <CODE>newWaitingForConnectOnHost:port:withTimeout:</CODE>:
java := JAVA::Java newWaitingForConnectOnHost:'localhost' port:4567 withTimeout:30.
which will open a port on the expecco side, and wait until the Java side connects to it.
[[#JAVA::Java|For more details see API]]

====Startup Parameters====
You can use any parameter in any order.
If no parameter is used then the bridge listenes on port 14014 in server mode without keepAlive.
;<code>-help</code>
* Shows the help

;<code>-ip <aHostnameOrIP></code>
* In client mode this specifies the ip or hostname to connect to. In server mode this specifies the ip or hostname to bind to.

;<code>-port <aPortNumber> </code>
* In client mode this specifies the port to connect to. In server mode this specifies the listening port.

;<code>-asClient</code>
* The bridge will start in client mode. If not set the bridge is started in server mode.

;<code>-keepAlive</code>
* By setting this flag the bridge will not exit after the connection has closed and starts to connect or listen again. Otherwise, it will run for a single connection session only.

== Loading Applications (from the expecco side) ==

Normally, you would start your application with the required command line arguments and include the javabridge as jar there. However, in some situations, it may be required to dynamically load other jars into the connected Java VM.
By accessing a classloader, additional classes, or applications as contained in JAR files can be loaded from the expecco side.

This can be used to add a JAR file to the classloader:
<CODE><PRE>
java loadJarByPath:'pathToJarFile'. "/ assuming "java" is a handle as returned from the above connect
</PRE></CODE>

or, if the JAR file is loaded in memory:
<CODE><PRE>
java loadJar:jarByteArray. "/ where "jarByteArray" is a ByteArray containing the JAR file
</PRE></CODE>

If the JVM is on a remote machine, the path is resolved on the expecco side and the JAR will be transferred to the remote side.

Should transferring the JAR be too much overhead, an additional mechanism is provided:
<CODE><PRE>
java loadExtension:'pathToJarFile'.
</PRE></CODE>
this will cache the JAR file on the bridge side and eliminate the overhead of subsequent invocations.

== Java Class Access ==

This following code sample simply references (i.e. accesses) the class "JFrame" from the <CODE>"javax.swing"</CODE> package. The fully specified class name in Java would be <CODE>"javax.swing.JFrame"</CODE>:
<CODE><PRE>
java getJavaClass:'javax.swing.JFrame'
</PRE></CODE>

Or, if you want to load multiple classes:
<CODE><PRE>
java import:'javax.swing.JFrame' import:'javax.swing.JButton'
do:[:jFrame :jButton | "do something with JButton and JFrame" ].
</PRE></CODE>

v2 also supports dynamic compilation of java source code:
<CODE><PRE>
java getJavaClass:'className' fromSource:'classSource'. "/ where classSource is a String containing valid java source code
</PRE></CODE>

and loading precompiled java bytecode:
<CODE><PRE>
java getJavaClass:'className' fromByteCode:byteCode. "/ where byteCode is a ByteArray containing valid java bytecode
</PRE></CODE>

[[#Remote Dynamic Code Injection | for details see Remote Dynamic Code Injection]]

== Instantiating a Class ==

Object instances are created via the "new"-message, sent to a proxy of a Java class. You can get this proxy as described in the previous section. For example, if we want to create a new instance of a "JFrame" and a "JButton", write:
<CODE><PRE>
frame := java getJavaClass:'javax.swing.JFrame' new.
button := java getJavaClass:'javax.swing.JButton' new.
</PRE></CODE>
The first statement results in a proxy object for the "JFrame" instance. The second line results in a proxy for a new "JButton" object.

== Calling Instance Methods ==

A method call is done by a message send to a proxy object, where the message is the method name to call. For example, to call the <CODE>"setVisible(boolean isVisible)"</CODE> method on the above JFrame object, we send the following message to that proxy:
<CODE><PRE>
frame setVisible:true.
</PRE></CODE>

As method naming is different in Smalltalk and Java, a dynamic translation is applied when sending messages from Smalltalk code to a remote Java object. Smalltalk has arguments embedded inside parts of a so called "keyword" message, such as in "receiver foo:arg1 bar:arg2", where "foo:bar:" would be the message name, and "arg1", "arg2" be the arguments.

In Java, the message name is a single identifier, and arguments are written in an argument list after the message name: "receiver.fooBar(arg1, arg2)".

When message names are translated, only the very first part of the Smalltalk keyword message is taken ("foo" in the above example), and the remaining parts are simpl ignored. Thus, any of the Smalltalk messages "foo:bar:", "foo:xxxx:" and "foo:_:" (a single underscore as second part) all translate to the same Java message name "foo()".

Therefore, to call a method with more than one argument, like <CODE>"setSize(int width,int height)"</CODE> on a JFrame instance we can write:
<CODE><PRE>
frame setSize:300 _:200.
</PRE></CODE>
but just as well:
<CODE><PRE>
frame setSize:300 anyWord:200.
</PRE></CODE>
or any other selector with "setSize:" as its first component.
The selector translation mechanism simply takes the first part as the Java selector.

In practice, you should take a reasonably descriptive name, such as: "frame setSize:300 height:200" or only the Java name as first part, such as "frame setSize:300 _:200".

For a call of a method with 4 arguments, we could write:
<CODE><PRE>
frame setBounds:100 y:50 width:300 height:200.
</PRE></CODE>
or:
<CODE><PRE>
frame setBounds:100 _:50 _:300 _:200.
</PRE></CODE>

Also here the <CODE>"y: width: height:"</CODE> can be named as you want, but the first part must be "setBounds:".

=== Calling Static Methods ===

Calling a static method on an object is not different from calling non static methods. In most cases you will call a static method not on an object but directly on the class. This is done by using the class object as "receiver" of the message. For example, if we want to call the static method <CODE>"isDefaultLookAndFeelDecorated()"</CODE> of the JFrame class, write:
<CODE><PRE>
java getJavaClass:'javax.swing.JFrame' isDefaultLookAndFeelDecorated.
</PRE></CODE>

== Accessing Fields ==

As Smalltalk does not support access of an object's fields from the outside (it is fully encapsulated, and access from outside is ONLY allowed via getters/setters), an additional translation mechanism is provided for field access.

Accessing a field of a Java object or a class's static field uses the same syntax as method calls. To access a field, send a message where the message is the field name. To access the field of a class the field must be static.
For example, to get the value of the static field named <CODE>"EXIT_ON_CLOSE"</CODE> of the "JFrame" class, write
<CODE><PRE>
value := java getJavaClass:'javax.swing.JFrame' EXIT_ON_CLOSE.
</PRE></CODE>
The variable "value" now holds the integer value of the <CODE>"EXIT_ON_CLOSE"</CODE> constant.

Assuming that a "JFrame" object had a field named <CODE>"myField"</CODE>, to access this field, we'd have to write:
<CODE><PRE>
value := frame myField.
</PRE></CODE>
and "value" now holding whatever <CODE>"myField"</CODE> returns. This could be another object reference or any primitive value.

=== Setting Fields ===
To set a field, use a setter-like method call:
<CODE><PRE>
frame myField: newValue.
</PRE></CODE>

=== Name Conflicts ===

In very rare situations, a Java object may contain both a field and a method by the same name.
In this case, the Smalltalk code cannot depend on the dynamic translation mechanism (which actually looks for either a field or method name to match), but instead make it explicit, which operation is wanted:
Use:
<CODE><PRE>
frame getFieldByName:'myField'
</PRE></CODE>
to read a field, and:
<CODE><PRE>
frame setFieldByName:'myField' value:123.
</PRE></CODE>
to write the field.

If there are both fields and methods by the same name, and you use the non-explicit call,
the bridge will always assume that you want to call the getter/setter and perform a method call.
 

== Arrays ==

=== Passing Smalltalk Collections to Java ===

Smalltalk collections can now be directly passed to Java with a few limitations:
* The identity of the Smalltalk collections will not be preserved. passing the same collection to java multiple times will result in multiple instances of the same array on the java side. (to bypass this instantiate a new java array)
* Smalltalk collections need to be explicitly converted to the correct type (e.g. a <CODE>SignedIntegerArray</CODE> on the smalltal side matches an <CODE>int</CODE>-Array on the java side)

=== Instantiating Arrays ===

The new bridge supports instantiation of arrays (whereas previously reflection had to be used to instantiate arrays from the smalltalk side).
There are two ways an array can be instantiated:

<CODE><PRE>
intArray := (java getJavaClass:'int[]') new:#[ 1 2 3 4 5 ] asSignedIntegerArray. "/ instantiates a new array of type "int" with the contents "1, 2, 3, 4, 5"
</PRE></CODE>

<CODE><PRE>
intArray := (java getJavaClass:'int[]') new:10. "/ instantiates a new empty array of type "int" with 10 elements.
</PRE></CODE>

=== Accessing Arrays ===

To achieve better performance, arrays of primitive types smaller than a certain size have their contents cached on the smalltalk side:
<CODE><PRE>
intArray contents at:1. "/ this will access the first element of the cached contents.
</PRE></CODE>

large arrays are not serialized immediately. large arrays will be serialized when <CODE>contents</CODE> is called the first time.

'''Attention:''' Java arrays are not immutable. changes to an array are not reflected in the cached contents. if an array has been updated, call <CODE>refresh</CODE> on the array to update the cache. arrays will not be updated automatically.

<CODE><PRE>
shortArray := (java getJavaClass:'short[]') new:10. "/ new empty "short" array with 10 elements

"/ copy the contents of the smalltalk collection to the newly instantiated short array
(java getJavaClass:'java.lang.System') arraycopy:(#[ 1 2 3 ] asSignedWordArray) srcPos:0 dest:shortArray destPos:0 length:3.

shortArray at:0. "/ will reflect the changes made to the array

shortArray contents at:1. "/ will still return 0 because the cached contents have not been updated.

shortArray refresh. "/ update the cached contents

shortArray contents at:1. "/ will now correctly reflect the changes made to the array
</PRE></CODE>

== Callbacks from Java ==
Sometimes you may want to execute a piece of Smalltalk code during the execution of the Java code. For example, we may want to install a Smalltalk observer to be notified when a button on a Java GUI was pressed,
or some other callback from a Java framework.

The following code registers a Smalltalk block as a callback for a mouse press event of a button:
<CODE><PRE>
listener := MouseListener new.
listener implementMethod:'mousePressed' as:[ Transcript showCR:'Hello from Java' ].
</PRE></CODE>
The above creates the callback and the listener, which can now be registered on a button:
<CODE><PRE>
button addMouseListener:listener.
</PRE></CODE>
Now, with the press of the button in the Java GUI, the Smalltalk block will be executed and writes <CODE>"Hello from Java"</CODE> to the Smalltalk console.
Of course, any other (Smalltalk-)action code can be made to run via this mechanism.

But be aware, that the callback is possibly called later (when the elementary action, which installed the code, has already finished long ago). Also, as the Java code execution is not synchronized with any of your expecco action execution, the callback may also be called at any arbutrary time, even at times when no activity at all is executed on the expecco side. If you forget to cleanup, and the Java object is still alive, it may even be called after you have finished your test run (if you keep the java bridge handle around and alive, for example in an expecoo environment variable).

So the Smalltalk callback code should not depend on any particular elementary action to be currently running, but instead in most cases write some information into a shared data container, preferably an instance of "SharedQueue", which is thread safe. Then, some other action (an elementary action) would read-wait and read events from that shared queue.

make sure that your test correctly cleans up any such callbacks afterwards. As a last resort, use the "Shutdown Bridge Connection" menu item, which closes the bridge connection, and thereby - as a side effect - removes any leftover callbacks. It does close the connection, and any remaining java proxy object handles become invalid, though.

Another example, using an observer could look like:
<CODE><PRE>
observer := java Observer new.
observer implementMethod:'update'
as:[:sourceObservable :argument|
argument notNil ifTrue:[ Transcript showCR:('I was notifyed with: ',argument toString) ]
ifFalse:[ Transcript showCR:'I was notifyed and the argument was nil' ].
].
myObservable addObserver:observer.
</PRE></CODE>
When the observable calls <CODE>"notifyObservers"</CODE>, the Smalltalk block will be executed.

== Exceptions in Java ==
Exceptions on the Java side are signalled back to the Smalltalk side and raise a corresponding exception there. However, on the Java side, the call stack which lead to the exception has already been unwound at that time (Java exceptions are not proceedable). So a proceed in the Smalltalk-side exception handler only affects the Smalltalk caller, but may leave the Java side in an undefined state.

== Remote Dynamic Code Injection ==
Sometimes we might want to execute code without the overhead of many rpc-messages being sent over the bridge, especially if we want to do something time critical, or want to make execution time measurements.
For this, it is possible to load a class at runtime into the JavaVM. The code of the class will first be sent to the JavaVM, which will compile and load the generated byte code. Then, the class can be accessed via the bridge just like any other preloaded class.

The following example specifies the class code in a smalltalk string and inject the code into the JavaVM. Then an instance of that new class will be instantiated and finally a method of the object instance will be invoked:
<CODE><PRE>
classCode := '
package myPackage.test;

import java.awt.BorderLayout;
import java.awt.event.MouseAdapter;
import java.awt.event.MouseEvent;
import java.util.Calendar;

import javax.swing.JButton;
import javax.swing.JFrame;
import javax.swing.JLabel;;

public class MyInjectedClass {
public void createSampleApp(){
JFrame frame=new JFrame("Hello im injected");
frame.setLayout(new BorderLayout());
JButton button=new JButton("click me");
final JLabel label=new JLabel("Text");
button.addMouseListener(new MouseAdapter() {

@Override
public void mouseClicked(MouseEvent e) {
label.setText(Calendar.getInstance().getTime().toString());
}
});
frame.add(label,BorderLayout.NORTH);
frame.add(button,BorderLayout.SOUTH);
frame.setSize(300, 300);
frame.setVisible(true);
}
}
'.
classObject := java getJavaClass:'myPackage.test.MyInjectedClass' fromSource:classCode.
classObject new createSampleApp.
</PRE></CODE>
After the code has been injected, a new instance of <CODE>"MyInjectedClass"</CODE> is created and the <CODE>"createSampleApp"</CODE> method is called. Because the example implements a GUI, a Java window will open, containing a label and a button. Clicking the button displays the current time in the label.



=== Code Sources for Class injection ===
There are 3 possible types of class code sources which we can use to inject the code. In the examples before we directly used a simple <CODE>"String"</CODE> in the smalltalk code as a code source. We also can use a <CODE>"*.java"</CODE> file as source. Just read the content of the file into a string and use it as in the previous examples.

To inject a <CODE>"*.class"</CODE> file use the following code:
<pre>
java getJavaClass:'the.class.name' fromByteCode:classCode.
</pre>

== Examples ==

This example creates a JFrame with one button inside. Then a Mouselistener is created and registered on the button. When the button is pressed, the title of the window changes to <CODE>"onPressed"</CODE> and the Transcript shows the message <CODE>"onPressed"</CODE>. When the button is released, the title of the window is changed to <CODE>"onReleased"</CODE> and the Transcript shows <CODE>"onReleased"</CODE>. If the button lost the mouse focus, the bridge will exit (disconnect), and the Java side is terminated.
<CODE><PRE>
|java frame button listener|

"/getting a bridge
java := JAVA::JavaBridge newWithServer.

"/creating a new frame and button object
frame := java getJavaClass:'javax.swing.JFrame' new.
button := java JButton new:'Click'.

"/creating a new mouse listener and adding callback blocks
listener := java MouseListener new.

listener implementMethod:'mousePressed' as:[ Transcript showCR:'onPress'. frame setTitle:'onPressed' ].
listener implementMethod:'mouseReleased' as:[ Transcript showCR:'onReleased'. frame setTitle:'onReleased' ].
listener implementMethod:'mouseExited' as:[ Transcript showCR:'onExited'. java closeBridge. ].

"/register the mouse listener on the button and make the frame with button visible
button addMouseListener:listener.
frame add:button.
frame setSize:300 y:100.
frame setVisible: true.
</PRE></CODE>



==Differences between v1 and v2==
===General===
* A Java Bridge instance no longer requires multiple tcp ports to be open. This simplifies connection through ssh tunnels and firewalls.
* The identity of strings and primitve wrappers can be preserved. (see [[#boxedDo:aBlock | boxedDo]])
* Arrays of primitive types are serialized. (see [[#Arrays | Arrays]])

===Loading Applications===
* '''addJarByPath:''' and '''addToClassPath:''' are still supported but have been deprecated. use '''loadJar:''', '''loadJarByPath:''' and '''loadExtension:''' instead. The new methods no longer require the jar or library to be present on the remote machine.

[[Java Interface Library#Loading Applications (from the expecco side) | v1]] [[#Loading Applications (from the expecco side) | v2]]

===Java Class Access===
* Sending the fully qualified name with instances of "." replaced by "_" to the bridge handle is still supported, but not recommended.
* A new method '''getJavaClass:''' has been introduced (also available for v1 since expecco v2.9). This solves the side effects of "_" being a legal character in class names.

[[Java Interface Library#Java Package Import and Class Access | v1]] [[#Java Class Access | v2]]
===Callbacks from Java===
* A new method '''implementMethod:as:''' has been introduced to assign callback blocks to method names. The old way is still supported.

[[Java Interface Library#Callbacks from Java | v1]] [[#Callbacks from Java | v2]]

===Remote Dynamic Code Injection===
* Code injection was problematic in v1 and has now been re-implemented in v2.

[[#Remote Dynamic Code Injection | v2]]

== API ==
===JAVA::Java===
====class protocol====
=====newWithServer=====
* This will start a local JavaVM, running the JavaBridge, and establishes a connection on a random free port.
: A new connected instance of JAVA::Java class is returned.

=====newWithServerForJavaPath:aJavaPathFilename=====
* This is the same as newWithServer but the path to the java executable can be specified. The JavaVM version must be 1.6 or higher to run the JavaBridge.
:: '''aJavaPathFilename''' - must be a instance of Filename
Smalltalk: JAVA::Java newWithServerForJavaPath:('my\path\to\java.executable'asFilename).
JavaScript: JAVA::Java.newWithServerForJavaPath("my\path\to\java.executable".asFilename());

=====newConnectedTo:aHhostString port:aPortNumber withTimeout:aTimeoutSeconds=====
* This is used to connect to a running JavaBridge on the network. The JavaBridge must be started in server mode on the remote host. After connecting a new connected instance of JAVA::Java is returned.
:: '''aHostString''' - the hostname or IP of the remote machine as String
:: '''aPortNumber ''' - the port on which the remote machine is listening as Number
:: '''aTimeoutSeconds''' - a connect timeout in seconds as Number
Smalltalk: JAVA::Java newConnectedTo:'myHostName' port:4567 withTimeout:30.
JavaScript: JAVA::Java.newConnectedTo_port_withTimeout("myHostName",4567,30);

=====newWaitingForConnectOnHost:aListeningAddressString port:aListeningPortNumber withTimeout:aTimeoutSeconds=====
* This is used to wait for incomming connecions of a running JavaBridge on the network. The JavaBridge must be started in client mode on the remote host. After connecting a new connected instance of JAVA::Java is returned.
:: '''deprecated: aListeningAddressString''' - no longer used. Can be nil.
:: '''aListeningPortNumber ''' - the port on which to listen for incomming connections as Number
:: '''aTimeoutSeconds''' - a connect timeout in seconds as Number, If nil it will wait endless.

=====singletonInstance=====
* This will call newWithServer for the first time and then always returns the same connected JAVA::Java instance until the connection was closed, then a new connected instance is returned.

=====exitAllInstances=====
* This will close all instances of JAVA::Java.

====instance protocol====
=====loadJarByPath:aPath=====
* Adds a jar to the running JavaVM. If the jar depends on other jars or libraries you have to add them too.
:: '''aPath''' - the path to the jar file as String.

=====loadJar:aByteArray=====
* Adds a jar to the running JavaVM. If the jar depends on other jars or libraries you have to add them too.
:: '''aByteArrays''' - a ByteArray containing the JAR file.

=====loadExtension:aPath=====
* Adds a jar to the running JavaVM and caches it for subsequent usages. If the jar depends on other jars you have to add them too.
:: '''aPath''' - the path to the jar file as String.

=====boxedDo:aBlock=====
* Any autoboxed values in aBlock returned from the JavaVM are preserved as such. By default autoboxed values are automatically unboxed. This way, the identity of such objects is preserved.

=====isConnected=====
* Tests if a connection is still established.
:: '''return:''' - true if the connection is still established, else false.

=====isAlive=====
* Tests if a connection is still responding.
:: '''return:''' - true if the connection is still alive, else false. Does a message round trip.

=====closeBridge=====
* This will close the bridge connection. Depending on in which mode the JavaBridge was started, the JavaVM is also closed (-keepAlive startparameter not set).

=====exit=====
* Same as closeBridge.

== See Also==
The [[DOT NET Interface Library| DOTNET Interface Plugin & Library]], which implements a likewise interface for .NET applications/libraries.

<hr>
Back to [[Plugins]]

Java Interface Library v2

2016-06-01T09:23:05Z

Javogel: /* Instantiating Arrays */

== Introduction ==

This article discusses version 2 of the Java Bridge (which is as of expecco v2.9 still experimental).
The article for version 1 can be found [[Java Interface Library | here]].

The Java Interface library ("Java Bridge") is used to interact with Java objects inside an external Java Virtual Machine (JVM).

The access to Java objects, classes and programs is done via a framework called "''Java-Bridge''", which is similar in operation to the [[DOT NET Interface Library| dotNET bridge]]. This framework implements transparent forwarding of method (virtual function) calls to Java objects, which exist in a local or remote Java Virtual Machine (JVM). Also, return values, callBacks and exception information are passed back from the Java program to expecco. This is done by a proxy-object mechanism, which catches all function calls, wraps the arguments, sends a datagram to the other bridge side, awaits the reply and returns the result to the original caller. Thus, remote procedure calls are almost completely transparent to the Smalltalk/JavaScript code inside expecco. In your elementary code, you can write remote function calls as if they were to local objects.

Notice that this document describes the low level framework, which implements the bridge communication. A much easier to use high level interface (called "Groovy Blocks") exists and should normally be used, if you need access to a java application's internals during testing.
Please take a look at
[[Expecco_API#Groovy_Elementary_Blocks | "Groovy Block API"]]
and [[Testing Java Applications using Groovy blocks/en | "Testing Java Applications using Groovy blocks"]].

== Architecture ==

On the expecco side, the bridge consists of a number of Proxy objects,
which behave like regular Smalltalk objects as seen from elementary expecco code.
However, instead of performing an action when one of their methods (virtual functions) is called,
they send a message over a socket connection to the Java VM (actually: to a bridge software inside the
Java application) which decodes the message and sends it to the destination Java object.
The same is done in reverse direction with the return value.

+---------------------+ +----------+ +----------------+ +----------------+ +---------+
| | | | | | | | | Java |
| expecco |---->| Proxy |---->| Bridge |==>>==| Bridge |---->| Object |
| (elementary code) |<----| |<----| (expecco side) |==<<==| (Java side) |<----| |
+---------------------+ +----------+ +----------------+ +----------------+ +---------+

This setup allows for transparent communication with objects inside a local or remote Java VM. This may be either utility functions which happen to be convenient for the test application (for example: file parsing, syntax analysis, protocol implementaitons or access to specific hardware via driver libraries), or the tested application in the system under test itself.

Especially, it allows for the objects of the tested application to be looked into, manipulated and for functions of it or underlying frameworks to be called.

For expecco code, we tried to make this as transparent as possible, however there are a few exceptions, when function names need to be translated (for example, because the function naming syntax is different) or due to the fact that for some operations no corresponding name exists in Smalltalk (array access, for example).

Of course, multiple such connections can coexist and be served/handled in parallel. This enables an expecco test suite to communicate with both sides of a tested client-server Java application, for example.

Notice that a similar mechanism is used in expecco to communicate with DOTNET, Qt (C++) and C applications.

 

== Activating the new Java Bridge ==
To activate the new bridge in expecco navigate to <CODE>Extras -> Settings -> Plugins -> Java Bridge</CODE> and tick the '''Use new Bridge (experimental)''' checkbox.
[[Datei:ActivateNewJavaBridge.png]]

'''Attention:''' Ticking the checkbox will terminate all currently active Bridge connections due to incompatibilities between the new and the old version.

== Initializing / Releasing the Bridge ==

Before any communication can take place between expecco and any Java object, the Java side of the bridge has to be started, and a communication has to be established.
In expecco, all of the bridge classes are found in the <CODE>JAVA</CODE> namespace.

The main interface class is "<CODE>Java</CODE>", in the "<CODE>JAVA</CODE>" namespace:
<CODE><PRE>
java := JAVA::Java newWithServer.
</PRE></CODE>
or (in JavaScript):
<CODE><PRE>
java = JAVA::Java.newWithServer();
</PRE></CODE>

This starts the Java-side of the bridge (actually executes java as a background command) on the local machine, and establishes a connection to that JVM.

The bridge connection should be closed, if the bridge is no longer needed. Release the bridge with:
<CODE><PRE>
java.closeBridge();
</PRE></CODE>
which terminates the connection.

=== Start and Connect to a Remote Machine ===
The above started a Java VM and connected to it. Alternatively, you may want to connect to an already running Java program (typically, your system under test).
In order for your program to be reachable, it must allow for the bridge to connect to it via a special bridge-connection, which is a socket connection. For this, it must execute the server code found in the "JavaBridge.jar" file. To pass [[#Startup Parameters| parameters]] you will typically start it from a command line or a little shell/batch script.

Call (on the shell/cmd level):
$ java -jar <PATH_TO_JAVABRIDGE.JAR> <PARAMETERS>

The "JavaBridge.jar" file is found in the installation directory of expecco at:
\exept\expecco\packages\exept\bridgeFramework\javaBridge\javaBin\JavaBridge.jar

The Javabridge code allows for either side to initiate the connection - i.e. it can be run in server mode,
where it awaits an incoming connection, or in client mode, where it actively initiates a connection.
After connection establishment, there is no difference in the operation of the bridge, however depending on the setup of your network infrastructure, especially firewalls, either mechanism may be easier to be used.

Assuming that the bridge is already running on the remote machine as server (default),
use <CODE>newConnectedTo:port:withTimeout:</CODE> to connect to it from the expecco side:
java := JAVA::Java newConnectedTo:'myHost' port:4567 withTimeout:30.
This will initiate the connection setup from the expecco side.

Alternatively, if started in client mode use <CODE>newWaitingForConnectOnHost:port:withTimeout:</CODE>:
java := JAVA::Java newWaitingForConnectOnHost:'localhost' port:4567 withTimeout:30.
which will open a port on the expecco side, and wait until the Java side connects to it.
[[#JAVA::Java|For more details see API]]

====Startup Parameters====
You can use any parameter in any order.
If no parameter is used then the bridge listenes on port 14014 in server mode without keepAlive.
;<code>-help</code>
* Shows the help

;<code>-ip <aHostnameOrIP></code>
* In client mode this specifies the ip or hostname to connect to. In server mode this specifies the ip or hostname to bind to.

;<code>-port <aPortNumber> </code>
* In client mode this specifies the port to connect to. In server mode this specifies the listening port.

;<code>-asClient</code>
* The bridge will start in client mode. If not set the bridge is started in server mode.

;<code>-keepAlive</code>
* By setting this flag the bridge will not exit after the connection has closed and starts to connect or listen again. Otherwise, it will run for a single connection session only.

== Loading Applications (from the expecco side) ==

Normally, you would start your application with the required command line arguments and include the javabridge as jar there. However, in some situations, it may be required to dynamically load other jars into the connected Java VM.
By accessing a classloader, additional classes, or applications as contained in JAR files can be loaded from the expecco side.

This can be used to add a JAR file to the classloader:
<CODE><PRE>
java loadJarByPath:'pathToJarFile'. "/ assuming "java" is a handle as returned from the above connect
</PRE></CODE>

or, if the JAR file is loaded in memory:
<CODE><PRE>
java loadJar:jarByteArray. "/ where "jarByteArray" is a ByteArray containing the JAR file
</PRE></CODE>

If the JVM is on a remote machine, the path is resolved on the expecco side and the JAR will be transferred to the remote side.

Should transferring the JAR be too much overhead, an additional mechanism is provided:
<CODE><PRE>
java loadExtension:'pathToJarFile'.
</PRE></CODE>
this will cache the JAR file on the bridge side and eliminate the overhead of subsequent invocations.

== Java Class Access ==

This following code sample simply references (i.e. accesses) the class "JFrame" from the <CODE>"javax.swing"</CODE> package. The fully specified class name in Java would be <CODE>"javax.swing.JFrame"</CODE>:
<CODE><PRE>
java getJavaClass:'javax.swing.JFrame'
</PRE></CODE>

Or, if you want to load multiple classes:
<CODE><PRE>
java import:'javax.swing.JFrame' import:'javax.swing.JButton'
do:[:jFrame :jButton | "do something with JButton and JFrame" ].
</PRE></CODE>

v2 also supports dynamic compilation of java source code:
<CODE><PRE>
java getJavaClass:'className' fromSource:'classSource'. "/ where classSource is a String containing valid java source code
</PRE></CODE>

and loading precompiled java bytecode:
<CODE><PRE>
java getJavaClass:'className' fromByteCode:byteCode. "/ where byteCode is a ByteArray containing valid java bytecode
</PRE></CODE>

[[#Remote Dynamic Code Injection | for details see Remote Dynamic Code Injection]]

== Instantiating a Class ==

Object instances are created via the "new"-message, sent to a proxy of a Java class. You can get this proxy as described in the previous section. For example, if we want to create a new instance of a "JFrame" and a "JButton", write:
<CODE><PRE>
frame := java getJavaClass:'javax.swing.JFrame' new.
button := java getJavaClass:'javax.swing.JButton' new.
</PRE></CODE>
The first statement results in a proxy object for the "JFrame" instance. The second line results in a proxy for a new "JButton" object.

== Calling Instance Methods ==

A method call is done by a message send to a proxy object, where the message is the method name to call. For example, to call the <CODE>"setVisible(boolean isVisible)"</CODE> method on the above JFrame object, we send the following message to that proxy:
<CODE><PRE>
frame setVisible:true.
</PRE></CODE>

As method naming is different in Smalltalk and Java, a dynamic translation is applied when sending messages from Smalltalk code to a remote Java object. Smalltalk has arguments embedded inside parts of a so called "keyword" message, such as in "receiver foo:arg1 bar:arg2", where "foo:bar:" would be the message name, and "arg1", "arg2" be the arguments.

In Java, the message name is a single identifier, and arguments are written in an argument list after the message name: "receiver.fooBar(arg1, arg2)".

When message names are translated, only the very first part of the Smalltalk keyword message is taken ("foo" in the above example), and the remaining parts are simpl ignored. Thus, any of the Smalltalk messages "foo:bar:", "foo:xxxx:" and "foo:_:" (a single underscore as second part) all translate to the same Java message name "foo()".

Therefore, to call a method with more than one argument, like <CODE>"setSize(int width,int height)"</CODE> on a JFrame instance we can write:
<CODE><PRE>
frame setSize:300 _:200.
</PRE></CODE>
but just as well:
<CODE><PRE>
frame setSize:300 anyWord:200.
</PRE></CODE>
or any other selector with "setSize:" as its first component.
The selector translation mechanism simply takes the first part as the Java selector.

In practice, you should take a reasonably descriptive name, such as: "frame setSize:300 height:200" or only the Java name as first part, such as "frame setSize:300 _:200".

For a call of a method with 4 arguments, we could write:
<CODE><PRE>
frame setBounds:100 y:50 width:300 height:200.
</PRE></CODE>
or:
<CODE><PRE>
frame setBounds:100 _:50 _:300 _:200.
</PRE></CODE>

Also here the <CODE>"y: width: height:"</CODE> can be named as you want, but the first part must be "setBounds:".

=== Calling Static Methods ===

Calling a static method on an object is not different from calling non static methods. In most cases you will call a static method not on an object but directly on the class. This is done by using the class object as "receiver" of the message. For example, if we want to call the static method <CODE>"isDefaultLookAndFeelDecorated()"</CODE> of the JFrame class, write:
<CODE><PRE>
java getJavaClass:'javax.swing.JFrame' isDefaultLookAndFeelDecorated.
</PRE></CODE>

== Accessing Fields ==

As Smalltalk does not support access of an object's fields from the outside (it is fully encapsulated, and access from outside is ONLY allowed via getters/setters), an additional translation mechanism is provided for field access.

Accessing a field of a Java object or a class's static field uses the same syntax as method calls. To access a field, send a message where the message is the field name. To access the field of a class the field must be static.
For example, to get the value of the static field named <CODE>"EXIT_ON_CLOSE"</CODE> of the "JFrame" class, write
<CODE><PRE>
value := java getJavaClass:'javax.swing.JFrame' EXIT_ON_CLOSE.
</PRE></CODE>
The variable "value" now holds the integer value of the <CODE>"EXIT_ON_CLOSE"</CODE> constant.

Assuming that a "JFrame" object had a field named <CODE>"myField"</CODE>, to access this field, we'd have to write:
<CODE><PRE>
value := frame myField.
</PRE></CODE>
and "value" now holding whatever <CODE>"myField"</CODE> returns. This could be another object reference or any primitive value.

=== Setting Fields ===
To set a field, use a setter-like method call:
<CODE><PRE>
frame myField: newValue.
</PRE></CODE>

=== Name Conflicts ===

In very rare situations, a Java object may contain both a field and a method by the same name.
In this case, the Smalltalk code cannot depend on the dynamic translation mechanism (which actually looks for either a field or method name to match), but instead make it explicit, which operation is wanted:
Use:
<CODE><PRE>
frame getFieldByName:'myField'
</PRE></CODE>
to read a field, and:
<CODE><PRE>
frame setFieldByName:'myField' value:123.
</PRE></CODE>
to write the field.

If there are both fields and methods by the same name, and you use the non-explicit call,
the bridge will always assume that you want to call the getter/setter and perform a method call.
 

== Arrays ==

=== Passing Smalltalk Collections to Java ===

Smalltalk collections can now be directly passed to Java with a few limitations:
* The identity of the Smalltalk collections will not be preserved. passing the same collection to java multiple times will result in multiple instances of the same array on the java side. (to bypass this instantiate a new java array)
* Smalltalk collections need to be explicitly converted to the correct type (e.g. a <CODE>SignedIntegerArray</CODE> on the smalltal side matches an <CODE>int</CODE>-Array on the java side)

=== Instantiating Arrays ===

The new bridge supports instantiation of arrays (whereas previously reflection had to be used to instantiate arrays from the smalltalk side).
There are two ways an array can be instantiated:

<CODE><PRE>
intArray := (java getJavaClass:'int[]') new:#[ 1 2 3 4 5 ] asSignedIntegerArray. "/ instantiates a new array of type "int" with the contents "1, 2, 3, 4, 5"
</PRE></CODE>

<CODE><PRE>
intArray := (java getJavaClass:'int[]') new:10. "/ instantiates a new empty array of type "int" with 10 elements.
</PRE></CODE>

=== Accessing Arrays ===

To achieve better performance, arrays of primitive types smaller than a certain size have their contents cached on the smalltalk side:
<CODE><PRE>
intArray contents at:1. "/ this will access the first element of the cached contents.
</PRE></CODE>

large arrays are not serialized immediately. large arrays will be serialized when <CODE>contents</CODE> is called the first time.

'''Attention:''' Java arrays are not immutable. changes to an array are not reflected in the cached contents. if an array has been updated, call <CODE>refresh</CODE> on the array to update the cache. arrays will not be updated automatically.

<CODE><PRE>
shortArray := (java getJavaClass:'[S') new:10. "/ new empty "short" array with 10 elements

"/ copy the contents of the smalltalk collection to the newly instantiated short array
(java getJavaClass:'java.lang.System') arraycopy:(#[ 1 2 3 ] asSignedWordArray) srcPos:0 dest:shortArray destPos:0 length:3.

shortArray at:0. "/ will reflect the changes made to the array

shortArray contents at:1. "/ will still return 0 because the cached contents have not been updated.

shortArray refresh. "/ update the cached contents

shortArray contents at:1. "/ will now correctly reflect the changes made to the array
</PRE></CODE>

== Callbacks from Java ==
Sometimes you may want to execute a piece of Smalltalk code during the execution of the Java code. For example, we may want to install a Smalltalk observer to be notified when a button on a Java GUI was pressed,
or some other callback from a Java framework.

The following code registers a Smalltalk block as a callback for a mouse press event of a button:
<CODE><PRE>
listener := MouseListener new.
listener implementMethod:'mousePressed' as:[ Transcript showCR:'Hello from Java' ].
</PRE></CODE>
The above creates the callback and the listener, which can now be registered on a button:
<CODE><PRE>
button addMouseListener:listener.
</PRE></CODE>
Now, with the press of the button in the Java GUI, the Smalltalk block will be executed and writes <CODE>"Hello from Java"</CODE> to the Smalltalk console.
Of course, any other (Smalltalk-)action code can be made to run via this mechanism.

But be aware, that the callback is possibly called later (when the elementary action, which installed the code, has already finished long ago). Also, as the Java code execution is not synchronized with any of your expecco action execution, the callback may also be called at any arbutrary time, even at times when no activity at all is executed on the expecco side. If you forget to cleanup, and the Java object is still alive, it may even be called after you have finished your test run (if you keep the java bridge handle around and alive, for example in an expecoo environment variable).

So the Smalltalk callback code should not depend on any particular elementary action to be currently running, but instead in most cases write some information into a shared data container, preferably an instance of "SharedQueue", which is thread safe. Then, some other action (an elementary action) would read-wait and read events from that shared queue.

make sure that your test correctly cleans up any such callbacks afterwards. As a last resort, use the "Shutdown Bridge Connection" menu item, which closes the bridge connection, and thereby - as a side effect - removes any leftover callbacks. It does close the connection, and any remaining java proxy object handles become invalid, though.

Another example, using an observer could look like:
<CODE><PRE>
observer := java Observer new.
observer implementMethod:'update'
as:[:sourceObservable :argument|
argument notNil ifTrue:[ Transcript showCR:('I was notifyed with: ',argument toString) ]
ifFalse:[ Transcript showCR:'I was notifyed and the argument was nil' ].
].
myObservable addObserver:observer.
</PRE></CODE>
When the observable calls <CODE>"notifyObservers"</CODE>, the Smalltalk block will be executed.

== Exceptions in Java ==
Exceptions on the Java side are signalled back to the Smalltalk side and raise a corresponding exception there. However, on the Java side, the call stack which lead to the exception has already been unwound at that time (Java exceptions are not proceedable). So a proceed in the Smalltalk-side exception handler only affects the Smalltalk caller, but may leave the Java side in an undefined state.

== Remote Dynamic Code Injection ==
Sometimes we might want to execute code without the overhead of many rpc-messages being sent over the bridge, especially if we want to do something time critical, or want to make execution time measurements.
For this, it is possible to load a class at runtime into the JavaVM. The code of the class will first be sent to the JavaVM, which will compile and load the generated byte code. Then, the class can be accessed via the bridge just like any other preloaded class.

The following example specifies the class code in a smalltalk string and inject the code into the JavaVM. Then an instance of that new class will be instantiated and finally a method of the object instance will be invoked:
<CODE><PRE>
classCode := '
package myPackage.test;

import java.awt.BorderLayout;
import java.awt.event.MouseAdapter;
import java.awt.event.MouseEvent;
import java.util.Calendar;

import javax.swing.JButton;
import javax.swing.JFrame;
import javax.swing.JLabel;;

public class MyInjectedClass {
public void createSampleApp(){
JFrame frame=new JFrame("Hello im injected");
frame.setLayout(new BorderLayout());
JButton button=new JButton("click me");
final JLabel label=new JLabel("Text");
button.addMouseListener(new MouseAdapter() {

@Override
public void mouseClicked(MouseEvent e) {
label.setText(Calendar.getInstance().getTime().toString());
}
});
frame.add(label,BorderLayout.NORTH);
frame.add(button,BorderLayout.SOUTH);
frame.setSize(300, 300);
frame.setVisible(true);
}
}
'.
classObject := java getJavaClass:'myPackage.test.MyInjectedClass' fromSource:classCode.
classObject new createSampleApp.
</PRE></CODE>
After the code has been injected, a new instance of <CODE>"MyInjectedClass"</CODE> is created and the <CODE>"createSampleApp"</CODE> method is called. Because the example implements a GUI, a Java window will open, containing a label and a button. Clicking the button displays the current time in the label.



=== Code Sources for Class injection ===
There are 3 possible types of class code sources which we can use to inject the code. In the examples before we directly used a simple <CODE>"String"</CODE> in the smalltalk code as a code source. We also can use a <CODE>"*.java"</CODE> file as source. Just read the content of the file into a string and use it as in the previous examples.

To inject a <CODE>"*.class"</CODE> file use the following code:
<pre>
java getJavaClass:'the.class.name' fromByteCode:classCode.
</pre>

== Examples ==

This example creates a JFrame with one button inside. Then a Mouselistener is created and registered on the button. When the button is pressed, the title of the window changes to <CODE>"onPressed"</CODE> and the Transcript shows the message <CODE>"onPressed"</CODE>. When the button is released, the title of the window is changed to <CODE>"onReleased"</CODE> and the Transcript shows <CODE>"onReleased"</CODE>. If the button lost the mouse focus, the bridge will exit (disconnect), and the Java side is terminated.
<CODE><PRE>
|java frame button listener|

"/getting a bridge
java := JAVA::JavaBridge newWithServer.

"/creating a new frame and button object
frame := java getJavaClass:'javax.swing.JFrame' new.
button := java JButton new:'Click'.

"/creating a new mouse listener and adding callback blocks
listener := java MouseListener new.

listener implementMethod:'mousePressed' as:[ Transcript showCR:'onPress'. frame setTitle:'onPressed' ].
listener implementMethod:'mouseReleased' as:[ Transcript showCR:'onReleased'. frame setTitle:'onReleased' ].
listener implementMethod:'mouseExited' as:[ Transcript showCR:'onExited'. java closeBridge. ].

"/register the mouse listener on the button and make the frame with button visible
button addMouseListener:listener.
frame add:button.
frame setSize:300 y:100.
frame setVisible: true.
</PRE></CODE>



==Differences between v1 and v2==
===General===
* A Java Bridge instance no longer requires multiple tcp ports to be open. This simplifies connection through ssh tunnels and firewalls.
* The identity of strings and primitve wrappers can be preserved. (see [[#boxedDo:aBlock | boxedDo]])
* Arrays of primitive types are serialized. (see [[#Arrays | Arrays]])

===Loading Applications===
* '''addJarByPath:''' and '''addToClassPath:''' are still supported but have been deprecated. use '''loadJar:''', '''loadJarByPath:''' and '''loadExtension:''' instead. The new methods no longer require the jar or library to be present on the remote machine.

[[Java Interface Library#Loading Applications (from the expecco side) | v1]] [[#Loading Applications (from the expecco side) | v2]]

===Java Class Access===
* Sending the fully qualified name with instances of "." replaced by "_" to the bridge handle is still supported, but not recommended.
* A new method '''getJavaClass:''' has been introduced (also available for v1 since expecco v2.9). This solves the side effects of "_" being a legal character in class names.

[[Java Interface Library#Java Package Import and Class Access | v1]] [[#Java Class Access | v2]]
===Callbacks from Java===
* A new method '''implementMethod:as:''' has been introduced to assign callback blocks to method names. The old way is still supported.

[[Java Interface Library#Callbacks from Java | v1]] [[#Callbacks from Java | v2]]

===Remote Dynamic Code Injection===
* Code injection was problematic in v1 and has now been re-implemented in v2.

[[#Remote Dynamic Code Injection | v2]]

== API ==
===JAVA::Java===
====class protocol====
=====newWithServer=====
* This will start a local JavaVM, running the JavaBridge, and establishes a connection on a random free port.
: A new connected instance of JAVA::Java class is returned.

=====newWithServerForJavaPath:aJavaPathFilename=====
* This is the same as newWithServer but the path to the java executable can be specified. The JavaVM version must be 1.6 or higher to run the JavaBridge.
:: '''aJavaPathFilename''' - must be a instance of Filename
Smalltalk: JAVA::Java newWithServerForJavaPath:('my\path\to\java.executable'asFilename).
JavaScript: JAVA::Java.newWithServerForJavaPath("my\path\to\java.executable".asFilename());

=====newConnectedTo:aHhostString port:aPortNumber withTimeout:aTimeoutSeconds=====
* This is used to connect to a running JavaBridge on the network. The JavaBridge must be started in server mode on the remote host. After connecting a new connected instance of JAVA::Java is returned.
:: '''aHostString''' - the hostname or IP of the remote machine as String
:: '''aPortNumber ''' - the port on which the remote machine is listening as Number
:: '''aTimeoutSeconds''' - a connect timeout in seconds as Number
Smalltalk: JAVA::Java newConnectedTo:'myHostName' port:4567 withTimeout:30.
JavaScript: JAVA::Java.newConnectedTo_port_withTimeout("myHostName",4567,30);

=====newWaitingForConnectOnHost:aListeningAddressString port:aListeningPortNumber withTimeout:aTimeoutSeconds=====
* This is used to wait for incomming connecions of a running JavaBridge on the network. The JavaBridge must be started in client mode on the remote host. After connecting a new connected instance of JAVA::Java is returned.
:: '''deprecated: aListeningAddressString''' - no longer used. Can be nil.
:: '''aListeningPortNumber ''' - the port on which to listen for incomming connections as Number
:: '''aTimeoutSeconds''' - a connect timeout in seconds as Number, If nil it will wait endless.

=====singletonInstance=====
* This will call newWithServer for the first time and then always returns the same connected JAVA::Java instance until the connection was closed, then a new connected instance is returned.

=====exitAllInstances=====
* This will close all instances of JAVA::Java.

====instance protocol====
=====loadJarByPath:aPath=====
* Adds a jar to the running JavaVM. If the jar depends on other jars or libraries you have to add them too.
:: '''aPath''' - the path to the jar file as String.

=====loadJar:aByteArray=====
* Adds a jar to the running JavaVM. If the jar depends on other jars or libraries you have to add them too.
:: '''aByteArrays''' - a ByteArray containing the JAR file.

=====loadExtension:aPath=====
* Adds a jar to the running JavaVM and caches it for subsequent usages. If the jar depends on other jars you have to add them too.
:: '''aPath''' - the path to the jar file as String.

=====boxedDo:aBlock=====
* Any autoboxed values in aBlock returned from the JavaVM are preserved as such. By default autoboxed values are automatically unboxed. This way, the identity of such objects is preserved.

=====isConnected=====
* Tests if a connection is still established.
:: '''return:''' - true if the connection is still established, else false.

=====isAlive=====
* Tests if a connection is still responding.
:: '''return:''' - true if the connection is still alive, else false. Does a message round trip.

=====closeBridge=====
* This will close the bridge connection. Depending on in which mode the JavaBridge was started, the JavaVM is also closed (-keepAlive startparameter not set).

=====exit=====
* Same as closeBridge.

== See Also==
The [[DOT NET Interface Library| DOTNET Interface Plugin & Library]], which implements a likewise interface for .NET applications/libraries.

<hr>
Back to [[Plugins]]

Java Interface Library v2

2016-06-01T09:19:39Z

Javogel: /* Instantiating Arrays */

== Introduction ==

This article discusses version 2 of the Java Bridge (which is as of expecco v2.9 still experimental).
The article for version 1 can be found [[Java Interface Library | here]].

The Java Interface library ("Java Bridge") is used to interact with Java objects inside an external Java Virtual Machine (JVM).

The access to Java objects, classes and programs is done via a framework called "''Java-Bridge''", which is similar in operation to the [[DOT NET Interface Library| dotNET bridge]]. This framework implements transparent forwarding of method (virtual function) calls to Java objects, which exist in a local or remote Java Virtual Machine (JVM). Also, return values, callBacks and exception information are passed back from the Java program to expecco. This is done by a proxy-object mechanism, which catches all function calls, wraps the arguments, sends a datagram to the other bridge side, awaits the reply and returns the result to the original caller. Thus, remote procedure calls are almost completely transparent to the Smalltalk/JavaScript code inside expecco. In your elementary code, you can write remote function calls as if they were to local objects.

Notice that this document describes the low level framework, which implements the bridge communication. A much easier to use high level interface (called "Groovy Blocks") exists and should normally be used, if you need access to a java application's internals during testing.
Please take a look at
[[Expecco_API#Groovy_Elementary_Blocks | "Groovy Block API"]]
and [[Testing Java Applications using Groovy blocks/en | "Testing Java Applications using Groovy blocks"]].

== Architecture ==

On the expecco side, the bridge consists of a number of Proxy objects,
which behave like regular Smalltalk objects as seen from elementary expecco code.
However, instead of performing an action when one of their methods (virtual functions) is called,
they send a message over a socket connection to the Java VM (actually: to a bridge software inside the
Java application) which decodes the message and sends it to the destination Java object.
The same is done in reverse direction with the return value.

+---------------------+ +----------+ +----------------+ +----------------+ +---------+
| | | | | | | | | Java |
| expecco |---->| Proxy |---->| Bridge |==>>==| Bridge |---->| Object |
| (elementary code) |<----| |<----| (expecco side) |==<<==| (Java side) |<----| |
+---------------------+ +----------+ +----------------+ +----------------+ +---------+

This setup allows for transparent communication with objects inside a local or remote Java VM. This may be either utility functions which happen to be convenient for the test application (for example: file parsing, syntax analysis, protocol implementaitons or access to specific hardware via driver libraries), or the tested application in the system under test itself.

Especially, it allows for the objects of the tested application to be looked into, manipulated and for functions of it or underlying frameworks to be called.

For expecco code, we tried to make this as transparent as possible, however there are a few exceptions, when function names need to be translated (for example, because the function naming syntax is different) or due to the fact that for some operations no corresponding name exists in Smalltalk (array access, for example).

Of course, multiple such connections can coexist and be served/handled in parallel. This enables an expecco test suite to communicate with both sides of a tested client-server Java application, for example.

Notice that a similar mechanism is used in expecco to communicate with DOTNET, Qt (C++) and C applications.

 

== Activating the new Java Bridge ==
To activate the new bridge in expecco navigate to <CODE>Extras -> Settings -> Plugins -> Java Bridge</CODE> and tick the '''Use new Bridge (experimental)''' checkbox.
[[Datei:ActivateNewJavaBridge.png]]

'''Attention:''' Ticking the checkbox will terminate all currently active Bridge connections due to incompatibilities between the new and the old version.

== Initializing / Releasing the Bridge ==

Before any communication can take place between expecco and any Java object, the Java side of the bridge has to be started, and a communication has to be established.
In expecco, all of the bridge classes are found in the <CODE>JAVA</CODE> namespace.

The main interface class is "<CODE>Java</CODE>", in the "<CODE>JAVA</CODE>" namespace:
<CODE><PRE>
java := JAVA::Java newWithServer.
</PRE></CODE>
or (in JavaScript):
<CODE><PRE>
java = JAVA::Java.newWithServer();
</PRE></CODE>

This starts the Java-side of the bridge (actually executes java as a background command) on the local machine, and establishes a connection to that JVM.

The bridge connection should be closed, if the bridge is no longer needed. Release the bridge with:
<CODE><PRE>
java.closeBridge();
</PRE></CODE>
which terminates the connection.

=== Start and Connect to a Remote Machine ===
The above started a Java VM and connected to it. Alternatively, you may want to connect to an already running Java program (typically, your system under test).
In order for your program to be reachable, it must allow for the bridge to connect to it via a special bridge-connection, which is a socket connection. For this, it must execute the server code found in the "JavaBridge.jar" file. To pass [[#Startup Parameters| parameters]] you will typically start it from a command line or a little shell/batch script.

Call (on the shell/cmd level):
$ java -jar <PATH_TO_JAVABRIDGE.JAR> <PARAMETERS>

The "JavaBridge.jar" file is found in the installation directory of expecco at:
\exept\expecco\packages\exept\bridgeFramework\javaBridge\javaBin\JavaBridge.jar

The Javabridge code allows for either side to initiate the connection - i.e. it can be run in server mode,
where it awaits an incoming connection, or in client mode, where it actively initiates a connection.
After connection establishment, there is no difference in the operation of the bridge, however depending on the setup of your network infrastructure, especially firewalls, either mechanism may be easier to be used.

Assuming that the bridge is already running on the remote machine as server (default),
use <CODE>newConnectedTo:port:withTimeout:</CODE> to connect to it from the expecco side:
java := JAVA::Java newConnectedTo:'myHost' port:4567 withTimeout:30.
This will initiate the connection setup from the expecco side.

Alternatively, if started in client mode use <CODE>newWaitingForConnectOnHost:port:withTimeout:</CODE>:
java := JAVA::Java newWaitingForConnectOnHost:'localhost' port:4567 withTimeout:30.
which will open a port on the expecco side, and wait until the Java side connects to it.
[[#JAVA::Java|For more details see API]]

====Startup Parameters====
You can use any parameter in any order.
If no parameter is used then the bridge listenes on port 14014 in server mode without keepAlive.
;<code>-help</code>
* Shows the help

;<code>-ip <aHostnameOrIP></code>
* In client mode this specifies the ip or hostname to connect to. In server mode this specifies the ip or hostname to bind to.

;<code>-port <aPortNumber> </code>
* In client mode this specifies the port to connect to. In server mode this specifies the listening port.

;<code>-asClient</code>
* The bridge will start in client mode. If not set the bridge is started in server mode.

;<code>-keepAlive</code>
* By setting this flag the bridge will not exit after the connection has closed and starts to connect or listen again. Otherwise, it will run for a single connection session only.

== Loading Applications (from the expecco side) ==

Normally, you would start your application with the required command line arguments and include the javabridge as jar there. However, in some situations, it may be required to dynamically load other jars into the connected Java VM.
By accessing a classloader, additional classes, or applications as contained in JAR files can be loaded from the expecco side.

This can be used to add a JAR file to the classloader:
<CODE><PRE>
java loadJarByPath:'pathToJarFile'. "/ assuming "java" is a handle as returned from the above connect
</PRE></CODE>

or, if the JAR file is loaded in memory:
<CODE><PRE>
java loadJar:jarByteArray. "/ where "jarByteArray" is a ByteArray containing the JAR file
</PRE></CODE>

If the JVM is on a remote machine, the path is resolved on the expecco side and the JAR will be transferred to the remote side.

Should transferring the JAR be too much overhead, an additional mechanism is provided:
<CODE><PRE>
java loadExtension:'pathToJarFile'.
</PRE></CODE>
this will cache the JAR file on the bridge side and eliminate the overhead of subsequent invocations.

== Java Class Access ==

This following code sample simply references (i.e. accesses) the class "JFrame" from the <CODE>"javax.swing"</CODE> package. The fully specified class name in Java would be <CODE>"javax.swing.JFrame"</CODE>:
<CODE><PRE>
java getJavaClass:'javax.swing.JFrame'
</PRE></CODE>

Or, if you want to load multiple classes:
<CODE><PRE>
java import:'javax.swing.JFrame' import:'javax.swing.JButton'
do:[:jFrame :jButton | "do something with JButton and JFrame" ].
</PRE></CODE>

v2 also supports dynamic compilation of java source code:
<CODE><PRE>
java getJavaClass:'className' fromSource:'classSource'. "/ where classSource is a String containing valid java source code
</PRE></CODE>

and loading precompiled java bytecode:
<CODE><PRE>
java getJavaClass:'className' fromByteCode:byteCode. "/ where byteCode is a ByteArray containing valid java bytecode
</PRE></CODE>

[[#Remote Dynamic Code Injection | for details see Remote Dynamic Code Injection]]

== Instantiating a Class ==

Object instances are created via the "new"-message, sent to a proxy of a Java class. You can get this proxy as described in the previous section. For example, if we want to create a new instance of a "JFrame" and a "JButton", write:
<CODE><PRE>
frame := java getJavaClass:'javax.swing.JFrame' new.
button := java getJavaClass:'javax.swing.JButton' new.
</PRE></CODE>
The first statement results in a proxy object for the "JFrame" instance. The second line results in a proxy for a new "JButton" object.

== Calling Instance Methods ==

A method call is done by a message send to a proxy object, where the message is the method name to call. For example, to call the <CODE>"setVisible(boolean isVisible)"</CODE> method on the above JFrame object, we send the following message to that proxy:
<CODE><PRE>
frame setVisible:true.
</PRE></CODE>

As method naming is different in Smalltalk and Java, a dynamic translation is applied when sending messages from Smalltalk code to a remote Java object. Smalltalk has arguments embedded inside parts of a so called "keyword" message, such as in "receiver foo:arg1 bar:arg2", where "foo:bar:" would be the message name, and "arg1", "arg2" be the arguments.

In Java, the message name is a single identifier, and arguments are written in an argument list after the message name: "receiver.fooBar(arg1, arg2)".

When message names are translated, only the very first part of the Smalltalk keyword message is taken ("foo" in the above example), and the remaining parts are simpl ignored. Thus, any of the Smalltalk messages "foo:bar:", "foo:xxxx:" and "foo:_:" (a single underscore as second part) all translate to the same Java message name "foo()".

Therefore, to call a method with more than one argument, like <CODE>"setSize(int width,int height)"</CODE> on a JFrame instance we can write:
<CODE><PRE>
frame setSize:300 _:200.
</PRE></CODE>
but just as well:
<CODE><PRE>
frame setSize:300 anyWord:200.
</PRE></CODE>
or any other selector with "setSize:" as its first component.
The selector translation mechanism simply takes the first part as the Java selector.

In practice, you should take a reasonably descriptive name, such as: "frame setSize:300 height:200" or only the Java name as first part, such as "frame setSize:300 _:200".

For a call of a method with 4 arguments, we could write:
<CODE><PRE>
frame setBounds:100 y:50 width:300 height:200.
</PRE></CODE>
or:
<CODE><PRE>
frame setBounds:100 _:50 _:300 _:200.
</PRE></CODE>

Also here the <CODE>"y: width: height:"</CODE> can be named as you want, but the first part must be "setBounds:".

=== Calling Static Methods ===

Calling a static method on an object is not different from calling non static methods. In most cases you will call a static method not on an object but directly on the class. This is done by using the class object as "receiver" of the message. For example, if we want to call the static method <CODE>"isDefaultLookAndFeelDecorated()"</CODE> of the JFrame class, write:
<CODE><PRE>
java getJavaClass:'javax.swing.JFrame' isDefaultLookAndFeelDecorated.
</PRE></CODE>

== Accessing Fields ==

As Smalltalk does not support access of an object's fields from the outside (it is fully encapsulated, and access from outside is ONLY allowed via getters/setters), an additional translation mechanism is provided for field access.

Accessing a field of a Java object or a class's static field uses the same syntax as method calls. To access a field, send a message where the message is the field name. To access the field of a class the field must be static.
For example, to get the value of the static field named <CODE>"EXIT_ON_CLOSE"</CODE> of the "JFrame" class, write
<CODE><PRE>
value := java getJavaClass:'javax.swing.JFrame' EXIT_ON_CLOSE.
</PRE></CODE>
The variable "value" now holds the integer value of the <CODE>"EXIT_ON_CLOSE"</CODE> constant.

Assuming that a "JFrame" object had a field named <CODE>"myField"</CODE>, to access this field, we'd have to write:
<CODE><PRE>
value := frame myField.
</PRE></CODE>
and "value" now holding whatever <CODE>"myField"</CODE> returns. This could be another object reference or any primitive value.

=== Setting Fields ===
To set a field, use a setter-like method call:
<CODE><PRE>
frame myField: newValue.
</PRE></CODE>

=== Name Conflicts ===

In very rare situations, a Java object may contain both a field and a method by the same name.
In this case, the Smalltalk code cannot depend on the dynamic translation mechanism (which actually looks for either a field or method name to match), but instead make it explicit, which operation is wanted:
Use:
<CODE><PRE>
frame getFieldByName:'myField'
</PRE></CODE>
to read a field, and:
<CODE><PRE>
frame setFieldByName:'myField' value:123.
</PRE></CODE>
to write the field.

If there are both fields and methods by the same name, and you use the non-explicit call,
the bridge will always assume that you want to call the getter/setter and perform a method call.
 

== Arrays ==

=== Passing Smalltalk Collections to Java ===

Smalltalk collections can now be directly passed to Java with a few limitations:
* The identity of the Smalltalk collections will not be preserved. passing the same collection to java multiple times will result in multiple instances of the same array on the java side. (to bypass this instantiate a new java array)
* Smalltalk collections need to be explicitly converted to the correct type (e.g. a <CODE>SignedIntegerArray</CODE> on the smalltal side matches an <CODE>int</CODE>-Array on the java side)

=== Instantiating Arrays ===

The new bridge supports instantiation of arrays (whereas previously reflection had to be used to instantiate arrays from the smalltalk side).
There are two ways an array can be instantiated:

<CODE><PRE>
intArray := (java getJavaClass:'[I') new:#[ 1 2 3 4 5 ] asSignedIntegerArray. "/ instantiates a new array of type "int" with the contents "1, 2, 3, 4, 5"
</PRE></CODE>

<CODE><PRE>
intArray := (java getJavaClass:'[I') new:10. "/ instantiates a new empty array of type "int" with 10 elements.
</PRE></CODE>

=== Accessing Arrays ===

To achieve better performance, arrays of primitive types smaller than a certain size have their contents cached on the smalltalk side:
<CODE><PRE>
intArray contents at:1. "/ this will access the first element of the cached contents.
</PRE></CODE>

large arrays are not serialized immediately. large arrays will be serialized when <CODE>contents</CODE> is called the first time.

'''Attention:''' Java arrays are not immutable. changes to an array are not reflected in the cached contents. if an array has been updated, call <CODE>refresh</CODE> on the array to update the cache. arrays will not be updated automatically.

<CODE><PRE>
shortArray := (java getJavaClass:'[S') new:10. "/ new empty "short" array with 10 elements

"/ copy the contents of the smalltalk collection to the newly instantiated short array
(java getJavaClass:'java.lang.System') arraycopy:(#[ 1 2 3 ] asSignedWordArray) srcPos:0 dest:shortArray destPos:0 length:3.

shortArray at:0. "/ will reflect the changes made to the array

shortArray contents at:1. "/ will still return 0 because the cached contents have not been updated.

shortArray refresh. "/ update the cached contents

shortArray contents at:1. "/ will now correctly reflect the changes made to the array
</PRE></CODE>

== Callbacks from Java ==
Sometimes you may want to execute a piece of Smalltalk code during the execution of the Java code. For example, we may want to install a Smalltalk observer to be notified when a button on a Java GUI was pressed,
or some other callback from a Java framework.

The following code registers a Smalltalk block as a callback for a mouse press event of a button:
<CODE><PRE>
listener := MouseListener new.
listener implementMethod:'mousePressed' as:[ Transcript showCR:'Hello from Java' ].
</PRE></CODE>
The above creates the callback and the listener, which can now be registered on a button:
<CODE><PRE>
button addMouseListener:listener.
</PRE></CODE>
Now, with the press of the button in the Java GUI, the Smalltalk block will be executed and writes <CODE>"Hello from Java"</CODE> to the Smalltalk console.
Of course, any other (Smalltalk-)action code can be made to run via this mechanism.

But be aware, that the callback is possibly called later (when the elementary action, which installed the code, has already finished long ago). Also, as the Java code execution is not synchronized with any of your expecco action execution, the callback may also be called at any arbutrary time, even at times when no activity at all is executed on the expecco side. If you forget to cleanup, and the Java object is still alive, it may even be called after you have finished your test run (if you keep the java bridge handle around and alive, for example in an expecoo environment variable).

So the Smalltalk callback code should not depend on any particular elementary action to be currently running, but instead in most cases write some information into a shared data container, preferably an instance of "SharedQueue", which is thread safe. Then, some other action (an elementary action) would read-wait and read events from that shared queue.

make sure that your test correctly cleans up any such callbacks afterwards. As a last resort, use the "Shutdown Bridge Connection" menu item, which closes the bridge connection, and thereby - as a side effect - removes any leftover callbacks. It does close the connection, and any remaining java proxy object handles become invalid, though.

Another example, using an observer could look like:
<CODE><PRE>
observer := java Observer new.
observer implementMethod:'update'
as:[:sourceObservable :argument|
argument notNil ifTrue:[ Transcript showCR:('I was notifyed with: ',argument toString) ]
ifFalse:[ Transcript showCR:'I was notifyed and the argument was nil' ].
].
myObservable addObserver:observer.
</PRE></CODE>
When the observable calls <CODE>"notifyObservers"</CODE>, the Smalltalk block will be executed.

== Exceptions in Java ==
Exceptions on the Java side are signalled back to the Smalltalk side and raise a corresponding exception there. However, on the Java side, the call stack which lead to the exception has already been unwound at that time (Java exceptions are not proceedable). So a proceed in the Smalltalk-side exception handler only affects the Smalltalk caller, but may leave the Java side in an undefined state.

== Remote Dynamic Code Injection ==
Sometimes we might want to execute code without the overhead of many rpc-messages being sent over the bridge, especially if we want to do something time critical, or want to make execution time measurements.
For this, it is possible to load a class at runtime into the JavaVM. The code of the class will first be sent to the JavaVM, which will compile and load the generated byte code. Then, the class can be accessed via the bridge just like any other preloaded class.

The following example specifies the class code in a smalltalk string and inject the code into the JavaVM. Then an instance of that new class will be instantiated and finally a method of the object instance will be invoked:
<CODE><PRE>
classCode := '
package myPackage.test;

import java.awt.BorderLayout;
import java.awt.event.MouseAdapter;
import java.awt.event.MouseEvent;
import java.util.Calendar;

import javax.swing.JButton;
import javax.swing.JFrame;
import javax.swing.JLabel;;

public class MyInjectedClass {
public void createSampleApp(){
JFrame frame=new JFrame("Hello im injected");
frame.setLayout(new BorderLayout());
JButton button=new JButton("click me");
final JLabel label=new JLabel("Text");
button.addMouseListener(new MouseAdapter() {

@Override
public void mouseClicked(MouseEvent e) {
label.setText(Calendar.getInstance().getTime().toString());
}
});
frame.add(label,BorderLayout.NORTH);
frame.add(button,BorderLayout.SOUTH);
frame.setSize(300, 300);
frame.setVisible(true);
}
}
'.
classObject := java getJavaClass:'myPackage.test.MyInjectedClass' fromSource:classCode.
classObject new createSampleApp.
</PRE></CODE>
After the code has been injected, a new instance of <CODE>"MyInjectedClass"</CODE> is created and the <CODE>"createSampleApp"</CODE> method is called. Because the example implements a GUI, a Java window will open, containing a label and a button. Clicking the button displays the current time in the label.



=== Code Sources for Class injection ===
There are 3 possible types of class code sources which we can use to inject the code. In the examples before we directly used a simple <CODE>"String"</CODE> in the smalltalk code as a code source. We also can use a <CODE>"*.java"</CODE> file as source. Just read the content of the file into a string and use it as in the previous examples.

To inject a <CODE>"*.class"</CODE> file use the following code:
<pre>
java getJavaClass:'the.class.name' fromByteCode:classCode.
</pre>

== Examples ==

This example creates a JFrame with one button inside. Then a Mouselistener is created and registered on the button. When the button is pressed, the title of the window changes to <CODE>"onPressed"</CODE> and the Transcript shows the message <CODE>"onPressed"</CODE>. When the button is released, the title of the window is changed to <CODE>"onReleased"</CODE> and the Transcript shows <CODE>"onReleased"</CODE>. If the button lost the mouse focus, the bridge will exit (disconnect), and the Java side is terminated.
<CODE><PRE>
|java frame button listener|

"/getting a bridge
java := JAVA::JavaBridge newWithServer.

"/creating a new frame and button object
frame := java getJavaClass:'javax.swing.JFrame' new.
button := java JButton new:'Click'.

"/creating a new mouse listener and adding callback blocks
listener := java MouseListener new.

listener implementMethod:'mousePressed' as:[ Transcript showCR:'onPress'. frame setTitle:'onPressed' ].
listener implementMethod:'mouseReleased' as:[ Transcript showCR:'onReleased'. frame setTitle:'onReleased' ].
listener implementMethod:'mouseExited' as:[ Transcript showCR:'onExited'. java closeBridge. ].

"/register the mouse listener on the button and make the frame with button visible
button addMouseListener:listener.
frame add:button.
frame setSize:300 y:100.
frame setVisible: true.
</PRE></CODE>



==Differences between v1 and v2==
===General===
* A Java Bridge instance no longer requires multiple tcp ports to be open. This simplifies connection through ssh tunnels and firewalls.
* The identity of strings and primitve wrappers can be preserved. (see [[#boxedDo:aBlock | boxedDo]])
* Arrays of primitive types are serialized. (see [[#Arrays | Arrays]])

===Loading Applications===
* '''addJarByPath:''' and '''addToClassPath:''' are still supported but have been deprecated. use '''loadJar:''', '''loadJarByPath:''' and '''loadExtension:''' instead. The new methods no longer require the jar or library to be present on the remote machine.

[[Java Interface Library#Loading Applications (from the expecco side) | v1]] [[#Loading Applications (from the expecco side) | v2]]

===Java Class Access===
* Sending the fully qualified name with instances of "." replaced by "_" to the bridge handle is still supported, but not recommended.
* A new method '''getJavaClass:''' has been introduced (also available for v1 since expecco v2.9). This solves the side effects of "_" being a legal character in class names.

[[Java Interface Library#Java Package Import and Class Access | v1]] [[#Java Class Access | v2]]
===Callbacks from Java===
* A new method '''implementMethod:as:''' has been introduced to assign callback blocks to method names. The old way is still supported.

[[Java Interface Library#Callbacks from Java | v1]] [[#Callbacks from Java | v2]]

===Remote Dynamic Code Injection===
* Code injection was problematic in v1 and has now been re-implemented in v2.

[[#Remote Dynamic Code Injection | v2]]

== API ==
===JAVA::Java===
====class protocol====
=====newWithServer=====
* This will start a local JavaVM, running the JavaBridge, and establishes a connection on a random free port.
: A new connected instance of JAVA::Java class is returned.

=====newWithServerForJavaPath:aJavaPathFilename=====
* This is the same as newWithServer but the path to the java executable can be specified. The JavaVM version must be 1.6 or higher to run the JavaBridge.
:: '''aJavaPathFilename''' - must be a instance of Filename
Smalltalk: JAVA::Java newWithServerForJavaPath:('my\path\to\java.executable'asFilename).
JavaScript: JAVA::Java.newWithServerForJavaPath("my\path\to\java.executable".asFilename());

=====newConnectedTo:aHhostString port:aPortNumber withTimeout:aTimeoutSeconds=====
* This is used to connect to a running JavaBridge on the network. The JavaBridge must be started in server mode on the remote host. After connecting a new connected instance of JAVA::Java is returned.
:: '''aHostString''' - the hostname or IP of the remote machine as String
:: '''aPortNumber ''' - the port on which the remote machine is listening as Number
:: '''aTimeoutSeconds''' - a connect timeout in seconds as Number
Smalltalk: JAVA::Java newConnectedTo:'myHostName' port:4567 withTimeout:30.
JavaScript: JAVA::Java.newConnectedTo_port_withTimeout("myHostName",4567,30);

=====newWaitingForConnectOnHost:aListeningAddressString port:aListeningPortNumber withTimeout:aTimeoutSeconds=====
* This is used to wait for incomming connecions of a running JavaBridge on the network. The JavaBridge must be started in client mode on the remote host. After connecting a new connected instance of JAVA::Java is returned.
:: '''deprecated: aListeningAddressString''' - no longer used. Can be nil.
:: '''aListeningPortNumber ''' - the port on which to listen for incomming connections as Number
:: '''aTimeoutSeconds''' - a connect timeout in seconds as Number, If nil it will wait endless.

=====singletonInstance=====
* This will call newWithServer for the first time and then always returns the same connected JAVA::Java instance until the connection was closed, then a new connected instance is returned.

=====exitAllInstances=====
* This will close all instances of JAVA::Java.

====instance protocol====
=====loadJarByPath:aPath=====
* Adds a jar to the running JavaVM. If the jar depends on other jars or libraries you have to add them too.
:: '''aPath''' - the path to the jar file as String.

=====loadJar:aByteArray=====
* Adds a jar to the running JavaVM. If the jar depends on other jars or libraries you have to add them too.
:: '''aByteArrays''' - a ByteArray containing the JAR file.

=====loadExtension:aPath=====
* Adds a jar to the running JavaVM and caches it for subsequent usages. If the jar depends on other jars you have to add them too.
:: '''aPath''' - the path to the jar file as String.

=====boxedDo:aBlock=====
* Any autoboxed values in aBlock returned from the JavaVM are preserved as such. By default autoboxed values are automatically unboxed. This way, the identity of such objects is preserved.

=====isConnected=====
* Tests if a connection is still established.
:: '''return:''' - true if the connection is still established, else false.

=====isAlive=====
* Tests if a connection is still responding.
:: '''return:''' - true if the connection is still alive, else false. Does a message round trip.

=====closeBridge=====
* This will close the bridge connection. Depending on in which mode the JavaBridge was started, the JavaVM is also closed (-keepAlive startparameter not set).

=====exit=====
* Same as closeBridge.

== See Also==
The [[DOT NET Interface Library| DOTNET Interface Plugin & Library]], which implements a likewise interface for .NET applications/libraries.

<hr>
Back to [[Plugins]]

Java Interface Library v2

2016-06-01T09:19:12Z

Javogel: /* Accessing Arrays */

== Introduction ==

This article discusses version 2 of the Java Bridge (which is as of expecco v2.9 still experimental).
The article for version 1 can be found [[Java Interface Library | here]].

The Java Interface library ("Java Bridge") is used to interact with Java objects inside an external Java Virtual Machine (JVM).

The access to Java objects, classes and programs is done via a framework called "''Java-Bridge''", which is similar in operation to the [[DOT NET Interface Library| dotNET bridge]]. This framework implements transparent forwarding of method (virtual function) calls to Java objects, which exist in a local or remote Java Virtual Machine (JVM). Also, return values, callBacks and exception information are passed back from the Java program to expecco. This is done by a proxy-object mechanism, which catches all function calls, wraps the arguments, sends a datagram to the other bridge side, awaits the reply and returns the result to the original caller. Thus, remote procedure calls are almost completely transparent to the Smalltalk/JavaScript code inside expecco. In your elementary code, you can write remote function calls as if they were to local objects.

Notice that this document describes the low level framework, which implements the bridge communication. A much easier to use high level interface (called "Groovy Blocks") exists and should normally be used, if you need access to a java application's internals during testing.
Please take a look at
[[Expecco_API#Groovy_Elementary_Blocks | "Groovy Block API"]]
and [[Testing Java Applications using Groovy blocks/en | "Testing Java Applications using Groovy blocks"]].

== Architecture ==

On the expecco side, the bridge consists of a number of Proxy objects,
which behave like regular Smalltalk objects as seen from elementary expecco code.
However, instead of performing an action when one of their methods (virtual functions) is called,
they send a message over a socket connection to the Java VM (actually: to a bridge software inside the
Java application) which decodes the message and sends it to the destination Java object.
The same is done in reverse direction with the return value.

+---------------------+ +----------+ +----------------+ +----------------+ +---------+
| | | | | | | | | Java |
| expecco |---->| Proxy |---->| Bridge |==>>==| Bridge |---->| Object |
| (elementary code) |<----| |<----| (expecco side) |==<<==| (Java side) |<----| |
+---------------------+ +----------+ +----------------+ +----------------+ +---------+

This setup allows for transparent communication with objects inside a local or remote Java VM. This may be either utility functions which happen to be convenient for the test application (for example: file parsing, syntax analysis, protocol implementaitons or access to specific hardware via driver libraries), or the tested application in the system under test itself.

Especially, it allows for the objects of the tested application to be looked into, manipulated and for functions of it or underlying frameworks to be called.

For expecco code, we tried to make this as transparent as possible, however there are a few exceptions, when function names need to be translated (for example, because the function naming syntax is different) or due to the fact that for some operations no corresponding name exists in Smalltalk (array access, for example).

Of course, multiple such connections can coexist and be served/handled in parallel. This enables an expecco test suite to communicate with both sides of a tested client-server Java application, for example.

Notice that a similar mechanism is used in expecco to communicate with DOTNET, Qt (C++) and C applications.

 

== Activating the new Java Bridge ==
To activate the new bridge in expecco navigate to <CODE>Extras -> Settings -> Plugins -> Java Bridge</CODE> and tick the '''Use new Bridge (experimental)''' checkbox.
[[Datei:ActivateNewJavaBridge.png]]

'''Attention:''' Ticking the checkbox will terminate all currently active Bridge connections due to incompatibilities between the new and the old version.

== Initializing / Releasing the Bridge ==

Before any communication can take place between expecco and any Java object, the Java side of the bridge has to be started, and a communication has to be established.
In expecco, all of the bridge classes are found in the <CODE>JAVA</CODE> namespace.

The main interface class is "<CODE>Java</CODE>", in the "<CODE>JAVA</CODE>" namespace:
<CODE><PRE>
java := JAVA::Java newWithServer.
</PRE></CODE>
or (in JavaScript):
<CODE><PRE>
java = JAVA::Java.newWithServer();
</PRE></CODE>

This starts the Java-side of the bridge (actually executes java as a background command) on the local machine, and establishes a connection to that JVM.

The bridge connection should be closed, if the bridge is no longer needed. Release the bridge with:
<CODE><PRE>
java.closeBridge();
</PRE></CODE>
which terminates the connection.

=== Start and Connect to a Remote Machine ===
The above started a Java VM and connected to it. Alternatively, you may want to connect to an already running Java program (typically, your system under test).
In order for your program to be reachable, it must allow for the bridge to connect to it via a special bridge-connection, which is a socket connection. For this, it must execute the server code found in the "JavaBridge.jar" file. To pass [[#Startup Parameters| parameters]] you will typically start it from a command line or a little shell/batch script.

Call (on the shell/cmd level):
$ java -jar <PATH_TO_JAVABRIDGE.JAR> <PARAMETERS>

The "JavaBridge.jar" file is found in the installation directory of expecco at:
\exept\expecco\packages\exept\bridgeFramework\javaBridge\javaBin\JavaBridge.jar

The Javabridge code allows for either side to initiate the connection - i.e. it can be run in server mode,
where it awaits an incoming connection, or in client mode, where it actively initiates a connection.
After connection establishment, there is no difference in the operation of the bridge, however depending on the setup of your network infrastructure, especially firewalls, either mechanism may be easier to be used.

Assuming that the bridge is already running on the remote machine as server (default),
use <CODE>newConnectedTo:port:withTimeout:</CODE> to connect to it from the expecco side:
java := JAVA::Java newConnectedTo:'myHost' port:4567 withTimeout:30.
This will initiate the connection setup from the expecco side.

Alternatively, if started in client mode use <CODE>newWaitingForConnectOnHost:port:withTimeout:</CODE>:
java := JAVA::Java newWaitingForConnectOnHost:'localhost' port:4567 withTimeout:30.
which will open a port on the expecco side, and wait until the Java side connects to it.
[[#JAVA::Java|For more details see API]]

====Startup Parameters====
You can use any parameter in any order.
If no parameter is used then the bridge listenes on port 14014 in server mode without keepAlive.
;<code>-help</code>
* Shows the help

;<code>-ip <aHostnameOrIP></code>
* In client mode this specifies the ip or hostname to connect to. In server mode this specifies the ip or hostname to bind to.

;<code>-port <aPortNumber> </code>
* In client mode this specifies the port to connect to. In server mode this specifies the listening port.

;<code>-asClient</code>
* The bridge will start in client mode. If not set the bridge is started in server mode.

;<code>-keepAlive</code>
* By setting this flag the bridge will not exit after the connection has closed and starts to connect or listen again. Otherwise, it will run for a single connection session only.

== Loading Applications (from the expecco side) ==

Normally, you would start your application with the required command line arguments and include the javabridge as jar there. However, in some situations, it may be required to dynamically load other jars into the connected Java VM.
By accessing a classloader, additional classes, or applications as contained in JAR files can be loaded from the expecco side.

This can be used to add a JAR file to the classloader:
<CODE><PRE>
java loadJarByPath:'pathToJarFile'. "/ assuming "java" is a handle as returned from the above connect
</PRE></CODE>

or, if the JAR file is loaded in memory:
<CODE><PRE>
java loadJar:jarByteArray. "/ where "jarByteArray" is a ByteArray containing the JAR file
</PRE></CODE>

If the JVM is on a remote machine, the path is resolved on the expecco side and the JAR will be transferred to the remote side.

Should transferring the JAR be too much overhead, an additional mechanism is provided:
<CODE><PRE>
java loadExtension:'pathToJarFile'.
</PRE></CODE>
this will cache the JAR file on the bridge side and eliminate the overhead of subsequent invocations.

== Java Class Access ==

This following code sample simply references (i.e. accesses) the class "JFrame" from the <CODE>"javax.swing"</CODE> package. The fully specified class name in Java would be <CODE>"javax.swing.JFrame"</CODE>:
<CODE><PRE>
java getJavaClass:'javax.swing.JFrame'
</PRE></CODE>

Or, if you want to load multiple classes:
<CODE><PRE>
java import:'javax.swing.JFrame' import:'javax.swing.JButton'
do:[:jFrame :jButton | "do something with JButton and JFrame" ].
</PRE></CODE>

v2 also supports dynamic compilation of java source code:
<CODE><PRE>
java getJavaClass:'className' fromSource:'classSource'. "/ where classSource is a String containing valid java source code
</PRE></CODE>

and loading precompiled java bytecode:
<CODE><PRE>
java getJavaClass:'className' fromByteCode:byteCode. "/ where byteCode is a ByteArray containing valid java bytecode
</PRE></CODE>

[[#Remote Dynamic Code Injection | for details see Remote Dynamic Code Injection]]

== Instantiating a Class ==

Object instances are created via the "new"-message, sent to a proxy of a Java class. You can get this proxy as described in the previous section. For example, if we want to create a new instance of a "JFrame" and a "JButton", write:
<CODE><PRE>
frame := java getJavaClass:'javax.swing.JFrame' new.
button := java getJavaClass:'javax.swing.JButton' new.
</PRE></CODE>
The first statement results in a proxy object for the "JFrame" instance. The second line results in a proxy for a new "JButton" object.

== Calling Instance Methods ==

A method call is done by a message send to a proxy object, where the message is the method name to call. For example, to call the <CODE>"setVisible(boolean isVisible)"</CODE> method on the above JFrame object, we send the following message to that proxy:
<CODE><PRE>
frame setVisible:true.
</PRE></CODE>

As method naming is different in Smalltalk and Java, a dynamic translation is applied when sending messages from Smalltalk code to a remote Java object. Smalltalk has arguments embedded inside parts of a so called "keyword" message, such as in "receiver foo:arg1 bar:arg2", where "foo:bar:" would be the message name, and "arg1", "arg2" be the arguments.

In Java, the message name is a single identifier, and arguments are written in an argument list after the message name: "receiver.fooBar(arg1, arg2)".

When message names are translated, only the very first part of the Smalltalk keyword message is taken ("foo" in the above example), and the remaining parts are simpl ignored. Thus, any of the Smalltalk messages "foo:bar:", "foo:xxxx:" and "foo:_:" (a single underscore as second part) all translate to the same Java message name "foo()".

Therefore, to call a method with more than one argument, like <CODE>"setSize(int width,int height)"</CODE> on a JFrame instance we can write:
<CODE><PRE>
frame setSize:300 _:200.
</PRE></CODE>
but just as well:
<CODE><PRE>
frame setSize:300 anyWord:200.
</PRE></CODE>
or any other selector with "setSize:" as its first component.
The selector translation mechanism simply takes the first part as the Java selector.

In practice, you should take a reasonably descriptive name, such as: "frame setSize:300 height:200" or only the Java name as first part, such as "frame setSize:300 _:200".

For a call of a method with 4 arguments, we could write:
<CODE><PRE>
frame setBounds:100 y:50 width:300 height:200.
</PRE></CODE>
or:
<CODE><PRE>
frame setBounds:100 _:50 _:300 _:200.
</PRE></CODE>

Also here the <CODE>"y: width: height:"</CODE> can be named as you want, but the first part must be "setBounds:".

=== Calling Static Methods ===

Calling a static method on an object is not different from calling non static methods. In most cases you will call a static method not on an object but directly on the class. This is done by using the class object as "receiver" of the message. For example, if we want to call the static method <CODE>"isDefaultLookAndFeelDecorated()"</CODE> of the JFrame class, write:
<CODE><PRE>
java getJavaClass:'javax.swing.JFrame' isDefaultLookAndFeelDecorated.
</PRE></CODE>

== Accessing Fields ==

As Smalltalk does not support access of an object's fields from the outside (it is fully encapsulated, and access from outside is ONLY allowed via getters/setters), an additional translation mechanism is provided for field access.

Accessing a field of a Java object or a class's static field uses the same syntax as method calls. To access a field, send a message where the message is the field name. To access the field of a class the field must be static.
For example, to get the value of the static field named <CODE>"EXIT_ON_CLOSE"</CODE> of the "JFrame" class, write
<CODE><PRE>
value := java getJavaClass:'javax.swing.JFrame' EXIT_ON_CLOSE.
</PRE></CODE>
The variable "value" now holds the integer value of the <CODE>"EXIT_ON_CLOSE"</CODE> constant.

Assuming that a "JFrame" object had a field named <CODE>"myField"</CODE>, to access this field, we'd have to write:
<CODE><PRE>
value := frame myField.
</PRE></CODE>
and "value" now holding whatever <CODE>"myField"</CODE> returns. This could be another object reference or any primitive value.

=== Setting Fields ===
To set a field, use a setter-like method call:
<CODE><PRE>
frame myField: newValue.
</PRE></CODE>

=== Name Conflicts ===

In very rare situations, a Java object may contain both a field and a method by the same name.
In this case, the Smalltalk code cannot depend on the dynamic translation mechanism (which actually looks for either a field or method name to match), but instead make it explicit, which operation is wanted:
Use:
<CODE><PRE>
frame getFieldByName:'myField'
</PRE></CODE>
to read a field, and:
<CODE><PRE>
frame setFieldByName:'myField' value:123.
</PRE></CODE>
to write the field.

If there are both fields and methods by the same name, and you use the non-explicit call,
the bridge will always assume that you want to call the getter/setter and perform a method call.
 

== Arrays ==

=== Passing Smalltalk Collections to Java ===

Smalltalk collections can now be directly passed to Java with a few limitations:
* The identity of the Smalltalk collections will not be preserved. passing the same collection to java multiple times will result in multiple instances of the same array on the java side. (to bypass this instantiate a new java array)
* Smalltalk collections need to be explicitly converted to the correct type (e.g. a <CODE>SignedIntegerArray</CODE> on the smalltal side matches an <CODE>int</CODE>-Array on the java side)

=== Instantiating Arrays ===

The new bridge supports instantiation of arrays (whereas previously reflection had to be used to instantiate arrays from the smalltalk side).
There are two ways an array can be instantiated:

<CODE><PRE>
intArray := java getJavaClass:'[I' new:#[ 1 2 3 4 5 ] asSignedIntegerArray. "/ instantiates a new array of type "int" with the contents "1, 2, 3, 4, 5"
</PRE></CODE>

<CODE><PRE>
intArray := java getJavaClass:'[I' new:10. "/ instantiates a new empty array of type "int" with 10 elements.
</PRE></CODE>

=== Accessing Arrays ===

To achieve better performance, arrays of primitive types smaller than a certain size have their contents cached on the smalltalk side:
<CODE><PRE>
intArray contents at:1. "/ this will access the first element of the cached contents.
</PRE></CODE>

large arrays are not serialized immediately. large arrays will be serialized when <CODE>contents</CODE> is called the first time.

'''Attention:''' Java arrays are not immutable. changes to an array are not reflected in the cached contents. if an array has been updated, call <CODE>refresh</CODE> on the array to update the cache. arrays will not be updated automatically.

<CODE><PRE>
shortArray := (java getJavaClass:'[S') new:10. "/ new empty "short" array with 10 elements

"/ copy the contents of the smalltalk collection to the newly instantiated short array
(java getJavaClass:'java.lang.System') arraycopy:(#[ 1 2 3 ] asSignedWordArray) srcPos:0 dest:shortArray destPos:0 length:3.

shortArray at:0. "/ will reflect the changes made to the array

shortArray contents at:1. "/ will still return 0 because the cached contents have not been updated.

shortArray refresh. "/ update the cached contents

shortArray contents at:1. "/ will now correctly reflect the changes made to the array
</PRE></CODE>

== Callbacks from Java ==
Sometimes you may want to execute a piece of Smalltalk code during the execution of the Java code. For example, we may want to install a Smalltalk observer to be notified when a button on a Java GUI was pressed,
or some other callback from a Java framework.

The following code registers a Smalltalk block as a callback for a mouse press event of a button:
<CODE><PRE>
listener := MouseListener new.
listener implementMethod:'mousePressed' as:[ Transcript showCR:'Hello from Java' ].
</PRE></CODE>
The above creates the callback and the listener, which can now be registered on a button:
<CODE><PRE>
button addMouseListener:listener.
</PRE></CODE>
Now, with the press of the button in the Java GUI, the Smalltalk block will be executed and writes <CODE>"Hello from Java"</CODE> to the Smalltalk console.
Of course, any other (Smalltalk-)action code can be made to run via this mechanism.

But be aware, that the callback is possibly called later (when the elementary action, which installed the code, has already finished long ago). Also, as the Java code execution is not synchronized with any of your expecco action execution, the callback may also be called at any arbutrary time, even at times when no activity at all is executed on the expecco side. If you forget to cleanup, and the Java object is still alive, it may even be called after you have finished your test run (if you keep the java bridge handle around and alive, for example in an expecoo environment variable).

So the Smalltalk callback code should not depend on any particular elementary action to be currently running, but instead in most cases write some information into a shared data container, preferably an instance of "SharedQueue", which is thread safe. Then, some other action (an elementary action) would read-wait and read events from that shared queue.

make sure that your test correctly cleans up any such callbacks afterwards. As a last resort, use the "Shutdown Bridge Connection" menu item, which closes the bridge connection, and thereby - as a side effect - removes any leftover callbacks. It does close the connection, and any remaining java proxy object handles become invalid, though.

Another example, using an observer could look like:
<CODE><PRE>
observer := java Observer new.
observer implementMethod:'update'
as:[:sourceObservable :argument|
argument notNil ifTrue:[ Transcript showCR:('I was notifyed with: ',argument toString) ]
ifFalse:[ Transcript showCR:'I was notifyed and the argument was nil' ].
].
myObservable addObserver:observer.
</PRE></CODE>
When the observable calls <CODE>"notifyObservers"</CODE>, the Smalltalk block will be executed.

== Exceptions in Java ==
Exceptions on the Java side are signalled back to the Smalltalk side and raise a corresponding exception there. However, on the Java side, the call stack which lead to the exception has already been unwound at that time (Java exceptions are not proceedable). So a proceed in the Smalltalk-side exception handler only affects the Smalltalk caller, but may leave the Java side in an undefined state.

== Remote Dynamic Code Injection ==
Sometimes we might want to execute code without the overhead of many rpc-messages being sent over the bridge, especially if we want to do something time critical, or want to make execution time measurements.
For this, it is possible to load a class at runtime into the JavaVM. The code of the class will first be sent to the JavaVM, which will compile and load the generated byte code. Then, the class can be accessed via the bridge just like any other preloaded class.

The following example specifies the class code in a smalltalk string and inject the code into the JavaVM. Then an instance of that new class will be instantiated and finally a method of the object instance will be invoked:
<CODE><PRE>
classCode := '
package myPackage.test;

import java.awt.BorderLayout;
import java.awt.event.MouseAdapter;
import java.awt.event.MouseEvent;
import java.util.Calendar;

import javax.swing.JButton;
import javax.swing.JFrame;
import javax.swing.JLabel;;

public class MyInjectedClass {
public void createSampleApp(){
JFrame frame=new JFrame("Hello im injected");
frame.setLayout(new BorderLayout());
JButton button=new JButton("click me");
final JLabel label=new JLabel("Text");
button.addMouseListener(new MouseAdapter() {

@Override
public void mouseClicked(MouseEvent e) {
label.setText(Calendar.getInstance().getTime().toString());
}
});
frame.add(label,BorderLayout.NORTH);
frame.add(button,BorderLayout.SOUTH);
frame.setSize(300, 300);
frame.setVisible(true);
}
}
'.
classObject := java getJavaClass:'myPackage.test.MyInjectedClass' fromSource:classCode.
classObject new createSampleApp.
</PRE></CODE>
After the code has been injected, a new instance of <CODE>"MyInjectedClass"</CODE> is created and the <CODE>"createSampleApp"</CODE> method is called. Because the example implements a GUI, a Java window will open, containing a label and a button. Clicking the button displays the current time in the label.



=== Code Sources for Class injection ===
There are 3 possible types of class code sources which we can use to inject the code. In the examples before we directly used a simple <CODE>"String"</CODE> in the smalltalk code as a code source. We also can use a <CODE>"*.java"</CODE> file as source. Just read the content of the file into a string and use it as in the previous examples.

To inject a <CODE>"*.class"</CODE> file use the following code:
<pre>
java getJavaClass:'the.class.name' fromByteCode:classCode.
</pre>

== Examples ==

This example creates a JFrame with one button inside. Then a Mouselistener is created and registered on the button. When the button is pressed, the title of the window changes to <CODE>"onPressed"</CODE> and the Transcript shows the message <CODE>"onPressed"</CODE>. When the button is released, the title of the window is changed to <CODE>"onReleased"</CODE> and the Transcript shows <CODE>"onReleased"</CODE>. If the button lost the mouse focus, the bridge will exit (disconnect), and the Java side is terminated.
<CODE><PRE>
|java frame button listener|

"/getting a bridge
java := JAVA::JavaBridge newWithServer.

"/creating a new frame and button object
frame := java getJavaClass:'javax.swing.JFrame' new.
button := java JButton new:'Click'.

"/creating a new mouse listener and adding callback blocks
listener := java MouseListener new.

listener implementMethod:'mousePressed' as:[ Transcript showCR:'onPress'. frame setTitle:'onPressed' ].
listener implementMethod:'mouseReleased' as:[ Transcript showCR:'onReleased'. frame setTitle:'onReleased' ].
listener implementMethod:'mouseExited' as:[ Transcript showCR:'onExited'. java closeBridge. ].

"/register the mouse listener on the button and make the frame with button visible
button addMouseListener:listener.
frame add:button.
frame setSize:300 y:100.
frame setVisible: true.
</PRE></CODE>



==Differences between v1 and v2==
===General===
* A Java Bridge instance no longer requires multiple tcp ports to be open. This simplifies connection through ssh tunnels and firewalls.
* The identity of strings and primitve wrappers can be preserved. (see [[#boxedDo:aBlock | boxedDo]])
* Arrays of primitive types are serialized. (see [[#Arrays | Arrays]])

===Loading Applications===
* '''addJarByPath:''' and '''addToClassPath:''' are still supported but have been deprecated. use '''loadJar:''', '''loadJarByPath:''' and '''loadExtension:''' instead. The new methods no longer require the jar or library to be present on the remote machine.

[[Java Interface Library#Loading Applications (from the expecco side) | v1]] [[#Loading Applications (from the expecco side) | v2]]

===Java Class Access===
* Sending the fully qualified name with instances of "." replaced by "_" to the bridge handle is still supported, but not recommended.
* A new method '''getJavaClass:''' has been introduced (also available for v1 since expecco v2.9). This solves the side effects of "_" being a legal character in class names.

[[Java Interface Library#Java Package Import and Class Access | v1]] [[#Java Class Access | v2]]
===Callbacks from Java===
* A new method '''implementMethod:as:''' has been introduced to assign callback blocks to method names. The old way is still supported.

[[Java Interface Library#Callbacks from Java | v1]] [[#Callbacks from Java | v2]]

===Remote Dynamic Code Injection===
* Code injection was problematic in v1 and has now been re-implemented in v2.

[[#Remote Dynamic Code Injection | v2]]

== API ==
===JAVA::Java===
====class protocol====
=====newWithServer=====
* This will start a local JavaVM, running the JavaBridge, and establishes a connection on a random free port.
: A new connected instance of JAVA::Java class is returned.

=====newWithServerForJavaPath:aJavaPathFilename=====
* This is the same as newWithServer but the path to the java executable can be specified. The JavaVM version must be 1.6 or higher to run the JavaBridge.
:: '''aJavaPathFilename''' - must be a instance of Filename
Smalltalk: JAVA::Java newWithServerForJavaPath:('my\path\to\java.executable'asFilename).
JavaScript: JAVA::Java.newWithServerForJavaPath("my\path\to\java.executable".asFilename());

=====newConnectedTo:aHhostString port:aPortNumber withTimeout:aTimeoutSeconds=====
* This is used to connect to a running JavaBridge on the network. The JavaBridge must be started in server mode on the remote host. After connecting a new connected instance of JAVA::Java is returned.
:: '''aHostString''' - the hostname or IP of the remote machine as String
:: '''aPortNumber ''' - the port on which the remote machine is listening as Number
:: '''aTimeoutSeconds''' - a connect timeout in seconds as Number
Smalltalk: JAVA::Java newConnectedTo:'myHostName' port:4567 withTimeout:30.
JavaScript: JAVA::Java.newConnectedTo_port_withTimeout("myHostName",4567,30);

=====newWaitingForConnectOnHost:aListeningAddressString port:aListeningPortNumber withTimeout:aTimeoutSeconds=====
* This is used to wait for incomming connecions of a running JavaBridge on the network. The JavaBridge must be started in client mode on the remote host. After connecting a new connected instance of JAVA::Java is returned.
:: '''deprecated: aListeningAddressString''' - no longer used. Can be nil.
:: '''aListeningPortNumber ''' - the port on which to listen for incomming connections as Number
:: '''aTimeoutSeconds''' - a connect timeout in seconds as Number, If nil it will wait endless.

=====singletonInstance=====
* This will call newWithServer for the first time and then always returns the same connected JAVA::Java instance until the connection was closed, then a new connected instance is returned.

=====exitAllInstances=====
* This will close all instances of JAVA::Java.

====instance protocol====
=====loadJarByPath:aPath=====
* Adds a jar to the running JavaVM. If the jar depends on other jars or libraries you have to add them too.
:: '''aPath''' - the path to the jar file as String.

=====loadJar:aByteArray=====
* Adds a jar to the running JavaVM. If the jar depends on other jars or libraries you have to add them too.
:: '''aByteArrays''' - a ByteArray containing the JAR file.

=====loadExtension:aPath=====
* Adds a jar to the running JavaVM and caches it for subsequent usages. If the jar depends on other jars you have to add them too.
:: '''aPath''' - the path to the jar file as String.

=====boxedDo:aBlock=====
* Any autoboxed values in aBlock returned from the JavaVM are preserved as such. By default autoboxed values are automatically unboxed. This way, the identity of such objects is preserved.

=====isConnected=====
* Tests if a connection is still established.
:: '''return:''' - true if the connection is still established, else false.

=====isAlive=====
* Tests if a connection is still responding.
:: '''return:''' - true if the connection is still alive, else false. Does a message round trip.

=====closeBridge=====
* This will close the bridge connection. Depending on in which mode the JavaBridge was started, the JavaVM is also closed (-keepAlive startparameter not set).

=====exit=====
* Same as closeBridge.

== See Also==
The [[DOT NET Interface Library| DOTNET Interface Plugin & Library]], which implements a likewise interface for .NET applications/libraries.

<hr>
Back to [[Plugins]]

Java Interface Library v2

2016-06-01T09:07:13Z

Javogel: /* Accessing Arrays */

== Introduction ==

This article discusses version 2 of the Java Bridge (which is as of expecco v2.9 still experimental).
The article for version 1 can be found [[Java Interface Library | here]].

The Java Interface library ("Java Bridge") is used to interact with Java objects inside an external Java Virtual Machine (JVM).

The access to Java objects, classes and programs is done via a framework called "''Java-Bridge''", which is similar in operation to the [[DOT NET Interface Library| dotNET bridge]]. This framework implements transparent forwarding of method (virtual function) calls to Java objects, which exist in a local or remote Java Virtual Machine (JVM). Also, return values, callBacks and exception information are passed back from the Java program to expecco. This is done by a proxy-object mechanism, which catches all function calls, wraps the arguments, sends a datagram to the other bridge side, awaits the reply and returns the result to the original caller. Thus, remote procedure calls are almost completely transparent to the Smalltalk/JavaScript code inside expecco. In your elementary code, you can write remote function calls as if they were to local objects.

Notice that this document describes the low level framework, which implements the bridge communication. A much easier to use high level interface (called "Groovy Blocks") exists and should normally be used, if you need access to a java application's internals during testing.
Please take a look at
[[Expecco_API#Groovy_Elementary_Blocks | "Groovy Block API"]]
and [[Testing Java Applications using Groovy blocks/en | "Testing Java Applications using Groovy blocks"]].

== Architecture ==

On the expecco side, the bridge consists of a number of Proxy objects,
which behave like regular Smalltalk objects as seen from elementary expecco code.
However, instead of performing an action when one of their methods (virtual functions) is called,
they send a message over a socket connection to the Java VM (actually: to a bridge software inside the
Java application) which decodes the message and sends it to the destination Java object.
The same is done in reverse direction with the return value.

+---------------------+ +----------+ +----------------+ +----------------+ +---------+
| | | | | | | | | Java |
| expecco |---->| Proxy |---->| Bridge |==>>==| Bridge |---->| Object |
| (elementary code) |<----| |<----| (expecco side) |==<<==| (Java side) |<----| |
+---------------------+ +----------+ +----------------+ +----------------+ +---------+

This setup allows for transparent communication with objects inside a local or remote Java VM. This may be either utility functions which happen to be convenient for the test application (for example: file parsing, syntax analysis, protocol implementaitons or access to specific hardware via driver libraries), or the tested application in the system under test itself.

Especially, it allows for the objects of the tested application to be looked into, manipulated and for functions of it or underlying frameworks to be called.

For expecco code, we tried to make this as transparent as possible, however there are a few exceptions, when function names need to be translated (for example, because the function naming syntax is different) or due to the fact that for some operations no corresponding name exists in Smalltalk (array access, for example).

Of course, multiple such connections can coexist and be served/handled in parallel. This enables an expecco test suite to communicate with both sides of a tested client-server Java application, for example.

Notice that a similar mechanism is used in expecco to communicate with DOTNET, Qt (C++) and C applications.

 

== Activating the new Java Bridge ==
To activate the new bridge in expecco navigate to <CODE>Extras -> Settings -> Plugins -> Java Bridge</CODE> and tick the '''Use new Bridge (experimental)''' checkbox.
[[Datei:ActivateNewJavaBridge.png]]

'''Attention:''' Ticking the checkbox will terminate all currently active Bridge connections due to incompatibilities between the new and the old version.

== Initializing / Releasing the Bridge ==

Before any communication can take place between expecco and any Java object, the Java side of the bridge has to be started, and a communication has to be established.
In expecco, all of the bridge classes are found in the <CODE>JAVA</CODE> namespace.

The main interface class is "<CODE>Java</CODE>", in the "<CODE>JAVA</CODE>" namespace:
<CODE><PRE>
java := JAVA::Java newWithServer.
</PRE></CODE>
or (in JavaScript):
<CODE><PRE>
java = JAVA::Java.newWithServer();
</PRE></CODE>

This starts the Java-side of the bridge (actually executes java as a background command) on the local machine, and establishes a connection to that JVM.

The bridge connection should be closed, if the bridge is no longer needed. Release the bridge with:
<CODE><PRE>
java.closeBridge();
</PRE></CODE>
which terminates the connection.

=== Start and Connect to a Remote Machine ===
The above started a Java VM and connected to it. Alternatively, you may want to connect to an already running Java program (typically, your system under test).
In order for your program to be reachable, it must allow for the bridge to connect to it via a special bridge-connection, which is a socket connection. For this, it must execute the server code found in the "JavaBridge.jar" file. To pass [[#Startup Parameters| parameters]] you will typically start it from a command line or a little shell/batch script.

Call (on the shell/cmd level):
$ java -jar <PATH_TO_JAVABRIDGE.JAR> <PARAMETERS>

The "JavaBridge.jar" file is found in the installation directory of expecco at:
\exept\expecco\packages\exept\bridgeFramework\javaBridge\javaBin\JavaBridge.jar

The Javabridge code allows for either side to initiate the connection - i.e. it can be run in server mode,
where it awaits an incoming connection, or in client mode, where it actively initiates a connection.
After connection establishment, there is no difference in the operation of the bridge, however depending on the setup of your network infrastructure, especially firewalls, either mechanism may be easier to be used.

Assuming that the bridge is already running on the remote machine as server (default),
use <CODE>newConnectedTo:port:withTimeout:</CODE> to connect to it from the expecco side:
java := JAVA::Java newConnectedTo:'myHost' port:4567 withTimeout:30.
This will initiate the connection setup from the expecco side.

Alternatively, if started in client mode use <CODE>newWaitingForConnectOnHost:port:withTimeout:</CODE>:
java := JAVA::Java newWaitingForConnectOnHost:'localhost' port:4567 withTimeout:30.
which will open a port on the expecco side, and wait until the Java side connects to it.
[[#JAVA::Java|For more details see API]]

====Startup Parameters====
You can use any parameter in any order.
If no parameter is used then the bridge listenes on port 14014 in server mode without keepAlive.
;<code>-help</code>
* Shows the help

;<code>-ip <aHostnameOrIP></code>
* In client mode this specifies the ip or hostname to connect to. In server mode this specifies the ip or hostname to bind to.

;<code>-port <aPortNumber> </code>
* In client mode this specifies the port to connect to. In server mode this specifies the listening port.

;<code>-asClient</code>
* The bridge will start in client mode. If not set the bridge is started in server mode.

;<code>-keepAlive</code>
* By setting this flag the bridge will not exit after the connection has closed and starts to connect or listen again. Otherwise, it will run for a single connection session only.

== Loading Applications (from the expecco side) ==

Normally, you would start your application with the required command line arguments and include the javabridge as jar there. However, in some situations, it may be required to dynamically load other jars into the connected Java VM.
By accessing a classloader, additional classes, or applications as contained in JAR files can be loaded from the expecco side.

This can be used to add a JAR file to the classloader:
<CODE><PRE>
java loadJarByPath:'pathToJarFile'. "/ assuming "java" is a handle as returned from the above connect
</PRE></CODE>

or, if the JAR file is loaded in memory:
<CODE><PRE>
java loadJar:jarByteArray. "/ where "jarByteArray" is a ByteArray containing the JAR file
</PRE></CODE>

If the JVM is on a remote machine, the path is resolved on the expecco side and the JAR will be transferred to the remote side.

Should transferring the JAR be too much overhead, an additional mechanism is provided:
<CODE><PRE>
java loadExtension:'pathToJarFile'.
</PRE></CODE>
this will cache the JAR file on the bridge side and eliminate the overhead of subsequent invocations.

== Java Class Access ==

This following code sample simply references (i.e. accesses) the class "JFrame" from the <CODE>"javax.swing"</CODE> package. The fully specified class name in Java would be <CODE>"javax.swing.JFrame"</CODE>:
<CODE><PRE>
java getJavaClass:'javax.swing.JFrame'
</PRE></CODE>

Or, if you want to load multiple classes:
<CODE><PRE>
java import:'javax.swing.JFrame' import:'javax.swing.JButton'
do:[:jFrame :jButton | "do something with JButton and JFrame" ].
</PRE></CODE>

v2 also supports dynamic compilation of java source code:
<CODE><PRE>
java getJavaClass:'className' fromSource:'classSource'. "/ where classSource is a String containing valid java source code
</PRE></CODE>

and loading precompiled java bytecode:
<CODE><PRE>
java getJavaClass:'className' fromByteCode:byteCode. "/ where byteCode is a ByteArray containing valid java bytecode
</PRE></CODE>

[[#Remote Dynamic Code Injection | for details see Remote Dynamic Code Injection]]

== Instantiating a Class ==

Object instances are created via the "new"-message, sent to a proxy of a Java class. You can get this proxy as described in the previous section. For example, if we want to create a new instance of a "JFrame" and a "JButton", write:
<CODE><PRE>
frame := java getJavaClass:'javax.swing.JFrame' new.
button := java getJavaClass:'javax.swing.JButton' new.
</PRE></CODE>
The first statement results in a proxy object for the "JFrame" instance. The second line results in a proxy for a new "JButton" object.

== Calling Instance Methods ==

A method call is done by a message send to a proxy object, where the message is the method name to call. For example, to call the <CODE>"setVisible(boolean isVisible)"</CODE> method on the above JFrame object, we send the following message to that proxy:
<CODE><PRE>
frame setVisible:true.
</PRE></CODE>

As method naming is different in Smalltalk and Java, a dynamic translation is applied when sending messages from Smalltalk code to a remote Java object. Smalltalk has arguments embedded inside parts of a so called "keyword" message, such as in "receiver foo:arg1 bar:arg2", where "foo:bar:" would be the message name, and "arg1", "arg2" be the arguments.

In Java, the message name is a single identifier, and arguments are written in an argument list after the message name: "receiver.fooBar(arg1, arg2)".

When message names are translated, only the very first part of the Smalltalk keyword message is taken ("foo" in the above example), and the remaining parts are simpl ignored. Thus, any of the Smalltalk messages "foo:bar:", "foo:xxxx:" and "foo:_:" (a single underscore as second part) all translate to the same Java message name "foo()".

Therefore, to call a method with more than one argument, like <CODE>"setSize(int width,int height)"</CODE> on a JFrame instance we can write:
<CODE><PRE>
frame setSize:300 _:200.
</PRE></CODE>
but just as well:
<CODE><PRE>
frame setSize:300 anyWord:200.
</PRE></CODE>
or any other selector with "setSize:" as its first component.
The selector translation mechanism simply takes the first part as the Java selector.

In practice, you should take a reasonably descriptive name, such as: "frame setSize:300 height:200" or only the Java name as first part, such as "frame setSize:300 _:200".

For a call of a method with 4 arguments, we could write:
<CODE><PRE>
frame setBounds:100 y:50 width:300 height:200.
</PRE></CODE>
or:
<CODE><PRE>
frame setBounds:100 _:50 _:300 _:200.
</PRE></CODE>

Also here the <CODE>"y: width: height:"</CODE> can be named as you want, but the first part must be "setBounds:".

=== Calling Static Methods ===

Calling a static method on an object is not different from calling non static methods. In most cases you will call a static method not on an object but directly on the class. This is done by using the class object as "receiver" of the message. For example, if we want to call the static method <CODE>"isDefaultLookAndFeelDecorated()"</CODE> of the JFrame class, write:
<CODE><PRE>
java getJavaClass:'javax.swing.JFrame' isDefaultLookAndFeelDecorated.
</PRE></CODE>

== Accessing Fields ==

As Smalltalk does not support access of an object's fields from the outside (it is fully encapsulated, and access from outside is ONLY allowed via getters/setters), an additional translation mechanism is provided for field access.

Accessing a field of a Java object or a class's static field uses the same syntax as method calls. To access a field, send a message where the message is the field name. To access the field of a class the field must be static.
For example, to get the value of the static field named <CODE>"EXIT_ON_CLOSE"</CODE> of the "JFrame" class, write
<CODE><PRE>
value := java getJavaClass:'javax.swing.JFrame' EXIT_ON_CLOSE.
</PRE></CODE>
The variable "value" now holds the integer value of the <CODE>"EXIT_ON_CLOSE"</CODE> constant.

Assuming that a "JFrame" object had a field named <CODE>"myField"</CODE>, to access this field, we'd have to write:
<CODE><PRE>
value := frame myField.
</PRE></CODE>
and "value" now holding whatever <CODE>"myField"</CODE> returns. This could be another object reference or any primitive value.

=== Setting Fields ===
To set a field, use a setter-like method call:
<CODE><PRE>
frame myField: newValue.
</PRE></CODE>

=== Name Conflicts ===

In very rare situations, a Java object may contain both a field and a method by the same name.
In this case, the Smalltalk code cannot depend on the dynamic translation mechanism (which actually looks for either a field or method name to match), but instead make it explicit, which operation is wanted:
Use:
<CODE><PRE>
frame getFieldByName:'myField'
</PRE></CODE>
to read a field, and:
<CODE><PRE>
frame setFieldByName:'myField' value:123.
</PRE></CODE>
to write the field.

If there are both fields and methods by the same name, and you use the non-explicit call,
the bridge will always assume that you want to call the getter/setter and perform a method call.
 

== Arrays ==

=== Passing Smalltalk Collections to Java ===

Smalltalk collections can now be directly passed to Java with a few limitations:
* The identity of the Smalltalk collections will not be preserved. passing the same collection to java multiple times will result in multiple instances of the same array on the java side. (to bypass this instantiate a new java array)
* Smalltalk collections need to be explicitly converted to the correct type (e.g. a <CODE>SignedIntegerArray</CODE> on the smalltal side matches an <CODE>int</CODE>-Array on the java side)

=== Instantiating Arrays ===

The new bridge supports instantiation of arrays (whereas previously reflection had to be used to instantiate arrays from the smalltalk side).
There are two ways an array can be instantiated:

<CODE><PRE>
intArray := java getJavaClass:'[I' new:#[ 1 2 3 4 5 ] asSignedIntegerArray. "/ instantiates a new array of type "int" with the contents "1, 2, 3, 4, 5"
</PRE></CODE>

<CODE><PRE>
intArray := java getJavaClass:'[I' new:10. "/ instantiates a new empty array of type "int" with 10 elements.
</PRE></CODE>

=== Accessing Arrays ===

To achieve better performance, arrays of primitive types smaller than a certain size have their contents cached on the smalltalk side:
<CODE><PRE>
intArray contents at:1. "/ this will access the first element of the cached contents.
</PRE></CODE>

large arrays are not serialized immediately. large arrays will be serialized when <CODE>contents</CODE> is called the first time.

'''Attention:''' Java arrays are not immutable. changes to an array are not reflected in the cached contents. if an array has been updated, call <CODE>refresh</CODE> on the array to update the cache. arrays will not be updated automatically.

<CODE><PRE>
shortArray := java getJavaClass:'[S' new:10. "/ new empty "short" array with 10 elements

"/ copy the contents of the smalltalk collection to the newly instantiated short array
(java getJavaClass:'java.lang.System') arraycopy:(#[ 1 2 3 ] asSignedWordArray) srcPos:0 dest:shortArray destPos:0 length:3.

shortArray at:0. "/ will reflect the changes made to the array

shortArray contents at:1. "/ will still return 0 because the cached contents have not been updated.

shortArray refresh. "/ update the cached contents

shortArray contents at:1. "/ will now correctly reflect the changes made to the array
</PRE></CODE>

== Callbacks from Java ==
Sometimes you may want to execute a piece of Smalltalk code during the execution of the Java code. For example, we may want to install a Smalltalk observer to be notified when a button on a Java GUI was pressed,
or some other callback from a Java framework.

The following code registers a Smalltalk block as a callback for a mouse press event of a button:
<CODE><PRE>
listener := MouseListener new.
listener implementMethod:'mousePressed' as:[ Transcript showCR:'Hello from Java' ].
</PRE></CODE>
The above creates the callback and the listener, which can now be registered on a button:
<CODE><PRE>
button addMouseListener:listener.
</PRE></CODE>
Now, with the press of the button in the Java GUI, the Smalltalk block will be executed and writes <CODE>"Hello from Java"</CODE> to the Smalltalk console.
Of course, any other (Smalltalk-)action code can be made to run via this mechanism.

But be aware, that the callback is possibly called later (when the elementary action, which installed the code, has already finished long ago). Also, as the Java code execution is not synchronized with any of your expecco action execution, the callback may also be called at any arbutrary time, even at times when no activity at all is executed on the expecco side. If you forget to cleanup, and the Java object is still alive, it may even be called after you have finished your test run (if you keep the java bridge handle around and alive, for example in an expecoo environment variable).

So the Smalltalk callback code should not depend on any particular elementary action to be currently running, but instead in most cases write some information into a shared data container, preferably an instance of "SharedQueue", which is thread safe. Then, some other action (an elementary action) would read-wait and read events from that shared queue.

make sure that your test correctly cleans up any such callbacks afterwards. As a last resort, use the "Shutdown Bridge Connection" menu item, which closes the bridge connection, and thereby - as a side effect - removes any leftover callbacks. It does close the connection, and any remaining java proxy object handles become invalid, though.

Another example, using an observer could look like:
<CODE><PRE>
observer := java Observer new.
observer implementMethod:'update'
as:[:sourceObservable :argument|
argument notNil ifTrue:[ Transcript showCR:('I was notifyed with: ',argument toString) ]
ifFalse:[ Transcript showCR:'I was notifyed and the argument was nil' ].
].
myObservable addObserver:observer.
</PRE></CODE>
When the observable calls <CODE>"notifyObservers"</CODE>, the Smalltalk block will be executed.

== Exceptions in Java ==
Exceptions on the Java side are signalled back to the Smalltalk side and raise a corresponding exception there. However, on the Java side, the call stack which lead to the exception has already been unwound at that time (Java exceptions are not proceedable). So a proceed in the Smalltalk-side exception handler only affects the Smalltalk caller, but may leave the Java side in an undefined state.

== Remote Dynamic Code Injection ==
Sometimes we might want to execute code without the overhead of many rpc-messages being sent over the bridge, especially if we want to do something time critical, or want to make execution time measurements.
For this, it is possible to load a class at runtime into the JavaVM. The code of the class will first be sent to the JavaVM, which will compile and load the generated byte code. Then, the class can be accessed via the bridge just like any other preloaded class.

The following example specifies the class code in a smalltalk string and inject the code into the JavaVM. Then an instance of that new class will be instantiated and finally a method of the object instance will be invoked:
<CODE><PRE>
classCode := '
package myPackage.test;

import java.awt.BorderLayout;
import java.awt.event.MouseAdapter;
import java.awt.event.MouseEvent;
import java.util.Calendar;

import javax.swing.JButton;
import javax.swing.JFrame;
import javax.swing.JLabel;;

public class MyInjectedClass {
public void createSampleApp(){
JFrame frame=new JFrame("Hello im injected");
frame.setLayout(new BorderLayout());
JButton button=new JButton("click me");
final JLabel label=new JLabel("Text");
button.addMouseListener(new MouseAdapter() {

@Override
public void mouseClicked(MouseEvent e) {
label.setText(Calendar.getInstance().getTime().toString());
}
});
frame.add(label,BorderLayout.NORTH);
frame.add(button,BorderLayout.SOUTH);
frame.setSize(300, 300);
frame.setVisible(true);
}
}
'.
classObject := java getJavaClass:'myPackage.test.MyInjectedClass' fromSource:classCode.
classObject new createSampleApp.
</PRE></CODE>
After the code has been injected, a new instance of <CODE>"MyInjectedClass"</CODE> is created and the <CODE>"createSampleApp"</CODE> method is called. Because the example implements a GUI, a Java window will open, containing a label and a button. Clicking the button displays the current time in the label.



=== Code Sources for Class injection ===
There are 3 possible types of class code sources which we can use to inject the code. In the examples before we directly used a simple <CODE>"String"</CODE> in the smalltalk code as a code source. We also can use a <CODE>"*.java"</CODE> file as source. Just read the content of the file into a string and use it as in the previous examples.

To inject a <CODE>"*.class"</CODE> file use the following code:
<pre>
java getJavaClass:'the.class.name' fromByteCode:classCode.
</pre>

== Examples ==

This example creates a JFrame with one button inside. Then a Mouselistener is created and registered on the button. When the button is pressed, the title of the window changes to <CODE>"onPressed"</CODE> and the Transcript shows the message <CODE>"onPressed"</CODE>. When the button is released, the title of the window is changed to <CODE>"onReleased"</CODE> and the Transcript shows <CODE>"onReleased"</CODE>. If the button lost the mouse focus, the bridge will exit (disconnect), and the Java side is terminated.
<CODE><PRE>
|java frame button listener|

"/getting a bridge
java := JAVA::JavaBridge newWithServer.

"/creating a new frame and button object
frame := java getJavaClass:'javax.swing.JFrame' new.
button := java JButton new:'Click'.

"/creating a new mouse listener and adding callback blocks
listener := java MouseListener new.

listener implementMethod:'mousePressed' as:[ Transcript showCR:'onPress'. frame setTitle:'onPressed' ].
listener implementMethod:'mouseReleased' as:[ Transcript showCR:'onReleased'. frame setTitle:'onReleased' ].
listener implementMethod:'mouseExited' as:[ Transcript showCR:'onExited'. java closeBridge. ].

"/register the mouse listener on the button and make the frame with button visible
button addMouseListener:listener.
frame add:button.
frame setSize:300 y:100.
frame setVisible: true.
</PRE></CODE>



==Differences between v1 and v2==
===General===
* A Java Bridge instance no longer requires multiple tcp ports to be open. This simplifies connection through ssh tunnels and firewalls.
* The identity of strings and primitve wrappers can be preserved. (see [[#boxedDo:aBlock | boxedDo]])
* Arrays of primitive types are serialized. (see [[#Arrays | Arrays]])

===Loading Applications===
* '''addJarByPath:''' and '''addToClassPath:''' are still supported but have been deprecated. use '''loadJar:''', '''loadJarByPath:''' and '''loadExtension:''' instead. The new methods no longer require the jar or library to be present on the remote machine.

[[Java Interface Library#Loading Applications (from the expecco side) | v1]] [[#Loading Applications (from the expecco side) | v2]]

===Java Class Access===
* Sending the fully qualified name with instances of "." replaced by "_" to the bridge handle is still supported, but not recommended.
* A new method '''getJavaClass:''' has been introduced (also available for v1 since expecco v2.9). This solves the side effects of "_" being a legal character in class names.

[[Java Interface Library#Java Package Import and Class Access | v1]] [[#Java Class Access | v2]]
===Callbacks from Java===
* A new method '''implementMethod:as:''' has been introduced to assign callback blocks to method names. The old way is still supported.

[[Java Interface Library#Callbacks from Java | v1]] [[#Callbacks from Java | v2]]

===Remote Dynamic Code Injection===
* Code injection was problematic in v1 and has now been re-implemented in v2.

[[#Remote Dynamic Code Injection | v2]]

== API ==
===JAVA::Java===
====class protocol====
=====newWithServer=====
* This will start a local JavaVM, running the JavaBridge, and establishes a connection on a random free port.
: A new connected instance of JAVA::Java class is returned.

=====newWithServerForJavaPath:aJavaPathFilename=====
* This is the same as newWithServer but the path to the java executable can be specified. The JavaVM version must be 1.6 or higher to run the JavaBridge.
:: '''aJavaPathFilename''' - must be a instance of Filename
Smalltalk: JAVA::Java newWithServerForJavaPath:('my\path\to\java.executable'asFilename).
JavaScript: JAVA::Java.newWithServerForJavaPath("my\path\to\java.executable".asFilename());

=====newConnectedTo:aHhostString port:aPortNumber withTimeout:aTimeoutSeconds=====
* This is used to connect to a running JavaBridge on the network. The JavaBridge must be started in server mode on the remote host. After connecting a new connected instance of JAVA::Java is returned.
:: '''aHostString''' - the hostname or IP of the remote machine as String
:: '''aPortNumber ''' - the port on which the remote machine is listening as Number
:: '''aTimeoutSeconds''' - a connect timeout in seconds as Number
Smalltalk: JAVA::Java newConnectedTo:'myHostName' port:4567 withTimeout:30.
JavaScript: JAVA::Java.newConnectedTo_port_withTimeout("myHostName",4567,30);

=====newWaitingForConnectOnHost:aListeningAddressString port:aListeningPortNumber withTimeout:aTimeoutSeconds=====
* This is used to wait for incomming connecions of a running JavaBridge on the network. The JavaBridge must be started in client mode on the remote host. After connecting a new connected instance of JAVA::Java is returned.
:: '''deprecated: aListeningAddressString''' - no longer used. Can be nil.
:: '''aListeningPortNumber ''' - the port on which to listen for incomming connections as Number
:: '''aTimeoutSeconds''' - a connect timeout in seconds as Number, If nil it will wait endless.

=====singletonInstance=====
* This will call newWithServer for the first time and then always returns the same connected JAVA::Java instance until the connection was closed, then a new connected instance is returned.

=====exitAllInstances=====
* This will close all instances of JAVA::Java.

====instance protocol====
=====loadJarByPath:aPath=====
* Adds a jar to the running JavaVM. If the jar depends on other jars or libraries you have to add them too.
:: '''aPath''' - the path to the jar file as String.

=====loadJar:aByteArray=====
* Adds a jar to the running JavaVM. If the jar depends on other jars or libraries you have to add them too.
:: '''aByteArrays''' - a ByteArray containing the JAR file.

=====loadExtension:aPath=====
* Adds a jar to the running JavaVM and caches it for subsequent usages. If the jar depends on other jars you have to add them too.
:: '''aPath''' - the path to the jar file as String.

=====boxedDo:aBlock=====
* Any autoboxed values in aBlock returned from the JavaVM are preserved as such. By default autoboxed values are automatically unboxed. This way, the identity of such objects is preserved.

=====isConnected=====
* Tests if a connection is still established.
:: '''return:''' - true if the connection is still established, else false.

=====isAlive=====
* Tests if a connection is still responding.
:: '''return:''' - true if the connection is still alive, else false. Does a message round trip.

=====closeBridge=====
* This will close the bridge connection. Depending on in which mode the JavaBridge was started, the JavaVM is also closed (-keepAlive startparameter not set).

=====exit=====
* Same as closeBridge.

== See Also==
The [[DOT NET Interface Library| DOTNET Interface Plugin & Library]], which implements a likewise interface for .NET applications/libraries.

<hr>
Back to [[Plugins]]

Java Interface Library v2

2016-06-01T09:06:28Z

Javogel:

== Introduction ==

This article discusses version 2 of the Java Bridge (which is as of expecco v2.9 still experimental).
The article for version 1 can be found [[Java Interface Library | here]].

The Java Interface library ("Java Bridge") is used to interact with Java objects inside an external Java Virtual Machine (JVM).

The access to Java objects, classes and programs is done via a framework called "''Java-Bridge''", which is similar in operation to the [[DOT NET Interface Library| dotNET bridge]]. This framework implements transparent forwarding of method (virtual function) calls to Java objects, which exist in a local or remote Java Virtual Machine (JVM). Also, return values, callBacks and exception information are passed back from the Java program to expecco. This is done by a proxy-object mechanism, which catches all function calls, wraps the arguments, sends a datagram to the other bridge side, awaits the reply and returns the result to the original caller. Thus, remote procedure calls are almost completely transparent to the Smalltalk/JavaScript code inside expecco. In your elementary code, you can write remote function calls as if they were to local objects.

Notice that this document describes the low level framework, which implements the bridge communication. A much easier to use high level interface (called "Groovy Blocks") exists and should normally be used, if you need access to a java application's internals during testing.
Please take a look at
[[Expecco_API#Groovy_Elementary_Blocks | "Groovy Block API"]]
and [[Testing Java Applications using Groovy blocks/en | "Testing Java Applications using Groovy blocks"]].

== Architecture ==

On the expecco side, the bridge consists of a number of Proxy objects,
which behave like regular Smalltalk objects as seen from elementary expecco code.
However, instead of performing an action when one of their methods (virtual functions) is called,
they send a message over a socket connection to the Java VM (actually: to a bridge software inside the
Java application) which decodes the message and sends it to the destination Java object.
The same is done in reverse direction with the return value.

+---------------------+ +----------+ +----------------+ +----------------+ +---------+
| | | | | | | | | Java |
| expecco |---->| Proxy |---->| Bridge |==>>==| Bridge |---->| Object |
| (elementary code) |<----| |<----| (expecco side) |==<<==| (Java side) |<----| |
+---------------------+ +----------+ +----------------+ +----------------+ +---------+

This setup allows for transparent communication with objects inside a local or remote Java VM. This may be either utility functions which happen to be convenient for the test application (for example: file parsing, syntax analysis, protocol implementaitons or access to specific hardware via driver libraries), or the tested application in the system under test itself.

Especially, it allows for the objects of the tested application to be looked into, manipulated and for functions of it or underlying frameworks to be called.

For expecco code, we tried to make this as transparent as possible, however there are a few exceptions, when function names need to be translated (for example, because the function naming syntax is different) or due to the fact that for some operations no corresponding name exists in Smalltalk (array access, for example).

Of course, multiple such connections can coexist and be served/handled in parallel. This enables an expecco test suite to communicate with both sides of a tested client-server Java application, for example.

Notice that a similar mechanism is used in expecco to communicate with DOTNET, Qt (C++) and C applications.

 

== Activating the new Java Bridge ==
To activate the new bridge in expecco navigate to <CODE>Extras -> Settings -> Plugins -> Java Bridge</CODE> and tick the '''Use new Bridge (experimental)''' checkbox.
[[Datei:ActivateNewJavaBridge.png]]

'''Attention:''' Ticking the checkbox will terminate all currently active Bridge connections due to incompatibilities between the new and the old version.

== Initializing / Releasing the Bridge ==

Before any communication can take place between expecco and any Java object, the Java side of the bridge has to be started, and a communication has to be established.
In expecco, all of the bridge classes are found in the <CODE>JAVA</CODE> namespace.

The main interface class is "<CODE>Java</CODE>", in the "<CODE>JAVA</CODE>" namespace:
<CODE><PRE>
java := JAVA::Java newWithServer.
</PRE></CODE>
or (in JavaScript):
<CODE><PRE>
java = JAVA::Java.newWithServer();
</PRE></CODE>

This starts the Java-side of the bridge (actually executes java as a background command) on the local machine, and establishes a connection to that JVM.

The bridge connection should be closed, if the bridge is no longer needed. Release the bridge with:
<CODE><PRE>
java.closeBridge();
</PRE></CODE>
which terminates the connection.

=== Start and Connect to a Remote Machine ===
The above started a Java VM and connected to it. Alternatively, you may want to connect to an already running Java program (typically, your system under test).
In order for your program to be reachable, it must allow for the bridge to connect to it via a special bridge-connection, which is a socket connection. For this, it must execute the server code found in the "JavaBridge.jar" file. To pass [[#Startup Parameters| parameters]] you will typically start it from a command line or a little shell/batch script.

Call (on the shell/cmd level):
$ java -jar <PATH_TO_JAVABRIDGE.JAR> <PARAMETERS>

The "JavaBridge.jar" file is found in the installation directory of expecco at:
\exept\expecco\packages\exept\bridgeFramework\javaBridge\javaBin\JavaBridge.jar

The Javabridge code allows for either side to initiate the connection - i.e. it can be run in server mode,
where it awaits an incoming connection, or in client mode, where it actively initiates a connection.
After connection establishment, there is no difference in the operation of the bridge, however depending on the setup of your network infrastructure, especially firewalls, either mechanism may be easier to be used.

Assuming that the bridge is already running on the remote machine as server (default),
use <CODE>newConnectedTo:port:withTimeout:</CODE> to connect to it from the expecco side:
java := JAVA::Java newConnectedTo:'myHost' port:4567 withTimeout:30.
This will initiate the connection setup from the expecco side.

Alternatively, if started in client mode use <CODE>newWaitingForConnectOnHost:port:withTimeout:</CODE>:
java := JAVA::Java newWaitingForConnectOnHost:'localhost' port:4567 withTimeout:30.
which will open a port on the expecco side, and wait until the Java side connects to it.
[[#JAVA::Java|For more details see API]]

====Startup Parameters====
You can use any parameter in any order.
If no parameter is used then the bridge listenes on port 14014 in server mode without keepAlive.
;<code>-help</code>
* Shows the help

;<code>-ip <aHostnameOrIP></code>
* In client mode this specifies the ip or hostname to connect to. In server mode this specifies the ip or hostname to bind to.

;<code>-port <aPortNumber> </code>
* In client mode this specifies the port to connect to. In server mode this specifies the listening port.

;<code>-asClient</code>
* The bridge will start in client mode. If not set the bridge is started in server mode.

;<code>-keepAlive</code>
* By setting this flag the bridge will not exit after the connection has closed and starts to connect or listen again. Otherwise, it will run for a single connection session only.

== Loading Applications (from the expecco side) ==

Normally, you would start your application with the required command line arguments and include the javabridge as jar there. However, in some situations, it may be required to dynamically load other jars into the connected Java VM.
By accessing a classloader, additional classes, or applications as contained in JAR files can be loaded from the expecco side.

This can be used to add a JAR file to the classloader:
<CODE><PRE>
java loadJarByPath:'pathToJarFile'. "/ assuming "java" is a handle as returned from the above connect
</PRE></CODE>

or, if the JAR file is loaded in memory:
<CODE><PRE>
java loadJar:jarByteArray. "/ where "jarByteArray" is a ByteArray containing the JAR file
</PRE></CODE>

If the JVM is on a remote machine, the path is resolved on the expecco side and the JAR will be transferred to the remote side.

Should transferring the JAR be too much overhead, an additional mechanism is provided:
<CODE><PRE>
java loadExtension:'pathToJarFile'.
</PRE></CODE>
this will cache the JAR file on the bridge side and eliminate the overhead of subsequent invocations.

== Java Class Access ==

This following code sample simply references (i.e. accesses) the class "JFrame" from the <CODE>"javax.swing"</CODE> package. The fully specified class name in Java would be <CODE>"javax.swing.JFrame"</CODE>:
<CODE><PRE>
java getJavaClass:'javax.swing.JFrame'
</PRE></CODE>

Or, if you want to load multiple classes:
<CODE><PRE>
java import:'javax.swing.JFrame' import:'javax.swing.JButton'
do:[:jFrame :jButton | "do something with JButton and JFrame" ].
</PRE></CODE>

v2 also supports dynamic compilation of java source code:
<CODE><PRE>
java getJavaClass:'className' fromSource:'classSource'. "/ where classSource is a String containing valid java source code
</PRE></CODE>

and loading precompiled java bytecode:
<CODE><PRE>
java getJavaClass:'className' fromByteCode:byteCode. "/ where byteCode is a ByteArray containing valid java bytecode
</PRE></CODE>

[[#Remote Dynamic Code Injection | for details see Remote Dynamic Code Injection]]

== Instantiating a Class ==

Object instances are created via the "new"-message, sent to a proxy of a Java class. You can get this proxy as described in the previous section. For example, if we want to create a new instance of a "JFrame" and a "JButton", write:
<CODE><PRE>
frame := java getJavaClass:'javax.swing.JFrame' new.
button := java getJavaClass:'javax.swing.JButton' new.
</PRE></CODE>
The first statement results in a proxy object for the "JFrame" instance. The second line results in a proxy for a new "JButton" object.

== Calling Instance Methods ==

A method call is done by a message send to a proxy object, where the message is the method name to call. For example, to call the <CODE>"setVisible(boolean isVisible)"</CODE> method on the above JFrame object, we send the following message to that proxy:
<CODE><PRE>
frame setVisible:true.
</PRE></CODE>

As method naming is different in Smalltalk and Java, a dynamic translation is applied when sending messages from Smalltalk code to a remote Java object. Smalltalk has arguments embedded inside parts of a so called "keyword" message, such as in "receiver foo:arg1 bar:arg2", where "foo:bar:" would be the message name, and "arg1", "arg2" be the arguments.

In Java, the message name is a single identifier, and arguments are written in an argument list after the message name: "receiver.fooBar(arg1, arg2)".

When message names are translated, only the very first part of the Smalltalk keyword message is taken ("foo" in the above example), and the remaining parts are simpl ignored. Thus, any of the Smalltalk messages "foo:bar:", "foo:xxxx:" and "foo:_:" (a single underscore as second part) all translate to the same Java message name "foo()".

Therefore, to call a method with more than one argument, like <CODE>"setSize(int width,int height)"</CODE> on a JFrame instance we can write:
<CODE><PRE>
frame setSize:300 _:200.
</PRE></CODE>
but just as well:
<CODE><PRE>
frame setSize:300 anyWord:200.
</PRE></CODE>
or any other selector with "setSize:" as its first component.
The selector translation mechanism simply takes the first part as the Java selector.

In practice, you should take a reasonably descriptive name, such as: "frame setSize:300 height:200" or only the Java name as first part, such as "frame setSize:300 _:200".

For a call of a method with 4 arguments, we could write:
<CODE><PRE>
frame setBounds:100 y:50 width:300 height:200.
</PRE></CODE>
or:
<CODE><PRE>
frame setBounds:100 _:50 _:300 _:200.
</PRE></CODE>

Also here the <CODE>"y: width: height:"</CODE> can be named as you want, but the first part must be "setBounds:".

=== Calling Static Methods ===

Calling a static method on an object is not different from calling non static methods. In most cases you will call a static method not on an object but directly on the class. This is done by using the class object as "receiver" of the message. For example, if we want to call the static method <CODE>"isDefaultLookAndFeelDecorated()"</CODE> of the JFrame class, write:
<CODE><PRE>
java getJavaClass:'javax.swing.JFrame' isDefaultLookAndFeelDecorated.
</PRE></CODE>

== Accessing Fields ==

As Smalltalk does not support access of an object's fields from the outside (it is fully encapsulated, and access from outside is ONLY allowed via getters/setters), an additional translation mechanism is provided for field access.

Accessing a field of a Java object or a class's static field uses the same syntax as method calls. To access a field, send a message where the message is the field name. To access the field of a class the field must be static.
For example, to get the value of the static field named <CODE>"EXIT_ON_CLOSE"</CODE> of the "JFrame" class, write
<CODE><PRE>
value := java getJavaClass:'javax.swing.JFrame' EXIT_ON_CLOSE.
</PRE></CODE>
The variable "value" now holds the integer value of the <CODE>"EXIT_ON_CLOSE"</CODE> constant.

Assuming that a "JFrame" object had a field named <CODE>"myField"</CODE>, to access this field, we'd have to write:
<CODE><PRE>
value := frame myField.
</PRE></CODE>
and "value" now holding whatever <CODE>"myField"</CODE> returns. This could be another object reference or any primitive value.

=== Setting Fields ===
To set a field, use a setter-like method call:
<CODE><PRE>
frame myField: newValue.
</PRE></CODE>

=== Name Conflicts ===

In very rare situations, a Java object may contain both a field and a method by the same name.
In this case, the Smalltalk code cannot depend on the dynamic translation mechanism (which actually looks for either a field or method name to match), but instead make it explicit, which operation is wanted:
Use:
<CODE><PRE>
frame getFieldByName:'myField'
</PRE></CODE>
to read a field, and:
<CODE><PRE>
frame setFieldByName:'myField' value:123.
</PRE></CODE>
to write the field.

If there are both fields and methods by the same name, and you use the non-explicit call,
the bridge will always assume that you want to call the getter/setter and perform a method call.
 

== Arrays ==

=== Passing Smalltalk Collections to Java ===

Smalltalk collections can now be directly passed to Java with a few limitations:
* The identity of the Smalltalk collections will not be preserved. passing the same collection to java multiple times will result in multiple instances of the same array on the java side. (to bypass this instantiate a new java array)
* Smalltalk collections need to be explicitly converted to the correct type (e.g. a <CODE>SignedIntegerArray</CODE> on the smalltal side matches an <CODE>int</CODE>-Array on the java side)

=== Instantiating Arrays ===

The new bridge supports instantiation of arrays (whereas previously reflection had to be used to instantiate arrays from the smalltalk side).
There are two ways an array can be instantiated:

<CODE><PRE>
intArray := java getJavaClass:'[I' new:#[ 1 2 3 4 5 ] asSignedIntegerArray. "/ instantiates a new array of type "int" with the contents "1, 2, 3, 4, 5"
</PRE></CODE>

<CODE><PRE>
intArray := java getJavaClass:'[I' new:10. "/ instantiates a new empty array of type "int" with 10 elements.
</PRE></CODE>

=== Accessing Arrays ===

To achieve better performance, arrays of primitive types smaller than a certain size have their contents cached on the smalltalk side:
<CODE><PRE>
intArray contents at:1. "/ this will access the first element of the cached contents.
</PRE></CODE>

large arrays are not serialized immediately. large arrays will be serialized when <CODE>contents</CODE> is called the first time.

'''Attention:''' Java arrays are not immutable. changes to an array are not reflected in the cached contents. if an array has been updated, call <CODE>refresh</CODE> on the array to update the cache. arrays will not be updated automatically.

<CODE><PRE>
shortArray := java getJavaClass:'[S' new:10. "/ new empty "short" array with 10 elements

"/ copy the contents of the smalltalk collection to the newly instantiated short array
java getJavaClass:'java.lang.System' arraycopy:(#[ 1 2 3 ] asSignedWordArray) srcPos:0 dest:shortArray destPos:0 length:3.

shortArray at:0. "/ will reflect the changes made to the array

shortArray contents at:1. "/ will still return 0 because the cached contents have not been updated.

shortArray refresh. "/ update the cached contents

shortArray contents at:1. "/ will now correctly reflect the changes made to the array
</PRE></CODE>

== Callbacks from Java ==
Sometimes you may want to execute a piece of Smalltalk code during the execution of the Java code. For example, we may want to install a Smalltalk observer to be notified when a button on a Java GUI was pressed,
or some other callback from a Java framework.

The following code registers a Smalltalk block as a callback for a mouse press event of a button:
<CODE><PRE>
listener := MouseListener new.
listener implementMethod:'mousePressed' as:[ Transcript showCR:'Hello from Java' ].
</PRE></CODE>
The above creates the callback and the listener, which can now be registered on a button:
<CODE><PRE>
button addMouseListener:listener.
</PRE></CODE>
Now, with the press of the button in the Java GUI, the Smalltalk block will be executed and writes <CODE>"Hello from Java"</CODE> to the Smalltalk console.
Of course, any other (Smalltalk-)action code can be made to run via this mechanism.

But be aware, that the callback is possibly called later (when the elementary action, which installed the code, has already finished long ago). Also, as the Java code execution is not synchronized with any of your expecco action execution, the callback may also be called at any arbutrary time, even at times when no activity at all is executed on the expecco side. If you forget to cleanup, and the Java object is still alive, it may even be called after you have finished your test run (if you keep the java bridge handle around and alive, for example in an expecoo environment variable).

So the Smalltalk callback code should not depend on any particular elementary action to be currently running, but instead in most cases write some information into a shared data container, preferably an instance of "SharedQueue", which is thread safe. Then, some other action (an elementary action) would read-wait and read events from that shared queue.

make sure that your test correctly cleans up any such callbacks afterwards. As a last resort, use the "Shutdown Bridge Connection" menu item, which closes the bridge connection, and thereby - as a side effect - removes any leftover callbacks. It does close the connection, and any remaining java proxy object handles become invalid, though.

Another example, using an observer could look like:
<CODE><PRE>
observer := java Observer new.
observer implementMethod:'update'
as:[:sourceObservable :argument|
argument notNil ifTrue:[ Transcript showCR:('I was notifyed with: ',argument toString) ]
ifFalse:[ Transcript showCR:'I was notifyed and the argument was nil' ].
].
myObservable addObserver:observer.
</PRE></CODE>
When the observable calls <CODE>"notifyObservers"</CODE>, the Smalltalk block will be executed.

== Exceptions in Java ==
Exceptions on the Java side are signalled back to the Smalltalk side and raise a corresponding exception there. However, on the Java side, the call stack which lead to the exception has already been unwound at that time (Java exceptions are not proceedable). So a proceed in the Smalltalk-side exception handler only affects the Smalltalk caller, but may leave the Java side in an undefined state.

== Remote Dynamic Code Injection ==
Sometimes we might want to execute code without the overhead of many rpc-messages being sent over the bridge, especially if we want to do something time critical, or want to make execution time measurements.
For this, it is possible to load a class at runtime into the JavaVM. The code of the class will first be sent to the JavaVM, which will compile and load the generated byte code. Then, the class can be accessed via the bridge just like any other preloaded class.

The following example specifies the class code in a smalltalk string and inject the code into the JavaVM. Then an instance of that new class will be instantiated and finally a method of the object instance will be invoked:
<CODE><PRE>
classCode := '
package myPackage.test;

import java.awt.BorderLayout;
import java.awt.event.MouseAdapter;
import java.awt.event.MouseEvent;
import java.util.Calendar;

import javax.swing.JButton;
import javax.swing.JFrame;
import javax.swing.JLabel;;

public class MyInjectedClass {
public void createSampleApp(){
JFrame frame=new JFrame("Hello im injected");
frame.setLayout(new BorderLayout());
JButton button=new JButton("click me");
final JLabel label=new JLabel("Text");
button.addMouseListener(new MouseAdapter() {

@Override
public void mouseClicked(MouseEvent e) {
label.setText(Calendar.getInstance().getTime().toString());
}
});
frame.add(label,BorderLayout.NORTH);
frame.add(button,BorderLayout.SOUTH);
frame.setSize(300, 300);
frame.setVisible(true);
}
}
'.
classObject := java getJavaClass:'myPackage.test.MyInjectedClass' fromSource:classCode.
classObject new createSampleApp.
</PRE></CODE>
After the code has been injected, a new instance of <CODE>"MyInjectedClass"</CODE> is created and the <CODE>"createSampleApp"</CODE> method is called. Because the example implements a GUI, a Java window will open, containing a label and a button. Clicking the button displays the current time in the label.



=== Code Sources for Class injection ===
There are 3 possible types of class code sources which we can use to inject the code. In the examples before we directly used a simple <CODE>"String"</CODE> in the smalltalk code as a code source. We also can use a <CODE>"*.java"</CODE> file as source. Just read the content of the file into a string and use it as in the previous examples.

To inject a <CODE>"*.class"</CODE> file use the following code:
<pre>
java getJavaClass:'the.class.name' fromByteCode:classCode.
</pre>

== Examples ==

This example creates a JFrame with one button inside. Then a Mouselistener is created and registered on the button. When the button is pressed, the title of the window changes to <CODE>"onPressed"</CODE> and the Transcript shows the message <CODE>"onPressed"</CODE>. When the button is released, the title of the window is changed to <CODE>"onReleased"</CODE> and the Transcript shows <CODE>"onReleased"</CODE>. If the button lost the mouse focus, the bridge will exit (disconnect), and the Java side is terminated.
<CODE><PRE>
|java frame button listener|

"/getting a bridge
java := JAVA::JavaBridge newWithServer.

"/creating a new frame and button object
frame := java getJavaClass:'javax.swing.JFrame' new.
button := java JButton new:'Click'.

"/creating a new mouse listener and adding callback blocks
listener := java MouseListener new.

listener implementMethod:'mousePressed' as:[ Transcript showCR:'onPress'. frame setTitle:'onPressed' ].
listener implementMethod:'mouseReleased' as:[ Transcript showCR:'onReleased'. frame setTitle:'onReleased' ].
listener implementMethod:'mouseExited' as:[ Transcript showCR:'onExited'. java closeBridge. ].

"/register the mouse listener on the button and make the frame with button visible
button addMouseListener:listener.
frame add:button.
frame setSize:300 y:100.
frame setVisible: true.
</PRE></CODE>



==Differences between v1 and v2==
===General===
* A Java Bridge instance no longer requires multiple tcp ports to be open. This simplifies connection through ssh tunnels and firewalls.
* The identity of strings and primitve wrappers can be preserved. (see [[#boxedDo:aBlock | boxedDo]])
* Arrays of primitive types are serialized. (see [[#Arrays | Arrays]])

===Loading Applications===
* '''addJarByPath:''' and '''addToClassPath:''' are still supported but have been deprecated. use '''loadJar:''', '''loadJarByPath:''' and '''loadExtension:''' instead. The new methods no longer require the jar or library to be present on the remote machine.

[[Java Interface Library#Loading Applications (from the expecco side) | v1]] [[#Loading Applications (from the expecco side) | v2]]

===Java Class Access===
* Sending the fully qualified name with instances of "." replaced by "_" to the bridge handle is still supported, but not recommended.
* A new method '''getJavaClass:''' has been introduced (also available for v1 since expecco v2.9). This solves the side effects of "_" being a legal character in class names.

[[Java Interface Library#Java Package Import and Class Access | v1]] [[#Java Class Access | v2]]
===Callbacks from Java===
* A new method '''implementMethod:as:''' has been introduced to assign callback blocks to method names. The old way is still supported.

[[Java Interface Library#Callbacks from Java | v1]] [[#Callbacks from Java | v2]]

===Remote Dynamic Code Injection===
* Code injection was problematic in v1 and has now been re-implemented in v2.

[[#Remote Dynamic Code Injection | v2]]

== API ==
===JAVA::Java===
====class protocol====
=====newWithServer=====
* This will start a local JavaVM, running the JavaBridge, and establishes a connection on a random free port.
: A new connected instance of JAVA::Java class is returned.

=====newWithServerForJavaPath:aJavaPathFilename=====
* This is the same as newWithServer but the path to the java executable can be specified. The JavaVM version must be 1.6 or higher to run the JavaBridge.
:: '''aJavaPathFilename''' - must be a instance of Filename
Smalltalk: JAVA::Java newWithServerForJavaPath:('my\path\to\java.executable'asFilename).
JavaScript: JAVA::Java.newWithServerForJavaPath("my\path\to\java.executable".asFilename());

=====newConnectedTo:aHhostString port:aPortNumber withTimeout:aTimeoutSeconds=====
* This is used to connect to a running JavaBridge on the network. The JavaBridge must be started in server mode on the remote host. After connecting a new connected instance of JAVA::Java is returned.
:: '''aHostString''' - the hostname or IP of the remote machine as String
:: '''aPortNumber ''' - the port on which the remote machine is listening as Number
:: '''aTimeoutSeconds''' - a connect timeout in seconds as Number
Smalltalk: JAVA::Java newConnectedTo:'myHostName' port:4567 withTimeout:30.
JavaScript: JAVA::Java.newConnectedTo_port_withTimeout("myHostName",4567,30);

=====newWaitingForConnectOnHost:aListeningAddressString port:aListeningPortNumber withTimeout:aTimeoutSeconds=====
* This is used to wait for incomming connecions of a running JavaBridge on the network. The JavaBridge must be started in client mode on the remote host. After connecting a new connected instance of JAVA::Java is returned.
:: '''deprecated: aListeningAddressString''' - no longer used. Can be nil.
:: '''aListeningPortNumber ''' - the port on which to listen for incomming connections as Number
:: '''aTimeoutSeconds''' - a connect timeout in seconds as Number, If nil it will wait endless.

=====singletonInstance=====
* This will call newWithServer for the first time and then always returns the same connected JAVA::Java instance until the connection was closed, then a new connected instance is returned.

=====exitAllInstances=====
* This will close all instances of JAVA::Java.

====instance protocol====
=====loadJarByPath:aPath=====
* Adds a jar to the running JavaVM. If the jar depends on other jars or libraries you have to add them too.
:: '''aPath''' - the path to the jar file as String.

=====loadJar:aByteArray=====
* Adds a jar to the running JavaVM. If the jar depends on other jars or libraries you have to add them too.
:: '''aByteArrays''' - a ByteArray containing the JAR file.

=====loadExtension:aPath=====
* Adds a jar to the running JavaVM and caches it for subsequent usages. If the jar depends on other jars you have to add them too.
:: '''aPath''' - the path to the jar file as String.

=====boxedDo:aBlock=====
* Any autoboxed values in aBlock returned from the JavaVM are preserved as such. By default autoboxed values are automatically unboxed. This way, the identity of such objects is preserved.

=====isConnected=====
* Tests if a connection is still established.
:: '''return:''' - true if the connection is still established, else false.

=====isAlive=====
* Tests if a connection is still responding.
:: '''return:''' - true if the connection is still alive, else false. Does a message round trip.

=====closeBridge=====
* This will close the bridge connection. Depending on in which mode the JavaBridge was started, the JavaVM is also closed (-keepAlive startparameter not set).

=====exit=====
* Same as closeBridge.

== See Also==
The [[DOT NET Interface Library| DOTNET Interface Plugin & Library]], which implements a likewise interface for .NET applications/libraries.

<hr>
Back to [[Plugins]]

Java Interface Library v2

2016-06-01T08:53:40Z

Javogel:

== Introduction ==

This article discusses version 2 of the Java Bridge (which is as of expecco v2.9 still experimental).
The article for version 1 can be found [[Java Interface Library | here]].

The Java Interface library ("Java Bridge") is used to interact with Java objects inside an external Java Virtual Machine (JVM).

The access to Java objects, classes and programs is done via a framework called "''Java-Bridge''", which is similar in operation to the [[DOT NET Interface Library| dotNET bridge]]. This framework implements transparent forwarding of method (virtual function) calls to Java objects, which exist in a local or remote Java Virtual Machine (JVM). Also, return values, callBacks and exception information are passed back from the Java program to expecco. This is done by a proxy-object mechanism, which catches all function calls, wraps the arguments, sends a datagram to the other bridge side, awaits the reply and returns the result to the original caller. Thus, remote procedure calls are almost completely transparent to the Smalltalk/JavaScript code inside expecco. In your elementary code, you can write remote function calls as if they were to local objects.

Notice that this document describes the low level framework, which implements the bridge communication. A much easier to use high level interface (called "Groovy Blocks") exists and should normally be used, if you need access to a java application's internals during testing.
Please take a look at
[[Expecco_API#Groovy_Elementary_Blocks | "Groovy Block API"]]
and [[Testing Java Applications using Groovy blocks/en | "Testing Java Applications using Groovy blocks"]].

== Architecture ==

On the expecco side, the bridge consists of a number of Proxy objects,
which behave like regular Smalltalk objects as seen from elementary expecco code.
However, instead of performing an action when one of their methods (virtual functions) is called,
they send a message over a socket connection to the Java VM (actually: to a bridge software inside the
Java application) which decodes the message and sends it to the destination Java object.
The same is done in reverse direction with the return value.

+---------------------+ +----------+ +----------------+ +----------------+ +---------+
| | | | | | | | | Java |
| expecco |---->| Proxy |---->| Bridge |==>>==| Bridge |---->| Object |
| (elementary code) |<----| |<----| (expecco side) |==<<==| (Java side) |<----| |
+---------------------+ +----------+ +----------------+ +----------------+ +---------+

This setup allows for transparent communication with objects inside a local or remote Java VM. This may be either utility functions which happen to be convenient for the test application (for example: file parsing, syntax analysis, protocol implementaitons or access to specific hardware via driver libraries), or the tested application in the system under test itself.

Especially, it allows for the objects of the tested application to be looked into, manipulated and for functions of it or underlying frameworks to be called.

For expecco code, we tried to make this as transparent as possible, however there are a few exceptions, when function names need to be translated (for example, because the function naming syntax is different) or due to the fact that for some operations no corresponding name exists in Smalltalk (array access, for example).

Of course, multiple such connections can coexist and be served/handled in parallel. This enables an expecco test suite to communicate with both sides of a tested client-server Java application, for example.

Notice that a similar mechanism is used in expecco to communicate with DOTNET, Qt (C++) and C applications.

 

== Activating the new Java Bridge ==
To activate the new bridge in expecco navigate to <CODE>Extras -> Settings -> Plugins -> Java Bridge</CODE> and tick the '''Use new Bridge (experimental)''' checkbox.
[[Datei:ActivateNewJavaBridge.png]]

'''Attention:''' Ticking the checkbox will terminate all currently active Bridge connections due to incompatibilities between the new and the old version.

== Initializing / Releasing the Bridge ==

Before any communication can take place between expecco and any Java object, the Java side of the bridge has to be started, and a communication has to be established.
In expecco, all of the bridge classes are found in the <CODE>JAVA</CODE> namespace.

The main interface class is "<CODE>Java</CODE>", in the "<CODE>JAVA</CODE>" namespace:
<CODE><PRE>
java := JAVA::Java newWithServer.
</PRE></CODE>
or (in JavaScript):
<CODE><PRE>
java = JAVA::Java.newWithServer();
</PRE></CODE>

This starts the Java-side of the bridge (actually executes java as a background command) on the local machine, and establishes a connection to that JVM.

The bridge connection should be closed, if the bridge is no longer needed. Release the bridge with:
<CODE><PRE>
java.closeBridge();
</PRE></CODE>
which terminates the connection.

=== Start and Connect to a Remote Machine ===
The above started a Java VM and connected to it. Alternatively, you may want to connect to an already running Java program (typically, your system under test).
In order for your program to be reachable, it must allow for the bridge to connect to it via a special bridge-connection, which is a socket connection. For this, it must execute the server code found in the "JavaBridge.jar" file. To pass [[#Startup Parameters| parameters]] you will typically start it from a command line or a little shell/batch script.

Call (on the shell/cmd level):
$ java -jar <PATH_TO_JAVABRIDGE.JAR> <PARAMETERS>

The "JavaBridge.jar" file is found in the installation directory of expecco at:
\exept\expecco\packages\exept\bridgeFramework\javaBridge\javaBin\JavaBridge.jar

The Javabridge code allows for either side to initiate the connection - i.e. it can be run in server mode,
where it awaits an incoming connection, or in client mode, where it actively initiates a connection.
After connection establishment, there is no difference in the operation of the bridge, however depending on the setup of your network infrastructure, especially firewalls, either mechanism may be easier to be used.

Assuming that the bridge is already running on the remote machine as server (default),
use <CODE>newConnectedTo:port:withTimeout:</CODE> to connect to it from the expecco side:
java := JAVA::Java newConnectedTo:'myHost' port:4567 withTimeout:30.
This will initiate the connection setup from the expecco side.

Alternatively, if started in client mode use <CODE>newWaitingForConnectOnHost:port:withTimeout:</CODE>:
java := JAVA::Java newWaitingForConnectOnHost:'localhost' port:4567 withTimeout:30.
which will open a port on the expecco side, and wait until the Java side connects to it.
[[#JAVA::Java|For more details see API]]

====Startup Parameters====
You can use any parameter in any order.
If no parameter is used then the bridge listenes on port 14014 in server mode without keepAlive.
;<code>-help</code>
* Shows the help

;<code>-ip <aHostnameOrIP></code>
* In client mode this specifies the ip or hostname to connect to. In server mode this specifies the ip or hostname to bind to.

;<code>-port <aPortNumber> </code>
* In client mode this specifies the port to connect to. In server mode this specifies the listening port.

;<code>-asClient</code>
* The bridge will start in client mode. If not set the bridge is started in server mode.

;<code>-keepAlive</code>
* By setting this flag the bridge will not exit after the connection has closed and starts to connect or listen again. Otherwise, it will run for a single connection session only.

== Loading Applications (from the expecco side) ==

Normally, you would start your application with the required command line arguments and include the javabridge as jar there. However, in some situations, it may be required to dynamically load other jars into the connected Java VM.
By accessing a classloader, additional classes, or applications as contained in JAR files can be loaded from the expecco side.

This can be used to add a JAR file to the classloader:
<CODE><PRE>
java loadJarByPath:'pathToJarFile'. "/ assuming "java" is a handle as returned from the above connect
</PRE></CODE>

or, if the JAR file is loaded in memory:
<CODE><PRE>
java loadJar:jarByteArray. "/ where "jarByteArray" is a ByteArray containing the JAR file
</PRE></CODE>

If the JVM is on a remote machine, the path is resolved on the expecco side and the JAR will be transferred to the remote side.

Should transferring the JAR be too much overhead, an additional mechanism is provided:
<CODE><PRE>
java loadExtension:'pathToJarFile'.
</PRE></CODE>
this will cache the JAR file on the bridge side and eliminate the overhead of subsequent invocations.

== Java Class Access ==

This following code sample simply references (i.e. accesses) the class "JFrame" from the <CODE>"javax.swing"</CODE> package. The fully specified class name in Java would be <CODE>"javax.swing.JFrame"</CODE>:
<CODE><PRE>
java getJavaClass:'javax.swing.JFrame'
</PRE></CODE>

Or, if you want to load multiple classes:
<CODE><PRE>
java import:'javax.swing.JFrame' import:'javax.swing.JButton'
do:[:jFrame :jButton | "do something with JButton and JFrame" ].
</PRE></CODE>

v2 also supports dynamic compilation of java source code:
<CODE><PRE>
java getJavaClass:'className' fromSource:'classSource'. "/ where classSource is a String containing valid java source code
</PRE></CODE>

and loading precompiled java bytecode:
<CODE><PRE>
java getJavaClass:'className' fromByteCode:byteCode. "/ where byteCode is a ByteArray containing valid java bytecode
</PRE></CODE>

[[#Remote Dynamic Code Injection | for details see Remote Dynamic Code Injection]]

== Instantiating a Class ==

Object instances are created via the "new"-message, sent to a proxy of a Java class. You can get this proxy as described in the previous section. For example, if we want to create a new instance of a "JFrame" and a "JButton", write:
<CODE><PRE>
frame := java getJavaClass:'javax.swing.JFrame' new.
button := java getJavaClass:'javax.swing.JButton' new.
</PRE></CODE>
The first statement results in a proxy object for the "JFrame" instance. The second line results in a proxy for a new "JButton" object.

== Calling Instance Methods ==

A method call is done by a message send to a proxy object, where the message is the method name to call. For example, to call the <CODE>"setVisible(boolean isVisible)"</CODE> method on the above JFrame object, we send the following message to that proxy:
<CODE><PRE>
frame setVisible:true.
</PRE></CODE>

As method naming is different in Smalltalk and Java, a dynamic translation is applied when sending messages from Smalltalk code to a remote Java object. Smalltalk has arguments embedded inside parts of a so called "keyword" message, such as in "receiver foo:arg1 bar:arg2", where "foo:bar:" would be the message name, and "arg1", "arg2" be the arguments.

In Java, the message name is a single identifier, and arguments are written in an argument list after the message name: "receiver.fooBar(arg1, arg2)".

When message names are translated, only the very first part of the Smalltalk keyword message is taken ("foo" in the above example), and the remaining parts are simpl ignored. Thus, any of the Smalltalk messages "foo:bar:", "foo:xxxx:" and "foo:_:" (a single underscore as second part) all translate to the same Java message name "foo()".

Therefore, to call a method with more than one argument, like <CODE>"setSize(int width,int height)"</CODE> on a JFrame instance we can write:
<CODE><PRE>
frame setSize:300 _:200.
</PRE></CODE>
but just as well:
<CODE><PRE>
frame setSize:300 anyWord:200.
</PRE></CODE>
or any other selector with "setSize:" as its first component.
The selector translation mechanism simply takes the first part as the Java selector.

In practice, you should take a reasonably descriptive name, such as: "frame setSize:300 height:200" or only the Java name as first part, such as "frame setSize:300 _:200".

For a call of a method with 4 arguments, we could write:
<CODE><PRE>
frame setBounds:100 y:50 width:300 height:200.
</PRE></CODE>
or:
<CODE><PRE>
frame setBounds:100 _:50 _:300 _:200.
</PRE></CODE>

Also here the <CODE>"y: width: height:"</CODE> can be named as you want, but the first part must be "setBounds:".

=== Calling Static Methods ===

Calling a static method on an object is not different from calling non static methods. In most cases you will call a static method not on an object but directly on the class. This is done by using the class object as "receiver" of the message. For example, if we want to call the static method <CODE>"isDefaultLookAndFeelDecorated()"</CODE> of the JFrame class, write:
<CODE><PRE>
java getJavaClass:'javax.swing.JFrame' isDefaultLookAndFeelDecorated.
</PRE></CODE>

== Accessing Fields ==

As Smalltalk does not support access of an object's fields from the outside (it is fully encapsulated, and access from outside is ONLY allowed via getters/setters), an additional translation mechanism is provided for field access.

Accessing a field of a Java object or a class's static field uses the same syntax as method calls. To access a field, send a message where the message is the field name. To access the field of a class the field must be static.
For example, to get the value of the static field named <CODE>"EXIT_ON_CLOSE"</CODE> of the "JFrame" class, write
<CODE><PRE>
value := java getJavaClass:'javax.swing.JFrame' EXIT_ON_CLOSE.
</PRE></CODE>
The variable "value" now holds the integer value of the <CODE>"EXIT_ON_CLOSE"</CODE> constant.

Assuming that a "JFrame" object had a field named <CODE>"myField"</CODE>, to access this field, we'd have to write:
<CODE><PRE>
value := frame myField.
</PRE></CODE>
and "value" now holding whatever <CODE>"myField"</CODE> returns. This could be another object reference or any primitive value.

=== Setting Fields ===
To set a field, use a setter-like method call:
<CODE><PRE>
frame myField: newValue.
</PRE></CODE>

=== Name Conflicts ===

In very rare situations, a Java object may contain both a field and a method by the same name.
In this case, the Smalltalk code cannot depend on the dynamic translation mechanism (which actually looks for either a field or method name to match), but instead make it explicit, which operation is wanted:
Use:
<CODE><PRE>
frame getFieldByName:'myField'
</PRE></CODE>
to read a field, and:
<CODE><PRE>
frame setFieldByName:'myField' value:123.
</PRE></CODE>
to write the field.

If there are both fields and methods by the same name, and you use the non-explicit call,
the bridge will always assume that you want to call the getter/setter and perform a method call.
 

== Arrays ==

=== Passing Smalltalk Collections to Java ===

Smalltalk collections can now be directly passed to Java with a few limitations:
* The identity of the Smalltalk collections will not be preserved. passing the same collection to java multiple times will result in multiple instances of the same array on the java side. (to bypass this instantiate a new java array)
* Smalltalk collections need to be explicitly converted to the correct type (e.g. a <CODE>SignedIntegerArray</CODE> matches an <CODE>int</CODE>-Array)

=== Instantiating Arrays ===

The new bridge supports instantiation of arrays (whereas previously reflection had to be used to instantiate arrays from the smalltalk side).
There are two ways an array can be instantiated:

<CODE><PRE>
intArray := java getJavaClass:'[I' new:#[ 1 2 3 4 5 ] asSignedIntegerArray. "/ instantiates a new array of type "int" with the contents "1, 2, 3, 4, 5"
</PRE></CODE>

<CODE><PRE>
intArray := java getJavaClass:'[I' new:10. "/ instantiates a new empty array of type "int" with 10 elements.
</PRE></CODE>

=== Accessing Arrays ===

To achieve better performance, arrays of primitive types smaller than a certain size have their contents cached on the smalltalk side:
<CODE><PRE>
intArray contents at:1. "/ this will access the first element of the cached contents.
</PRE></CODE>

large arrays are not serialized immediately. large arrays will be serialized when <CODE>contents</CODE> is called the first time.

'''Attention:''' Java arrays are not immutable. changes to an array are not reflected in the cached contents. if an array has been updated, call <CODE>_refresh</CODE> on the array to update the cache. arrays will not be updated automatically.

<CODE><PRE>
shortArray := java getJavaClass:'[S' new:10. "/ new empty "short" array with 10 elements

"/ copy the contents of the smalltalk collection to the newly instantiated short array
java getJavaClass:'java.lang.System' arraycopy:(#[ 1 2 3 ] asSignedWordArray) srcPos:0 dest:shortArray destPos:0 length:3.

shortArray at:0. "/ will reflect the changes made to the array

shortArray contents at:1. "/ will still return 0 because the cached contents have not been updated.

shortArray _refresh. "/ update the cached contents

shortArray contents at:1. "/ will now correctly reflect the changes made to the array
</PRE></CODE>

== Callbacks from Java ==
Sometimes you may want to execute a piece of Smalltalk code during the execution of the Java code. For example, we may want to install a Smalltalk observer to be notified when a button on a Java GUI was pressed,
or some other callback from a Java framework.

The following code registers a Smalltalk block as a callback for a mouse press event of a button:
<CODE><PRE>
listener := MouseListener new.
listener implementMethod:'mousePressed' as:[ Transcript showCR:'Hello from Java' ].
</PRE></CODE>
The above creates the callback and the listener, which can now be registered on a button:
<CODE><PRE>
button addMouseListener:listener.
</PRE></CODE>
Now, with the press of the button in the Java GUI, the Smalltalk block will be executed and writes <CODE>"Hello from Java"</CODE> to the Smalltalk console.
Of course, any other (Smalltalk-)action code can be made to run via this mechanism.

But be aware, that the callback is possibly called later (when the elementary action, which installed the code, has already finished long ago). Also, as the Java code execution is not synchronized with any of your expecco action execution, the callback may also be called at any arbutrary time, even at times when no activity at all is executed on the expecco side. If you forget to cleanup, and the Java object is still alive, it may even be called after you have finished your test run (if you keep the java bridge handle around and alive, for example in an expecoo environment variable).

So the Smalltalk callback code should not depend on any particular elementary action to be currently running, but instead in most cases write some information into a shared data container, preferably an instance of "SharedQueue", which is thread safe. Then, some other action (an elementary action) would read-wait and read events from that shared queue.

make sure that your test correctly cleans up any such callbacks afterwards. As a last resort, use the "Shutdown Bridge Connection" menu item, which closes the bridge connection, and thereby - as a side effect - removes any leftover callbacks. It does close the connection, and any remaining java proxy object handles become invalid, though.

Another example, using an observer could look like:
<CODE><PRE>
observer := java Observer new.
observer implementMethod:'update'
as:[:sourceObservable :argument|
argument notNil ifTrue:[ Transcript showCR:('I was notifyed with: ',argument toString) ]
ifFalse:[ Transcript showCR:'I was notifyed and the argument was nil' ].
].
myObservable addObserver:observer.
</PRE></CODE>
When the observable calls <CODE>"notifyObservers"</CODE>, the Smalltalk block will be executed.

== Exceptions in Java ==
Exceptions on the Java side are signalled back to the Smalltalk side and raise a corresponding exception there. However, on the Java side, the call stack which lead to the exception has already been unwound at that time (Java exceptions are not proceedable). So a proceed in the Smalltalk-side exception handler only affects the Smalltalk caller, but may leave the Java side in an undefined state.

== Remote Dynamic Code Injection ==
Sometimes we might want to execute code without the overhead of many rpc-messages being sent over the bridge, especially if we want to do something time critical, or want to make execution time measurements.
For this, it is possible to load a class at runtime into the JavaVM. The code of the class will first be sent to the JavaVM, which will compile and load the generated byte code. Then, the class can be accessed via the bridge just like any other preloaded class.

The following example specifies the class code in a smalltalk string and inject the code into the JavaVM. Then an instance of that new class will be instantiated and finally a method of the object instance will be invoked:
<CODE><PRE>
classCode := '
package myPackage.test;

import java.awt.BorderLayout;
import java.awt.event.MouseAdapter;
import java.awt.event.MouseEvent;
import java.util.Calendar;

import javax.swing.JButton;
import javax.swing.JFrame;
import javax.swing.JLabel;;

public class MyInjectedClass {
public void createSampleApp(){
JFrame frame=new JFrame("Hello im injected");
frame.setLayout(new BorderLayout());
JButton button=new JButton("click me");
final JLabel label=new JLabel("Text");
button.addMouseListener(new MouseAdapter() {

@Override
public void mouseClicked(MouseEvent e) {
label.setText(Calendar.getInstance().getTime().toString());
}
});
frame.add(label,BorderLayout.NORTH);
frame.add(button,BorderLayout.SOUTH);
frame.setSize(300, 300);
frame.setVisible(true);
}
}
'.
classObject := java getJavaClass:'myPackage.test.MyInjectedClass' fromSource:classCode.
classObject new createSampleApp.
</PRE></CODE>
After the code has been injected, a new instance of <CODE>"MyInjectedClass"</CODE> is created and the <CODE>"createSampleApp"</CODE> method is called. Because the example implements a GUI, a Java window will open, containing a label and a button. Clicking the button displays the current time in the label.



=== Code Sources for Class injection ===
There are 3 possible types of class code sources which we can use to inject the code. In the examples before we directly used a simple <CODE>"String"</CODE> in the smalltalk code as a code source. We also can use a <CODE>"*.java"</CODE> file as source. Just read the content of the file into a string and use it as in the previous examples.

To inject a <CODE>"*.class"</CODE> file use the following code:
<pre>
java getJavaClass:'the.class.name' fromByteCode:classCode.
</pre>

== Examples ==

This example creates a JFrame with one button inside. Then a Mouselistener is created and registered on the button. When the button is pressed, the title of the window changes to <CODE>"onPressed"</CODE> and the Transcript shows the message <CODE>"onPressed"</CODE>. When the button is released, the title of the window is changed to <CODE>"onReleased"</CODE> and the Transcript shows <CODE>"onReleased"</CODE>. If the button lost the mouse focus, the bridge will exit (disconnect), and the Java side is terminated.
<CODE><PRE>
|java frame button listener|

"/getting a bridge
java := JAVA::JavaBridge newWithServer.

"/creating a new frame and button object
frame := java getJavaClass:'javax.swing.JFrame' new.
button := java JButton new:'Click'.

"/creating a new mouse listener and adding callback blocks
listener := java MouseListener new.

listener implementMethod:'mousePressed' as:[ Transcript showCR:'onPress'. frame setTitle:'onPressed' ].
listener implementMethod:'mouseReleased' as:[ Transcript showCR:'onReleased'. frame setTitle:'onReleased' ].
listener implementMethod:'mouseExited' as:[ Transcript showCR:'onExited'. java closeBridge. ].

"/register the mouse listener on the button and make the frame with button visible
button addMouseListener:listener.
frame add:button.
frame setSize:300 y:100.
frame setVisible: true.
</PRE></CODE>



==Differences between v1 and v2==
===General===
* A Java Bridge instance no longer requires multiple tcp ports to be open. This simplifies connection through ssh tunnels and firewalls.
* The identity of strings and primitve wrappers can be preserved. (see [[#boxedDo:aBlock | boxedDo]])
* Arrays of primitive types are serialized. (see [[#Arrays | Arrays]])

===Loading Applications===
* '''addJarByPath:''' and '''addToClassPath:''' are still supported but have been deprecated. use '''loadJar:''', '''loadJarByPath:''' and '''loadExtension:''' instead. The new methods no longer require the jar or library to be present on the remote machine.

[[Java Interface Library#Loading Applications (from the expecco side) | v1]] [[#Loading Applications (from the expecco side) | v2]]

===Java Class Access===
* Sending the fully qualified name with instances of "." replaced by "_" to the bridge handle is still supported, but not recommended.
* A new method '''getJavaClass:''' has been introduced (also available for v1 since expecco v2.9). This solves the side effects of "_" being a legal character in class names.

[[Java Interface Library#Java Package Import and Class Access | v1]] [[#Java Class Access | v2]]
===Callbacks from Java===
* A new method '''implementMethod:as:''' has been introduced to assign callback blocks to method names. The old way is still supported.

[[Java Interface Library#Callbacks from Java | v1]] [[#Callbacks from Java | v2]]

===Remote Dynamic Code Injection===
* Code injection was problematic in v1 and has now been re-implemented in v2.

[[#Remote Dynamic Code Injection | v2]]

== API ==
===JAVA::Java===
====class protocol====
=====newWithServer=====
* This will start a local JavaVM, running the JavaBridge, and establishes a connection on a random free port.
: A new connected instance of JAVA::Java class is returned.

=====newWithServerForJavaPath:aJavaPathFilename=====
* This is the same as newWithServer but the path to the java executable can be specified. The JavaVM version must be 1.6 or higher to run the JavaBridge.
:: '''aJavaPathFilename''' - must be a instance of Filename
Smalltalk: JAVA::Java newWithServerForJavaPath:('my\path\to\java.executable'asFilename).
JavaScript: JAVA::Java.newWithServerForJavaPath("my\path\to\java.executable".asFilename());

=====newConnectedTo:aHhostString port:aPortNumber withTimeout:aTimeoutSeconds=====
* This is used to connect to a running JavaBridge on the network. The JavaBridge must be started in server mode on the remote host. After connecting a new connected instance of JAVA::Java is returned.
:: '''aHostString''' - the hostname or IP of the remote machine as String
:: '''aPortNumber ''' - the port on which the remote machine is listening as Number
:: '''aTimeoutSeconds''' - a connect timeout in seconds as Number
Smalltalk: JAVA::Java newConnectedTo:'myHostName' port:4567 withTimeout:30.
JavaScript: JAVA::Java.newConnectedTo_port_withTimeout("myHostName",4567,30);

=====newWaitingForConnectOnHost:aListeningAddressString port:aListeningPortNumber withTimeout:aTimeoutSeconds=====
* This is used to wait for incomming connecions of a running JavaBridge on the network. The JavaBridge must be started in client mode on the remote host. After connecting a new connected instance of JAVA::Java is returned.
:: '''deprecated: aListeningAddressString''' - no longer used. Can be nil.
:: '''aListeningPortNumber ''' - the port on which to listen for incomming connections as Number
:: '''aTimeoutSeconds''' - a connect timeout in seconds as Number, If nil it will wait endless.

=====singletonInstance=====
* This will call newWithServer for the first time and then always returns the same connected JAVA::Java instance until the connection was closed, then a new connected instance is returned.

=====exitAllInstances=====
* This will close all instances of JAVA::Java.

====instance protocol====
=====loadJarByPath:aPath=====
* Adds a jar to the running JavaVM. If the jar depends on other jars or libraries you have to add them too.
:: '''aPath''' - the path to the jar file as String.

=====loadJar:aByteArray=====
* Adds a jar to the running JavaVM. If the jar depends on other jars or libraries you have to add them too.
:: '''aByteArrays''' - a ByteArray containing the JAR file.

=====loadExtension:aPath=====
* Adds a jar to the running JavaVM and caches it for subsequent usages. If the jar depends on other jars you have to add them too.
:: '''aPath''' - the path to the jar file as String.

=====boxedDo:aBlock=====
* Any autoboxed values in aBlock returned from the JavaVM are preserved as such. By default autoboxed values are automatically unboxed. This way, the identity of such objects is preserved.

=====isConnected=====
* Tests if a connection is still established.
:: '''return:''' - true if the connection is still established, else false.

=====isAlive=====
* Tests if a connection is still responding.
:: '''return:''' - true if the connection is still alive, else false. Does a message round trip.

=====closeBridge=====
* This will close the bridge connection. Depending on in which mode the JavaBridge was started, the JavaVM is also closed (-keepAlive startparameter not set).

=====exit=====
* Same as closeBridge.

== See Also==
The [[DOT NET Interface Library| DOTNET Interface Plugin & Library]], which implements a likewise interface for .NET applications/libraries.

<hr>
Back to [[Plugins]]

Java Interface Library v2

2016-06-01T07:41:21Z

Javogel: #Activating the new Java Bridge

== Introduction ==

This article discusses version 2 of the Java Bridge (which is as of expecco v2.9 still experimental).
The article for version 1 can be found [[Java Interface Library | here]].

The Java Interface library ("Java Bridge") is used to interact with Java objects inside an external Java Virtual Machine (JVM).

The access to Java objects, classes and programs is done via a framework called "''Java-Bridge''", which is similar in operation to the [[DOT NET Interface Library| dotNET bridge]]. This framework implements transparent forwarding of method (virtual function) calls to Java objects, which exist in a local or remote Java Virtual Machine (JVM). Also, return values, callBacks and exception information are passed back from the Java program to expecco. This is done by a proxy-object mechanism, which catches all function calls, wraps the arguments, sends a datagram to the other bridge side, awaits the reply and returns the result to the original caller. Thus, remote procedure calls are almost completely transparent to the Smalltalk/JavaScript code inside expecco. In your elementary code, you can write remote function calls as if they were to local objects.

Notice that this document describes the low level framework, which implements the bridge communication. A much easier to use high level interface (called "Groovy Blocks") exists and should normally be used, if you need access to a java application's internals during testing.
Please take a look at
[[Expecco_API#Groovy_Elementary_Blocks | "Groovy Block API"]]
and [[Testing Java Applications using Groovy blocks/en | "Testing Java Applications using Groovy blocks"]].

== Architecture ==

On the expecco side, the bridge consists of a number of Proxy objects,
which behave like regular Smalltalk objects as seen from elementary expecco code.
However, instead of performing an action when one of their methods (virtual functions) is called,
they send a message over a socket connection to the Java VM (actually: to a bridge software inside the
Java application) which decodes the message and sends it to the destination Java object.
The same is done in reverse direction with the return value.

+---------------------+ +----------+ +----------------+ +----------------+ +---------+
| | | | | | | | | Java |
| expecco |---->| Proxy |---->| Bridge |==>>==| Bridge |---->| Object |
| (elementary code) |<----| |<----| (expecco side) |==<<==| (Java side) |<----| |
+---------------------+ +----------+ +----------------+ +----------------+ +---------+

This setup allows for transparent communication with objects inside a local or remote Java VM. This may be either utility functions which happen to be convenient for the test application (for example: file parsing, syntax analysis, protocol implementaitons or access to specific hardware via driver libraries), or the tested application in the system under test itself.

Especially, it allows for the objects of the tested application to be looked into, manipulated and for functions of it or underlying frameworks to be called.

For expecco code, we tried to make this as transparent as possible, however there are a few exceptions, when function names need to be translated (for example, because the function naming syntax is different) or due to the fact that for some operations no corresponding name exists in Smalltalk (array access, for example).

Of course, multiple such connections can coexist and be served/handled in parallel. This enables an expecco test suite to communicate with both sides of a tested client-server Java application, for example.

Notice that a similar mechanism is used in expecco to communicate with DOTNET, Qt (C++) and C applications.

 

== Activating the new Java Bridge ==
To activate the new bridge in expecco navigate to <CODE>Extras -> Settings -> Plugins -> Java Bridge</CODE> and tick the '''Use new Bridge (experimental)''' checkbox.
[[Datei:ActivateNewJavaBridge.png]]

'''Attention:''' Ticking the checkbox will terminate all currently active Bridge connections due to incompatibilities between the new and the old version.

== Initializing / Releasing the Bridge ==

Before any communication can take place between expecco and any Java object, the Java side of the bridge has to be started, and a communication has to be established.
In expecco, all of the bridge classes are found in the <CODE>JAVA</CODE> namespace.

The main interface class is "<CODE>Java</CODE>", in the "<CODE>JAVA</CODE>" namespace:
<CODE><PRE>
java := JAVA::Java newWithServer.
</PRE></CODE>
or (in JavaScript):
<CODE><PRE>
java = JAVA::Java.newWithServer();
</PRE></CODE>

This starts the Java-side of the bridge (actually executes java as a background command) on the local machine, and establishes a connection to that JVM.

The bridge connection should be closed, if the bridge is no longer needed. Release the bridge with:
<CODE><PRE>
java.closeBridge();
</PRE></CODE>
which terminates the connection.

=== Start and Connect to a Remote Machine ===
The above started a Java VM and connected to it. Alternatively, you may want to connect to an already running Java program (typically, your system under test).
In order for your program to be reachable, it must allow for the bridge to connect to it via a special bridge-connection, which is a socket connection. For this, it must execute the server code found in the "JavaBridge.jar" file. To pass [[#Startup Parameters| parameters]] you will typically start it from a command line or a little shell/batch script.

Call (on the shell/cmd level):
$ java -jar <PATH_TO_JAVABRIDGE.JAR> <PARAMETERS>

The "JavaBridge.jar" file is found in the installation directory of expecco at:
\exept\expecco\packages\exept\bridgeFramework\javaBridge\javaBin\JavaBridge.jar

The Javabridge code allows for either side to initiate the connection - i.e. it can be run in server mode,
where it awaits an incoming connection, or in client mode, where it actively initiates a connection.
After connection establishment, there is no difference in the operation of the bridge, however depending on the setup of your network infrastructure, especially firewalls, either mechanism may be easier to be used.

Assuming that the bridge is already running on the remote machine as server (default),
use <CODE>newConnectedTo:port:withTimeout:</CODE> to connect to it from the expecco side:
java := JAVA::Java newConnectedTo:'myHost' port:4567 withTimeout:30.
This will initiate the connection setup from the expecco side.

Alternatively, if started in client mode use <CODE>newWaitingForConnectOnHost:port:withTimeout:</CODE>:
java := JAVA::Java newWaitingForConnectOnHost:'localhost' port:4567 withTimeout:30.
which will open a port on the expecco side, and wait until the Java side connects to it.
[[#JAVA::Java|For more details see API]]

====Startup Parameters====
You can use any parameter in any order.
If no parameter is used then the bridge listenes on port 14014 in server mode without keepAlive.
;<code>-help</code>
* Shows the help

;<code>-ip <aHostnameOrIP></code>
* In client mode this specifies the ip or hostname to connect to. In server mode this specifies the ip or hostname to bind to.

;<code>-port <aPortNumber> </code>
* In client mode this specifies the port to connect to. In server mode this specifies the listening port.

;<code>-asClient</code>
* The bridge will start in client mode. If not set the bridge is started in server mode.

;<code>-keepAlive</code>
* By setting this flag the bridge will not exit after the connection has closed and starts to connect or listen again. Otherwise, it will run for a single connection session only.

== Loading Applications (from the expecco side) ==

Normally, you would start your application with the required command line arguments and include the javabridge as jar there. However, in some situations, it may be required to dynamically load other jars into the connected Java VM.
By accessing a classloader, additional classes, or applications as contained in JAR files can be loaded from the expecco side.

This can be used to add a JAR file to the classloader:
<CODE><PRE>
java loadJarByPath:'pathToJarFile'. "/ assuming "java" is a handle as returned from the above connect
</PRE></CODE>

or, if the JAR file is loaded in memory:
<CODE><PRE>
java loadJar:jarByteArray. "/ where "jarByteArray" is a ByteArray containing the JAR file
</PRE></CODE>

If the JVM is on a remote machine, the path is resolved on the expecco side and the JAR will be transferred to the remote side.

Should transferring the JAR be too much overhead, an additional mechanism is provided:
<CODE><PRE>
java loadExtension:'pathToJarFile'.
</PRE></CODE>
this will cache the JAR file on the bridge side and eliminate the overhead of subsequent invocations.

== Java Class Access ==

This following code sample simply references (i.e. accesses) the class "JFrame" from the <CODE>"javax.swing"</CODE> package. The fully specified class name in Java would be <CODE>"javax.swing.JFrame"</CODE>:
<CODE><PRE>
java getJavaClass:'javax.swing.JFrame'
</PRE></CODE>

Or, if you want to load multiple classes:
<CODE><PRE>
java import:'javax.swing.JFrame' import:'javax.swing.JButton'
do:[:jFrame :jButton | "do something with JButton and JFrame" ].
</PRE></CODE>

v2 also supports dynamic compilation of java source code:
<CODE><PRE>
java getJavaClass:'className' fromSource:'classSource'. "/ where classSource is a String containing valid java source code
</PRE></CODE>

and loading precompiled java bytecode:
<CODE><PRE>
java getJavaClass:'className' fromByteCode:byteCode. "/ where byteCode is a ByteArray containing valid java bytecode
</PRE></CODE>

[[#Remote Dynamic Code Injection | for details see Remote Dynamic Code Injection]]

== Instantiating a Class ==

Object instances are created via the "new"-message, sent to a proxy of a Java class. You can get this proxy as described in the previous section. For example, if we want to create a new instance of a "JFrame" and a "JButton", write:
<CODE><PRE>
frame := java getJavaClass:'javax.swing.JFrame' new.
button := java getJavaClass:'javax.swing.JButton' new.
</PRE></CODE>
The first statement results in a proxy object for the "JFrame" instance. The second line results in a proxy for a new "JButton" object.

== Calling Instance Methods ==

A method call is done by a message send to a proxy object, where the message is the method name to call. For example, to call the <CODE>"setVisible(boolean isVisible)"</CODE> method on the above JFrame object, we send the following message to that proxy:
<CODE><PRE>
frame setVisible:true.
</PRE></CODE>

As method naming is different in Smalltalk and Java, a dynamic translation is applied when sending messages from Smalltalk code to a remote Java object. Smalltalk has arguments embedded inside parts of a so called "keyword" message, such as in "receiver foo:arg1 bar:arg2", where "foo:bar:" would be the message name, and "arg1", "arg2" be the arguments.

In Java, the message name is a single identifier, and arguments are written in an argument list after the message name: "receiver.fooBar(arg1, arg2)".

When message names are translated, only the very first part of the Smalltalk keyword message is taken ("foo" in the above example), and the remaining parts are simpl ignored. Thus, any of the Smalltalk messages "foo:bar:", "foo:xxxx:" and "foo:_:" (a single underscore as second part) all translate to the same Java message name "foo()".

Therefore, to call a method with more than one argument, like <CODE>"setSize(int width,int height)"</CODE> on a JFrame instance we can write:
<CODE><PRE>
frame setSize:300 _:200.
</PRE></CODE>
but just as well:
<CODE><PRE>
frame setSize:300 anyWord:200.
</PRE></CODE>
or any other selector with "setSize:" as its first component.
The selector translation mechanism simply takes the first part as the Java selector.

In practice, you should take a reasonably descriptive name, such as: "frame setSize:300 height:200" or only the Java name as first part, such as "frame setSize:300 _:200".

For a call of a method with 4 arguments, we could write:
<CODE><PRE>
frame setBounds:100 y:50 width:300 height:200.
</PRE></CODE>
or:
<CODE><PRE>
frame setBounds:100 _:50 _:300 _:200.
</PRE></CODE>

Also here the <CODE>"y: width: height:"</CODE> can be named as you want, but the first part must be "setBounds:".

=== Calling Static Methods ===

Calling a static method on an object is not different from calling non static methods. In most cases you will call a static method not on an object but directly on the class. This is done by using the class object as "receiver" of the message. For example, if we want to call the static method <CODE>"isDefaultLookAndFeelDecorated()"</CODE> of the JFrame class, write:
<CODE><PRE>
java getJavaClass:'javax.swing.JFrame' isDefaultLookAndFeelDecorated.
</PRE></CODE>

== Accessing Fields ==

As Smalltalk does not support access of an object's fields from the outside (it is fully encapsulated, and access from outside is ONLY allowed via getters/setters), an additional translation mechanism is provided for field access.

Accessing a field of a Java object or a class's static field uses the same syntax as method calls. To access a field, send a message where the message is the field name. To access the field of a class the field must be static.
For example, to get the value of the static field named <CODE>"EXIT_ON_CLOSE"</CODE> of the "JFrame" class, write
<CODE><PRE>
value := java getJavaClass:'javax.swing.JFrame' EXIT_ON_CLOSE.
</PRE></CODE>
The variable "value" now holds the integer value of the <CODE>"EXIT_ON_CLOSE"</CODE> constant.

Assuming that a "JFrame" object had a field named <CODE>"myField"</CODE>, to access this field, we'd have to write:
<CODE><PRE>
value := frame myField.
</PRE></CODE>
and "value" now holding whatever <CODE>"myField"</CODE> returns. This could be another object reference or any primitive value.

=== Setting Fields ===
To set a field, use a setter-like method call:
<CODE><PRE>
frame myField: newValue.
</PRE></CODE>

=== Name Conflicts ===

In very rare situations, a Java object may contain both a field and a method by the same name.
In this case, the Smalltalk code cannot depend on the dynamic translation mechanism (which actually looks for either a field or method name to match), but instead make it explicit, which operation is wanted:
Use:
<CODE><PRE>
frame getFieldByName:'myField'
</PRE></CODE>
to read a field, and:
<CODE><PRE>
frame setFieldByName:'myField' value:123.
</PRE></CODE>
to write the field.

If there are both fields and methods by the same name, and you use the non-explicit call,
the bridge will always assume that you want to call the getter/setter and perform a method call.
 

== Callbacks from Java ==
Sometimes you may want to execute a piece of Smalltalk code during the execution of the Java code. For example, we may want to install a Smalltalk observer to be notified when a button on a Java GUI was pressed,
or some other callback from a Java framework.

The following code registers a Smalltalk block as a callback for a mouse press event of a button:
<CODE><PRE>
listener := MouseListener new.
listener implementMethod:'mousePressed' as:[ Transcript showCR:'Hello from Java' ].
</PRE></CODE>
The above creates the callback and the listener, which can now be registered on a button:
<CODE><PRE>
button addMouseListener:listener.
</PRE></CODE>
Now, with the press of the button in the Java GUI, the Smalltalk block will be executed and writes <CODE>"Hello from Java"</CODE> to the Smalltalk console.
Of course, any other (Smalltalk-)action code can be made to run via this mechanism.

But be aware, that the callback is possibly called later (when the elementary action, which installed the code, has already finished long ago). Also, as the Java code execution is not synchronized with any of your expecco action execution, the callback may also be called at any arbutrary time, even at times when no activity at all is executed on the expecco side. If you forget to cleanup, and the Java object is still alive, it may even be called after you have finished your test run (if you keep the java bridge handle around and alive, for example in an expecoo environment variable).

So the Smalltalk callback code should not depend on any particular elementary action to be currently running, but instead in most cases write some information into a shared data container, preferably an instance of "SharedQueue", which is thread safe. Then, some other action (an elementary action) would read-wait and read events from that shared queue.

make sure that your test correctly cleans up any such callbacks afterwards. As a last resort, use the "Shutdown Bridge Connection" menu item, which closes the bridge connection, and thereby - as a side effect - removes any leftover callbacks. It does close the connection, and any remaining java proxy object handles become invalid, though.

Another example, using an observer could look like:
<CODE><PRE>
observer := java Observer new.
observer implementMethod:'update'
as:[:sourceObservable :argument|
argument notNil ifTrue:[ Transcript showCR:('I was notifyed with: ',argument toString) ]
ifFalse:[ Transcript showCR:'I was notifyed and the argument was nil' ].
].
myObservable addObserver:observer.
</PRE></CODE>
When the observable calls <CODE>"notifyObservers"</CODE>, the Smalltalk block will be executed.

== Exceptions in Java ==
Exceptions on the Java side are signalled back to the Smalltalk side and raise a corresponding exception there. However, on the Java side, the call stack which lead to the exception has already been unwound at that time (Java exceptions are not proceedable). So a proceed in the Smalltalk-side exception handler only affects the Smalltalk caller, but may leave the Java side in an undefined state.

== Remote Dynamic Code Injection ==
Sometimes we might want to execute code without the overhead of many rpc-messages being sent over the bridge, especially if we want to do something time critical, or want to make execution time measurements.
For this, it is possible to load a class at runtime into the JavaVM. The code of the class will first be sent to the JavaVM, which will compile and load the generated byte code. Then, the class can be accessed via the bridge just like any other preloaded class.

The following example specifies the class code in a smalltalk string and inject the code into the JavaVM. Then an instance of that new class will be instantiated and finally a method of the object instance will be invoked:
<CODE><PRE>
classCode := '
package myPackage.test;

import java.awt.BorderLayout;
import java.awt.event.MouseAdapter;
import java.awt.event.MouseEvent;
import java.util.Calendar;

import javax.swing.JButton;
import javax.swing.JFrame;
import javax.swing.JLabel;;

public class MyInjectedClass {
public void createSampleApp(){
JFrame frame=new JFrame("Hello im injected");
frame.setLayout(new BorderLayout());
JButton button=new JButton("click me");
final JLabel label=new JLabel("Text");
button.addMouseListener(new MouseAdapter() {

@Override
public void mouseClicked(MouseEvent e) {
label.setText(Calendar.getInstance().getTime().toString());
}
});
frame.add(label,BorderLayout.NORTH);
frame.add(button,BorderLayout.SOUTH);
frame.setSize(300, 300);
frame.setVisible(true);
}
}
'.
classObject := java getJavaClass:'myPackage.test.MyInjectedClass' fromSource:classCode.
classObject new createSampleApp.
</PRE></CODE>
After the code has been injected, a new instance of <CODE>"MyInjectedClass"</CODE> is created and the <CODE>"createSampleApp"</CODE> method is called. Because the example implements a GUI, a Java window will open, containing a label and a button. Clicking the button displays the current time in the label.



=== Code Sources for Class injection ===
There are 3 possible types of class code sources which we can use to inject the code. In the examples before we directly used a simple <CODE>"String"</CODE> in the smalltalk code as a code source. We also can use a <CODE>"*.java"</CODE> file as source. Just read the content of the file into a string and use it as in the previous examples.

To inject a <CODE>"*.class"</CODE> file use the following code:
<pre>
java getJavaClass:'the.class.name' fromByteCode:classCode.
</pre>

== Examples ==

This example creates a JFrame with one button inside. Then a Mouselistener is created and registered on the button. When the button is pressed, the title of the window changes to <CODE>"onPressed"</CODE> and the Transcript shows the message <CODE>"onPressed"</CODE>. When the button is released, the title of the window is changed to <CODE>"onReleased"</CODE> and the Transcript shows <CODE>"onReleased"</CODE>. If the button lost the mouse focus, the bridge will exit (disconnect), and the Java side is terminated.
<CODE><PRE>
|java frame button listener|

"/getting a bridge
java := JAVA::JavaBridge newWithServer.

"/creating a new frame and button object
frame := java getJavaClass:'javax.swing.JFrame' new.
button := java JButton new:'Click'.

"/creating a new mouse listener and adding callback blocks
listener := java MouseListener new.

listener implementMethod:'mousePressed' as:[ Transcript showCR:'onPress'. frame setTitle:'onPressed' ].
listener implementMethod:'mouseReleased' as:[ Transcript showCR:'onReleased'. frame setTitle:'onReleased' ].
listener implementMethod:'mouseExited' as:[ Transcript showCR:'onExited'. java closeBridge. ].

"/register the mouse listener on the button and make the frame with button visible
button addMouseListener:listener.
frame add:button.
frame setSize:300 y:100.
frame setVisible: true.
</PRE></CODE>



==Differences between v1 and v2==
===General===
* A Java Bridge instance no longer requires multiple tcp ports to be open. This simplifies connection through ssh tunnels and firewalls.
* The identity of strings and primitve wrappers can be preserved. (see [[#boxedDo:aBlock | boxedDo]])
* Arrays of primitive types are serialized.

===Loading Applications===
* '''addJarByPath:''' and '''addToClassPath:''' are still supported but have been deprecated. use '''loadJar:''', '''loadJarByPath:''' and '''loadExtension:''' instead. The new methods no longer require the jar or library to be present on the remote machine.

[[Java Interface Library#Loading Applications (from the expecco side) | v1]] [[#Loading Applications (from the expecco side) | v2]]

===Java Class Access===
* Sending the fully qualified name with instances of "." replaced by "_" to the bridge handle is still supported, but not recommended.
* A new method '''getJavaClass:''' has been introduced (also available for v1 since expecco v2.9). This solves the side effects of "_" being a legal character in class names.

[[Java Interface Library#Java Package Import and Class Access | v1]] [[#Java Class Access | v2]]
===Callbacks from Java===
* A new method '''implementMethod:as:''' has been introduced to assign callback blocks to method names. The old way is still supported.

[[Java Interface Library#Callbacks from Java | v1]] [[#Callbacks from Java | v2]]

===Remote Dynamic Code Injection===
* Code injection was problematic in v1 and has now been re-implemented in v2.

[[#Remote Dynamic Code Injection | v2]]

== API ==
===JAVA::Java===
====class protocol====
=====newWithServer=====
* This will start a local JavaVM, running the JavaBridge, and establishes a connection on a random free port.
: A new connected instance of JAVA::Java class is returned.

=====newWithServerForJavaPath:aJavaPathFilename=====
* This is the same as newWithServer but the path to the java executable can be specified. The JavaVM version must be 1.6 or higher to run the JavaBridge.
:: '''aJavaPathFilename''' - must be a instance of Filename
Smalltalk: JAVA::Java newWithServerForJavaPath:('my\path\to\java.executable'asFilename).
JavaScript: JAVA::Java.newWithServerForJavaPath("my\path\to\java.executable".asFilename());

=====newConnectedTo:aHhostString port:aPortNumber withTimeout:aTimeoutSeconds=====
* This is used to connect to a running JavaBridge on the network. The JavaBridge must be started in server mode on the remote host. After connecting a new connected instance of JAVA::Java is returned.
:: '''aHostString''' - the hostname or IP of the remote machine as String
:: '''aPortNumber ''' - the port on which the remote machine is listening as Number
:: '''aTimeoutSeconds''' - a connect timeout in seconds as Number
Smalltalk: JAVA::Java newConnectedTo:'myHostName' port:4567 withTimeout:30.
JavaScript: JAVA::Java.newConnectedTo_port_withTimeout("myHostName",4567,30);

=====newWaitingForConnectOnHost:aListeningAddressString port:aListeningPortNumber withTimeout:aTimeoutSeconds=====
* This is used to wait for incomming connecions of a running JavaBridge on the network. The JavaBridge must be started in client mode on the remote host. After connecting a new connected instance of JAVA::Java is returned.
:: '''deprecated: aListeningAddressString''' - no longer used. Can be nil.
:: '''aListeningPortNumber ''' - the port on which to listen for incomming connections as Number
:: '''aTimeoutSeconds''' - a connect timeout in seconds as Number, If nil it will wait endless.

=====singletonInstance=====
* This will call newWithServer for the first time and then always returns the same connected JAVA::Java instance until the connection was closed, then a new connected instance is returned.

=====exitAllInstances=====
* This will close all instances of JAVA::Java.

====instance protocol====
=====loadJarByPath:aPath=====
* Adds a jar to the running JavaVM. If the jar depends on other jars or libraries you have to add them too.
:: '''aPath''' - the path to the jar file as String.

=====loadJar:aByteArray=====
* Adds a jar to the running JavaVM. If the jar depends on other jars or libraries you have to add them too.
:: '''aByteArrays''' - a ByteArray containing the JAR file.

=====loadExtension:aPath=====
* Adds a jar to the running JavaVM and caches it for subsequent usages. If the jar depends on other jars you have to add them too.
:: '''aPath''' - the path to the jar file as String.

=====boxedDo:aBlock=====
* Any autoboxed values in aBlock returned from the JavaVM are preserved as such. By default autoboxed values are automatically unboxed. This way, the identity of such objects is preserved.

=====isConnected=====
* Tests if a connection is still established.
:: '''return:''' - true if the connection is still established, else false.

=====isAlive=====
* Tests if a connection is still responding.
:: '''return:''' - true if the connection is still alive, else false. Does a message round trip.

=====closeBridge=====
* This will close the bridge connection. Depending on in which mode the JavaBridge was started, the JavaVM is also closed (-keepAlive startparameter not set).

=====exit=====
* Same as closeBridge.

== See Also==
The [[DOT NET Interface Library| DOTNET Interface Plugin & Library]], which implements a likewise interface for .NET applications/libraries.

<hr>
Back to [[Plugins]]

Java Interface Library v2

2016-05-31T16:29:47Z

Javogel: /* Differences between v1 and v2 */

== Introduction ==

This article discusses version 2 of the Java Bridge (which is as of expecco v2.9 still experimental).
The article for version 1 can be found [[Java Interface Library | here]].

The Java Interface library ("Java Bridge") is used to interact with Java objects inside an external Java Virtual Machine (JVM).

The access to Java objects, classes and programs is done via a framework called "''Java-Bridge''", which is similar in operation to the [[DOT NET Interface Library| dotNET bridge]]. This framework implements transparent forwarding of method (virtual function) calls to Java objects, which exist in a local or remote Java Virtual Machine (JVM). Also, return values, callBacks and exception information are passed back from the Java program to expecco. This is done by a proxy-object mechanism, which catches all function calls, wraps the arguments, sends a datagram to the other bridge side, awaits the reply and returns the result to the original caller. Thus, remote procedure calls are almost completely transparent to the Smalltalk/JavaScript code inside expecco. In your elementary code, you can write remote function calls as if they were to local objects.

Notice that this document describes the low level framework, which implements the bridge communication. A much easier to use high level interface (called "Groovy Blocks") exists and should normally be used, if you need access to a java application's internals during testing.
Please take a look at
[[Expecco_API#Groovy_Elementary_Blocks | "Groovy Block API"]]
and [[Testing Java Applications using Groovy blocks/en | "Testing Java Applications using Groovy blocks"]].

== Architecture ==

On the expecco side, the bridge consists of a number of Proxy objects,
which behave like regular Smalltalk objects as seen from elementary expecco code.
However, instead of performing an action when one of their methods (virtual functions) is called,
they send a message over a socket connection to the Java VM (actually: to a bridge software inside the
Java application) which decodes the message and sends it to the destination Java object.
The same is done in reverse direction with the return value.

+---------------------+ +----------+ +----------------+ +----------------+ +---------+
| | | | | | | | | Java |
| expecco |---->| Proxy |---->| Bridge |==>>==| Bridge |---->| Object |
| (elementary code) |<----| |<----| (expecco side) |==<<==| (Java side) |<----| |
+---------------------+ +----------+ +----------------+ +----------------+ +---------+

This setup allows for transparent communication with objects inside a local or remote Java VM. This may be either utility functions which happen to be convenient for the test application (for example: file parsing, syntax analysis, protocol implementaitons or access to specific hardware via driver libraries), or the tested application in the system under test itself.

Especially, it allows for the objects of the tested application to be looked into, manipulated and for functions of it or underlying frameworks to be called.

For expecco code, we tried to make this as transparent as possible, however there are a few exceptions, when function names need to be translated (for example, because the function naming syntax is different) or due to the fact that for some operations no corresponding name exists in Smalltalk (array access, for example).

Of course, multiple such connections can coexist and be served/handled in parallel. This enables an expecco test suite to communicate with both sides of a tested client-server Java application, for example.

Notice that a similar mechanism is used in expecco to communicate with DOTNET, Qt (C++) and C applications.

 

== Initializing / Releasing the Bridge ==

Before any communication can take place between expecco and any Java object, the Java side of the bridge has to be started, and a communication has to be established.
In expecco, all of the bridge classes are found in the <CODE>JAVA</CODE> namespace.

The main interface class is "<CODE>Java</CODE>", in the "<CODE>JAVA</CODE>" namespace:
<CODE><PRE>
java := JAVA::Java newWithServer.
</PRE></CODE>
or (in JavaScript):
<CODE><PRE>
java = JAVA::Java.newWithServer();
</PRE></CODE>

This starts the Java-side of the bridge (actually executes java as a background command) on the local machine, and establishes a connection to that JVM.

The bridge connection should be closed, if the bridge is no longer needed. Release the bridge with:
<CODE><PRE>
java.closeBridge();
</PRE></CODE>
which terminates the connection.

=== Start and Connect to a Remote Machine ===
The above started a Java VM and connected to it. Alternatively, you may want to connect to an already running Java program (typically, your system under test).
In order for your program to be reachable, it must allow for the bridge to connect to it via a special bridge-connection, which is a socket connection. For this, it must execute the server code found in the "JavaBridge.jar" file. To pass [[#Startup Parameters| parameters]] you will typically start it from a command line or a little shell/batch script.

Call (on the shell/cmd level):
$ java -jar <PATH_TO_JAVABRIDGE.JAR> <PARAMETERS>

The "JavaBridge.jar" file is found in the installation directory of expecco at:
\exept\expecco\packages\exept\bridgeFramework\javaBridge\javaBin\JavaBridge.jar

The Javabridge code allows for either side to initiate the connection - i.e. it can be run in server mode,
where it awaits an incoming connection, or in client mode, where it actively initiates a connection.
After connection establishment, there is no difference in the operation of the bridge, however depending on the setup of your network infrastructure, especially firewalls, either mechanism may be easier to be used.

Assuming that the bridge is already running on the remote machine as server (default),
use <CODE>newConnectedTo:port:withTimeout:</CODE> to connect to it from the expecco side:
java := JAVA::Java newConnectedTo:'myHost' port:4567 withTimeout:30.
This will initiate the connection setup from the expecco side.

Alternatively, if started in client mode use <CODE>newWaitingForConnectOnHost:port:withTimeout:</CODE>:
java := JAVA::Java newWaitingForConnectOnHost:'localhost' port:4567 withTimeout:30.
which will open a port on the expecco side, and wait until the Java side connects to it.
[[#JAVA::Java|For more details see API]]

====Startup Parameters====
You can use any parameter in any order.
If no parameter is used then the bridge listenes on port 14014 in server mode without keepAlive.
;<code>-help</code>
* Shows the help

;<code>-ip <aHostnameOrIP></code>
* In client mode this specifies the ip or hostname to connect to. In server mode this specifies the ip or hostname to bind to.

;<code>-port <aPortNumber> </code>
* In client mode this specifies the port to connect to. In server mode this specifies the listening port.

;<code>-asClient</code>
* The bridge will start in client mode. If not set the bridge is started in server mode.

;<code>-keepAlive</code>
* By setting this flag the bridge will not exit after the connection has closed and starts to connect or listen again. Otherwise, it will run for a single connection session only.

== Loading Applications (from the expecco side) ==

Normally, you would start your application with the required command line arguments and include the javabridge as jar there. However, in some situations, it may be required to dynamically load other jars into the connected Java VM.
By accessing a classloader, additional classes, or applications as contained in JAR files can be loaded from the expecco side.

This can be used to add a JAR file to the classloader:
<CODE><PRE>
java loadJarByPath:'pathToJarFile'. "/ assuming "java" is a handle as returned from the above connect
</PRE></CODE>

or, if the JAR file is loaded in memory:
<CODE><PRE>
java loadJar:jarByteArray. "/ where "jarByteArray" is a ByteArray containing the JAR file
</PRE></CODE>

If the JVM is on a remote machine, the path is resolved on the expecco side and the JAR will be transferred to the remote side.

Should transferring the JAR be too much overhead, an additional mechanism is provided:
<CODE><PRE>
java loadExtension:'pathToJarFile'.
</PRE></CODE>
this will cache the JAR file on the bridge side and eliminate the overhead of subsequent invocations.

== Java Class Access ==

This following code sample simply references (i.e. accesses) the class "JFrame" from the <CODE>"javax.swing"</CODE> package. The fully specified class name in Java would be <CODE>"javax.swing.JFrame"</CODE>:
<CODE><PRE>
java getJavaClass:'javax.swing.JFrame'
</PRE></CODE>

Or, if you want to load multiple classes:
<CODE><PRE>
java import:'javax.swing.JFrame' import:'javax.swing.JButton'
do:[:jFrame :jButton | "do something with JButton and JFrame" ].
</PRE></CODE>

v2 also supports dynamic compilation of java source code:
<CODE><PRE>
java getJavaClass:'className' fromSource:'classSource'. "/ where classSource is a String containing valid java source code
</PRE></CODE>

and loading precompiled java bytecode:
<CODE><PRE>
java getJavaClass:'className' fromByteCode:byteCode. "/ where byteCode is a ByteArray containing valid java bytecode
</PRE></CODE>

[[#Remote Dynamic Code Injection | for details see Remote Dynamic Code Injection]]

== Instantiating a Class ==

Object instances are created via the "new"-message, sent to a proxy of a Java class. You can get this proxy as described in the previous section. For example, if we want to create a new instance of a "JFrame" and a "JButton", write:
<CODE><PRE>
frame := java getJavaClass:'javax.swing.JFrame' new.
button := java getJavaClass:'javax.swing.JButton' new.
</PRE></CODE>
The first statement results in a proxy object for the "JFrame" instance. The second line results in a proxy for a new "JButton" object.

== Calling Instance Methods ==

A method call is done by a message send to a proxy object, where the message is the method name to call. For example, to call the <CODE>"setVisible(boolean isVisible)"</CODE> method on the above JFrame object, we send the following message to that proxy:
<CODE><PRE>
frame setVisible:true.
</PRE></CODE>

As method naming is different in Smalltalk and Java, a dynamic translation is applied when sending messages from Smalltalk code to a remote Java object. Smalltalk has arguments embedded inside parts of a so called "keyword" message, such as in "receiver foo:arg1 bar:arg2", where "foo:bar:" would be the message name, and "arg1", "arg2" be the arguments.

In Java, the message name is a single identifier, and arguments are written in an argument list after the message name: "receiver.fooBar(arg1, arg2)".

When message names are translated, only the very first part of the Smalltalk keyword message is taken ("foo" in the above example), and the remaining parts are simpl ignored. Thus, any of the Smalltalk messages "foo:bar:", "foo:xxxx:" and "foo:_:" (a single underscore as second part) all translate to the same Java message name "foo()".

Therefore, to call a method with more than one argument, like <CODE>"setSize(int width,int height)"</CODE> on a JFrame instance we can write:
<CODE><PRE>
frame setSize:300 _:200.
</PRE></CODE>
but just as well:
<CODE><PRE>
frame setSize:300 anyWord:200.
</PRE></CODE>
or any other selector with "setSize:" as its first component.
The selector translation mechanism simply takes the first part as the Java selector.

In practice, you should take a reasonably descriptive name, such as: "frame setSize:300 height:200" or only the Java name as first part, such as "frame setSize:300 _:200".

For a call of a method with 4 arguments, we could write:
<CODE><PRE>
frame setBounds:100 y:50 width:300 height:200.
</PRE></CODE>
or:
<CODE><PRE>
frame setBounds:100 _:50 _:300 _:200.
</PRE></CODE>

Also here the <CODE>"y: width: height:"</CODE> can be named as you want, but the first part must be "setBounds:".

=== Calling Static Methods ===

Calling a static method on an object is not different from calling non static methods. In most cases you will call a static method not on an object but directly on the class. This is done by using the class object as "receiver" of the message. For example, if we want to call the static method <CODE>"isDefaultLookAndFeelDecorated()"</CODE> of the JFrame class, write:
<CODE><PRE>
java getJavaClass:'javax.swing.JFrame' isDefaultLookAndFeelDecorated.
</PRE></CODE>

== Accessing Fields ==

As Smalltalk does not support access of an object's fields from the outside (it is fully encapsulated, and access from outside is ONLY allowed via getters/setters), an additional translation mechanism is provided for field access.

Accessing a field of a Java object or a class's static field uses the same syntax as method calls. To access a field, send a message where the message is the field name. To access the field of a class the field must be static.
For example, to get the value of the static field named <CODE>"EXIT_ON_CLOSE"</CODE> of the "JFrame" class, write
<CODE><PRE>
value := java getJavaClass:'javax.swing.JFrame' EXIT_ON_CLOSE.
</PRE></CODE>
The variable "value" now holds the integer value of the <CODE>"EXIT_ON_CLOSE"</CODE> constant.

Assuming that a "JFrame" object had a field named <CODE>"myField"</CODE>, to access this field, we'd have to write:
<CODE><PRE>
value := frame myField.
</PRE></CODE>
and "value" now holding whatever <CODE>"myField"</CODE> returns. This could be another object reference or any primitive value.

=== Setting Fields ===
To set a field, use a setter-like method call:
<CODE><PRE>
frame myField: newValue.
</PRE></CODE>

=== Name Conflicts ===

In very rare situations, a Java object may contain both a field and a method by the same name.
In this case, the Smalltalk code cannot depend on the dynamic translation mechanism (which actually looks for either a field or method name to match), but instead make it explicit, which operation is wanted:
Use:
<CODE><PRE>
frame getFieldByName:'myField'
</PRE></CODE>
to read a field, and:
<CODE><PRE>
frame setFieldByName:'myField' value:123.
</PRE></CODE>
to write the field.

If there are both fields and methods by the same name, and you use the non-explicit call,
the bridge will always assume that you want to call the getter/setter and perform a method call.
 

== Callbacks from Java ==
Sometimes you may want to execute a piece of Smalltalk code during the execution of the Java code. For example, we may want to install a Smalltalk observer to be notified when a button on a Java GUI was pressed,
or some other callback from a Java framework.

The following code registers a Smalltalk block as a callback for a mouse press event of a button:
<CODE><PRE>
listener := MouseListener new.
listener implementMethod:'mousePressed' as:[ Transcript showCR:'Hello from Java' ].
</PRE></CODE>
The above creates the callback and the listener, which can now be registered on a button:
<CODE><PRE>
button addMouseListener:listener.
</PRE></CODE>
Now, with the press of the button in the Java GUI, the Smalltalk block will be executed and writes <CODE>"Hello from Java"</CODE> to the Smalltalk console.
Of course, any other (Smalltalk-)action code can be made to run via this mechanism.

But be aware, that the callback is possibly called later (when the elementary action, which installed the code, has already finished long ago). Also, as the Java code execution is not synchronized with any of your expecco action execution, the callback may also be called at any arbutrary time, even at times when no activity at all is executed on the expecco side. If you forget to cleanup, and the Java object is still alive, it may even be called after you have finished your test run (if you keep the java bridge handle around and alive, for example in an expecoo environment variable).

So the Smalltalk callback code should not depend on any particular elementary action to be currently running, but instead in most cases write some information into a shared data container, preferably an instance of "SharedQueue", which is thread safe. Then, some other action (an elementary action) would read-wait and read events from that shared queue.

make sure that your test correctly cleans up any such callbacks afterwards. As a last resort, use the "Shutdown Bridge Connection" menu item, which closes the bridge connection, and thereby - as a side effect - removes any leftover callbacks. It does close the connection, and any remaining java proxy object handles become invalid, though.

Another example, using an observer could look like:
<CODE><PRE>
observer := java Observer new.
observer implementMethod:'update'
as:[:sourceObservable :argument|
argument notNil ifTrue:[ Transcript showCR:('I was notifyed with: ',argument toString) ]
ifFalse:[ Transcript showCR:'I was notifyed and the argument was nil' ].
].
myObservable addObserver:observer.
</PRE></CODE>
When the observable calls <CODE>"notifyObservers"</CODE>, the Smalltalk block will be executed.

== Exceptions in Java ==
Exceptions on the Java side are signalled back to the Smalltalk side and raise a corresponding exception there. However, on the Java side, the call stack which lead to the exception has already been unwound at that time (Java exceptions are not proceedable). So a proceed in the Smalltalk-side exception handler only affects the Smalltalk caller, but may leave the Java side in an undefined state.

== Remote Dynamic Code Injection ==
Sometimes we might want to execute code without the overhead of many rpc-messages being sent over the bridge, especially if we want to do something time critical, or want to make execution time measurements.
For this, it is possible to load a class at runtime into the JavaVM. The code of the class will first be sent to the JavaVM, which will compile and load the generated byte code. Then, the class can be accessed via the bridge just like any other preloaded class.

The following example specifies the class code in a smalltalk string and inject the code into the JavaVM. Then an instance of that new class will be instantiated and finally a method of the object instance will be invoked:
<CODE><PRE>
classCode := '
package myPackage.test;

import java.awt.BorderLayout;
import java.awt.event.MouseAdapter;
import java.awt.event.MouseEvent;
import java.util.Calendar;

import javax.swing.JButton;
import javax.swing.JFrame;
import javax.swing.JLabel;;

public class MyInjectedClass {
public void createSampleApp(){
JFrame frame=new JFrame("Hello im injected");
frame.setLayout(new BorderLayout());
JButton button=new JButton("click me");
final JLabel label=new JLabel("Text");
button.addMouseListener(new MouseAdapter() {

@Override
public void mouseClicked(MouseEvent e) {
label.setText(Calendar.getInstance().getTime().toString());
}
});
frame.add(label,BorderLayout.NORTH);
frame.add(button,BorderLayout.SOUTH);
frame.setSize(300, 300);
frame.setVisible(true);
}
}
'.
classObject := java getJavaClass:'myPackage.test.MyInjectedClass' fromSource:classCode.
classObject new createSampleApp.
</PRE></CODE>
After the code has been injected, a new instance of <CODE>"MyInjectedClass"</CODE> is created and the <CODE>"createSampleApp"</CODE> method is called. Because the example implements a GUI, a Java window will open, containing a label and a button. Clicking the button displays the current time in the label.



=== Code Sources for Class injection ===
There are 3 possible types of class code sources which we can use to inject the code. In the examples before we directly used a simple <CODE>"String"</CODE> in the smalltalk code as a code source. We also can use a <CODE>"*.java"</CODE> file as source. Just read the content of the file into a string and use it as in the previous examples.

To inject a <CODE>"*.class"</CODE> file use the following code:
<pre>
java getJavaClass:'the.class.name' fromByteCode:classCode.
</pre>

== Examples ==

This example creates a JFrame with one button inside. Then a Mouselistener is created and registered on the button. When the button is pressed, the title of the window changes to <CODE>"onPressed"</CODE> and the Transcript shows the message <CODE>"onPressed"</CODE>. When the button is released, the title of the window is changed to <CODE>"onReleased"</CODE> and the Transcript shows <CODE>"onReleased"</CODE>. If the button lost the mouse focus, the bridge will exit (disconnect), and the Java side is terminated.
<CODE><PRE>
|java frame button listener|

"/getting a bridge
java := JAVA::JavaBridge newWithServer.

"/creating a new frame and button object
frame := java getJavaClass:'javax.swing.JFrame' new.
button := java JButton new:'Click'.

"/creating a new mouse listener and adding callback blocks
listener := java MouseListener new.

listener implementMethod:'mousePressed' as:[ Transcript showCR:'onPress'. frame setTitle:'onPressed' ].
listener implementMethod:'mouseReleased' as:[ Transcript showCR:'onReleased'. frame setTitle:'onReleased' ].
listener implementMethod:'mouseExited' as:[ Transcript showCR:'onExited'. java closeBridge. ].

"/register the mouse listener on the button and make the frame with button visible
button addMouseListener:listener.
frame add:button.
frame setSize:300 y:100.
frame setVisible: true.
</PRE></CODE>



==Differences between v1 and v2==
===General===
* A Java Bridge instance no longer requires multiple tcp ports to be open. This simplifies connection through ssh tunnels and firewalls.
* The identity of strings and primitve wrappers can be preserved. (see [[#boxedDo:aBlock | boxedDo]])
* Arrays of primitive types are serialized.

===Loading Applications===
* '''addJarByPath:''' and '''addToClassPath:''' are still supported but have been deprecated. use '''loadJar:''', '''loadJarByPath:''' and '''loadExtension:''' instead. The new methods no longer require the jar or library to be present on the remote machine.

[[Java Interface Library#Loading Applications (from the expecco side) | v1]] [[#Loading Applications (from the expecco side) | v2]]

===Java Class Access===
* Sending the fully qualified name with instances of "." replaced by "_" to the bridge handle is still supported, but not recommended.
* A new method '''getJavaClass:''' has been introduced (also available for v1 since expecco v2.9). This solves the side effects of "_" being a legal character in class names.

[[Java Interface Library#Java Package Import and Class Access | v1]] [[#Java Class Access | v2]]
===Callbacks from Java===
* A new method '''implementMethod:as:''' has been introduced to assign callback blocks to method names. The old way is still supported.

[[Java Interface Library#Callbacks from Java | v1]] [[#Callbacks from Java | v2]]

===Remote Dynamic Code Injection===
* Code injection was problematic in v1 and has now been re-implemented in v2.

[[#Remote Dynamic Code Injection | v2]]

== API ==
===JAVA::Java===
====class protocol====
=====newWithServer=====
* This will start a local JavaVM, running the JavaBridge, and establishes a connection on a random free port.
: A new connected instance of JAVA::Java class is returned.

=====newWithServerForJavaPath:aJavaPathFilename=====
* This is the same as newWithServer but the path to the java executable can be specified. The JavaVM version must be 1.6 or higher to run the JavaBridge.
:: '''aJavaPathFilename''' - must be a instance of Filename
Smalltalk: JAVA::Java newWithServerForJavaPath:('my\path\to\java.executable'asFilename).
JavaScript: JAVA::Java.newWithServerForJavaPath("my\path\to\java.executable".asFilename());

=====newConnectedTo:aHhostString port:aPortNumber withTimeout:aTimeoutSeconds=====
* This is used to connect to a running JavaBridge on the network. The JavaBridge must be started in server mode on the remote host. After connecting a new connected instance of JAVA::Java is returned.
:: '''aHostString''' - the hostname or IP of the remote machine as String
:: '''aPortNumber ''' - the port on which the remote machine is listening as Number
:: '''aTimeoutSeconds''' - a connect timeout in seconds as Number
Smalltalk: JAVA::Java newConnectedTo:'myHostName' port:4567 withTimeout:30.
JavaScript: JAVA::Java.newConnectedTo_port_withTimeout("myHostName",4567,30);

=====newWaitingForConnectOnHost:aListeningAddressString port:aListeningPortNumber withTimeout:aTimeoutSeconds=====
* This is used to wait for incomming connecions of a running JavaBridge on the network. The JavaBridge must be started in client mode on the remote host. After connecting a new connected instance of JAVA::Java is returned.
:: '''deprecated: aListeningAddressString''' - no longer used. Can be nil.
:: '''aListeningPortNumber ''' - the port on which to listen for incomming connections as Number
:: '''aTimeoutSeconds''' - a connect timeout in seconds as Number, If nil it will wait endless.

=====singletonInstance=====
* This will call newWithServer for the first time and then always returns the same connected JAVA::Java instance until the connection was closed, then a new connected instance is returned.

=====exitAllInstances=====
* This will close all instances of JAVA::Java.

====instance protocol====
=====loadJarByPath:aPath=====
* Adds a jar to the running JavaVM. If the jar depends on other jars or libraries you have to add them too.
:: '''aPath''' - the path to the jar file as String.

=====loadJar:aByteArray=====
* Adds a jar to the running JavaVM. If the jar depends on other jars or libraries you have to add them too.
:: '''aByteArrays''' - a ByteArray containing the JAR file.

=====loadExtension:aPath=====
* Adds a jar to the running JavaVM and caches it for subsequent usages. If the jar depends on other jars you have to add them too.
:: '''aPath''' - the path to the jar file as String.

=====boxedDo:aBlock=====
* Any autoboxed values in aBlock returned from the JavaVM are preserved as such. By default autoboxed values are automatically unboxed. This way, the identity of such objects is preserved.

=====isConnected=====
* Tests if a connection is still established.
:: '''return:''' - true if the connection is still established, else false.

=====isAlive=====
* Tests if a connection is still responding.
:: '''return:''' - true if the connection is still alive, else false. Does a message round trip.

=====closeBridge=====
* This will close the bridge connection. Depending on in which mode the JavaBridge was started, the JavaVM is also closed (-keepAlive startparameter not set).

=====exit=====
* Same as closeBridge.

== See Also==
The [[DOT NET Interface Library| DOTNET Interface Plugin & Library]], which implements a likewise interface for .NET applications/libraries.

<hr>
Back to [[Plugins]]

Java Interface Library v2

2016-05-31T16:28:59Z

Javogel: /* Differences between v1 and v2 */

== Introduction ==

This article discusses version 2 of the Java Bridge (which is as of expecco v2.9 still experimental).
The article for version 1 can be found [[Java Interface Library | here]].

The Java Interface library ("Java Bridge") is used to interact with Java objects inside an external Java Virtual Machine (JVM).

The access to Java objects, classes and programs is done via a framework called "''Java-Bridge''", which is similar in operation to the [[DOT NET Interface Library| dotNET bridge]]. This framework implements transparent forwarding of method (virtual function) calls to Java objects, which exist in a local or remote Java Virtual Machine (JVM). Also, return values, callBacks and exception information are passed back from the Java program to expecco. This is done by a proxy-object mechanism, which catches all function calls, wraps the arguments, sends a datagram to the other bridge side, awaits the reply and returns the result to the original caller. Thus, remote procedure calls are almost completely transparent to the Smalltalk/JavaScript code inside expecco. In your elementary code, you can write remote function calls as if they were to local objects.

Notice that this document describes the low level framework, which implements the bridge communication. A much easier to use high level interface (called "Groovy Blocks") exists and should normally be used, if you need access to a java application's internals during testing.
Please take a look at
[[Expecco_API#Groovy_Elementary_Blocks | "Groovy Block API"]]
and [[Testing Java Applications using Groovy blocks/en | "Testing Java Applications using Groovy blocks"]].

== Architecture ==

On the expecco side, the bridge consists of a number of Proxy objects,
which behave like regular Smalltalk objects as seen from elementary expecco code.
However, instead of performing an action when one of their methods (virtual functions) is called,
they send a message over a socket connection to the Java VM (actually: to a bridge software inside the
Java application) which decodes the message and sends it to the destination Java object.
The same is done in reverse direction with the return value.

+---------------------+ +----------+ +----------------+ +----------------+ +---------+
| | | | | | | | | Java |
| expecco |---->| Proxy |---->| Bridge |==>>==| Bridge |---->| Object |
| (elementary code) |<----| |<----| (expecco side) |==<<==| (Java side) |<----| |
+---------------------+ +----------+ +----------------+ +----------------+ +---------+

This setup allows for transparent communication with objects inside a local or remote Java VM. This may be either utility functions which happen to be convenient for the test application (for example: file parsing, syntax analysis, protocol implementaitons or access to specific hardware via driver libraries), or the tested application in the system under test itself.

Especially, it allows for the objects of the tested application to be looked into, manipulated and for functions of it or underlying frameworks to be called.

For expecco code, we tried to make this as transparent as possible, however there are a few exceptions, when function names need to be translated (for example, because the function naming syntax is different) or due to the fact that for some operations no corresponding name exists in Smalltalk (array access, for example).

Of course, multiple such connections can coexist and be served/handled in parallel. This enables an expecco test suite to communicate with both sides of a tested client-server Java application, for example.

Notice that a similar mechanism is used in expecco to communicate with DOTNET, Qt (C++) and C applications.

 

== Initializing / Releasing the Bridge ==

Before any communication can take place between expecco and any Java object, the Java side of the bridge has to be started, and a communication has to be established.
In expecco, all of the bridge classes are found in the <CODE>JAVA</CODE> namespace.

The main interface class is "<CODE>Java</CODE>", in the "<CODE>JAVA</CODE>" namespace:
<CODE><PRE>
java := JAVA::Java newWithServer.
</PRE></CODE>
or (in JavaScript):
<CODE><PRE>
java = JAVA::Java.newWithServer();
</PRE></CODE>

This starts the Java-side of the bridge (actually executes java as a background command) on the local machine, and establishes a connection to that JVM.

The bridge connection should be closed, if the bridge is no longer needed. Release the bridge with:
<CODE><PRE>
java.closeBridge();
</PRE></CODE>
which terminates the connection.

=== Start and Connect to a Remote Machine ===
The above started a Java VM and connected to it. Alternatively, you may want to connect to an already running Java program (typically, your system under test).
In order for your program to be reachable, it must allow for the bridge to connect to it via a special bridge-connection, which is a socket connection. For this, it must execute the server code found in the "JavaBridge.jar" file. To pass [[#Startup Parameters| parameters]] you will typically start it from a command line or a little shell/batch script.

Call (on the shell/cmd level):
$ java -jar <PATH_TO_JAVABRIDGE.JAR> <PARAMETERS>

The "JavaBridge.jar" file is found in the installation directory of expecco at:
\exept\expecco\packages\exept\bridgeFramework\javaBridge\javaBin\JavaBridge.jar

The Javabridge code allows for either side to initiate the connection - i.e. it can be run in server mode,
where it awaits an incoming connection, or in client mode, where it actively initiates a connection.
After connection establishment, there is no difference in the operation of the bridge, however depending on the setup of your network infrastructure, especially firewalls, either mechanism may be easier to be used.

Assuming that the bridge is already running on the remote machine as server (default),
use <CODE>newConnectedTo:port:withTimeout:</CODE> to connect to it from the expecco side:
java := JAVA::Java newConnectedTo:'myHost' port:4567 withTimeout:30.
This will initiate the connection setup from the expecco side.

Alternatively, if started in client mode use <CODE>newWaitingForConnectOnHost:port:withTimeout:</CODE>:
java := JAVA::Java newWaitingForConnectOnHost:'localhost' port:4567 withTimeout:30.
which will open a port on the expecco side, and wait until the Java side connects to it.
[[#JAVA::Java|For more details see API]]

====Startup Parameters====
You can use any parameter in any order.
If no parameter is used then the bridge listenes on port 14014 in server mode without keepAlive.
;<code>-help</code>
* Shows the help

;<code>-ip <aHostnameOrIP></code>
* In client mode this specifies the ip or hostname to connect to. In server mode this specifies the ip or hostname to bind to.

;<code>-port <aPortNumber> </code>
* In client mode this specifies the port to connect to. In server mode this specifies the listening port.

;<code>-asClient</code>
* The bridge will start in client mode. If not set the bridge is started in server mode.

;<code>-keepAlive</code>
* By setting this flag the bridge will not exit after the connection has closed and starts to connect or listen again. Otherwise, it will run for a single connection session only.

== Loading Applications (from the expecco side) ==

Normally, you would start your application with the required command line arguments and include the javabridge as jar there. However, in some situations, it may be required to dynamically load other jars into the connected Java VM.
By accessing a classloader, additional classes, or applications as contained in JAR files can be loaded from the expecco side.

This can be used to add a JAR file to the classloader:
<CODE><PRE>
java loadJarByPath:'pathToJarFile'. "/ assuming "java" is a handle as returned from the above connect
</PRE></CODE>

or, if the JAR file is loaded in memory:
<CODE><PRE>
java loadJar:jarByteArray. "/ where "jarByteArray" is a ByteArray containing the JAR file
</PRE></CODE>

If the JVM is on a remote machine, the path is resolved on the expecco side and the JAR will be transferred to the remote side.

Should transferring the JAR be too much overhead, an additional mechanism is provided:
<CODE><PRE>
java loadExtension:'pathToJarFile'.
</PRE></CODE>
this will cache the JAR file on the bridge side and eliminate the overhead of subsequent invocations.

== Java Class Access ==

This following code sample simply references (i.e. accesses) the class "JFrame" from the <CODE>"javax.swing"</CODE> package. The fully specified class name in Java would be <CODE>"javax.swing.JFrame"</CODE>:
<CODE><PRE>
java getJavaClass:'javax.swing.JFrame'
</PRE></CODE>

Or, if you want to load multiple classes:
<CODE><PRE>
java import:'javax.swing.JFrame' import:'javax.swing.JButton'
do:[:jFrame :jButton | "do something with JButton and JFrame" ].
</PRE></CODE>

v2 also supports dynamic compilation of java source code:
<CODE><PRE>
java getJavaClass:'className' fromSource:'classSource'. "/ where classSource is a String containing valid java source code
</PRE></CODE>

and loading precompiled java bytecode:
<CODE><PRE>
java getJavaClass:'className' fromByteCode:byteCode. "/ where byteCode is a ByteArray containing valid java bytecode
</PRE></CODE>

[[#Remote Dynamic Code Injection | for details see Remote Dynamic Code Injection]]

== Instantiating a Class ==

Object instances are created via the "new"-message, sent to a proxy of a Java class. You can get this proxy as described in the previous section. For example, if we want to create a new instance of a "JFrame" and a "JButton", write:
<CODE><PRE>
frame := java getJavaClass:'javax.swing.JFrame' new.
button := java getJavaClass:'javax.swing.JButton' new.
</PRE></CODE>
The first statement results in a proxy object for the "JFrame" instance. The second line results in a proxy for a new "JButton" object.

== Calling Instance Methods ==

A method call is done by a message send to a proxy object, where the message is the method name to call. For example, to call the <CODE>"setVisible(boolean isVisible)"</CODE> method on the above JFrame object, we send the following message to that proxy:
<CODE><PRE>
frame setVisible:true.
</PRE></CODE>

As method naming is different in Smalltalk and Java, a dynamic translation is applied when sending messages from Smalltalk code to a remote Java object. Smalltalk has arguments embedded inside parts of a so called "keyword" message, such as in "receiver foo:arg1 bar:arg2", where "foo:bar:" would be the message name, and "arg1", "arg2" be the arguments.

In Java, the message name is a single identifier, and arguments are written in an argument list after the message name: "receiver.fooBar(arg1, arg2)".

When message names are translated, only the very first part of the Smalltalk keyword message is taken ("foo" in the above example), and the remaining parts are simpl ignored. Thus, any of the Smalltalk messages "foo:bar:", "foo:xxxx:" and "foo:_:" (a single underscore as second part) all translate to the same Java message name "foo()".

Therefore, to call a method with more than one argument, like <CODE>"setSize(int width,int height)"</CODE> on a JFrame instance we can write:
<CODE><PRE>
frame setSize:300 _:200.
</PRE></CODE>
but just as well:
<CODE><PRE>
frame setSize:300 anyWord:200.
</PRE></CODE>
or any other selector with "setSize:" as its first component.
The selector translation mechanism simply takes the first part as the Java selector.

In practice, you should take a reasonably descriptive name, such as: "frame setSize:300 height:200" or only the Java name as first part, such as "frame setSize:300 _:200".

For a call of a method with 4 arguments, we could write:
<CODE><PRE>
frame setBounds:100 y:50 width:300 height:200.
</PRE></CODE>
or:
<CODE><PRE>
frame setBounds:100 _:50 _:300 _:200.
</PRE></CODE>

Also here the <CODE>"y: width: height:"</CODE> can be named as you want, but the first part must be "setBounds:".

=== Calling Static Methods ===

Calling a static method on an object is not different from calling non static methods. In most cases you will call a static method not on an object but directly on the class. This is done by using the class object as "receiver" of the message. For example, if we want to call the static method <CODE>"isDefaultLookAndFeelDecorated()"</CODE> of the JFrame class, write:
<CODE><PRE>
java getJavaClass:'javax.swing.JFrame' isDefaultLookAndFeelDecorated.
</PRE></CODE>

== Accessing Fields ==

As Smalltalk does not support access of an object's fields from the outside (it is fully encapsulated, and access from outside is ONLY allowed via getters/setters), an additional translation mechanism is provided for field access.

Accessing a field of a Java object or a class's static field uses the same syntax as method calls. To access a field, send a message where the message is the field name. To access the field of a class the field must be static.
For example, to get the value of the static field named <CODE>"EXIT_ON_CLOSE"</CODE> of the "JFrame" class, write
<CODE><PRE>
value := java getJavaClass:'javax.swing.JFrame' EXIT_ON_CLOSE.
</PRE></CODE>
The variable "value" now holds the integer value of the <CODE>"EXIT_ON_CLOSE"</CODE> constant.

Assuming that a "JFrame" object had a field named <CODE>"myField"</CODE>, to access this field, we'd have to write:
<CODE><PRE>
value := frame myField.
</PRE></CODE>
and "value" now holding whatever <CODE>"myField"</CODE> returns. This could be another object reference or any primitive value.

=== Setting Fields ===
To set a field, use a setter-like method call:
<CODE><PRE>
frame myField: newValue.
</PRE></CODE>

=== Name Conflicts ===

In very rare situations, a Java object may contain both a field and a method by the same name.
In this case, the Smalltalk code cannot depend on the dynamic translation mechanism (which actually looks for either a field or method name to match), but instead make it explicit, which operation is wanted:
Use:
<CODE><PRE>
frame getFieldByName:'myField'
</PRE></CODE>
to read a field, and:
<CODE><PRE>
frame setFieldByName:'myField' value:123.
</PRE></CODE>
to write the field.

If there are both fields and methods by the same name, and you use the non-explicit call,
the bridge will always assume that you want to call the getter/setter and perform a method call.
 

== Callbacks from Java ==
Sometimes you may want to execute a piece of Smalltalk code during the execution of the Java code. For example, we may want to install a Smalltalk observer to be notified when a button on a Java GUI was pressed,
or some other callback from a Java framework.

The following code registers a Smalltalk block as a callback for a mouse press event of a button:
<CODE><PRE>
listener := MouseListener new.
listener implementMethod:'mousePressed' as:[ Transcript showCR:'Hello from Java' ].
</PRE></CODE>
The above creates the callback and the listener, which can now be registered on a button:
<CODE><PRE>
button addMouseListener:listener.
</PRE></CODE>
Now, with the press of the button in the Java GUI, the Smalltalk block will be executed and writes <CODE>"Hello from Java"</CODE> to the Smalltalk console.
Of course, any other (Smalltalk-)action code can be made to run via this mechanism.

But be aware, that the callback is possibly called later (when the elementary action, which installed the code, has already finished long ago). Also, as the Java code execution is not synchronized with any of your expecco action execution, the callback may also be called at any arbutrary time, even at times when no activity at all is executed on the expecco side. If you forget to cleanup, and the Java object is still alive, it may even be called after you have finished your test run (if you keep the java bridge handle around and alive, for example in an expecoo environment variable).

So the Smalltalk callback code should not depend on any particular elementary action to be currently running, but instead in most cases write some information into a shared data container, preferably an instance of "SharedQueue", which is thread safe. Then, some other action (an elementary action) would read-wait and read events from that shared queue.

make sure that your test correctly cleans up any such callbacks afterwards. As a last resort, use the "Shutdown Bridge Connection" menu item, which closes the bridge connection, and thereby - as a side effect - removes any leftover callbacks. It does close the connection, and any remaining java proxy object handles become invalid, though.

Another example, using an observer could look like:
<CODE><PRE>
observer := java Observer new.
observer implementMethod:'update'
as:[:sourceObservable :argument|
argument notNil ifTrue:[ Transcript showCR:('I was notifyed with: ',argument toString) ]
ifFalse:[ Transcript showCR:'I was notifyed and the argument was nil' ].
].
myObservable addObserver:observer.
</PRE></CODE>
When the observable calls <CODE>"notifyObservers"</CODE>, the Smalltalk block will be executed.

== Exceptions in Java ==
Exceptions on the Java side are signalled back to the Smalltalk side and raise a corresponding exception there. However, on the Java side, the call stack which lead to the exception has already been unwound at that time (Java exceptions are not proceedable). So a proceed in the Smalltalk-side exception handler only affects the Smalltalk caller, but may leave the Java side in an undefined state.

== Remote Dynamic Code Injection ==
Sometimes we might want to execute code without the overhead of many rpc-messages being sent over the bridge, especially if we want to do something time critical, or want to make execution time measurements.
For this, it is possible to load a class at runtime into the JavaVM. The code of the class will first be sent to the JavaVM, which will compile and load the generated byte code. Then, the class can be accessed via the bridge just like any other preloaded class.

The following example specifies the class code in a smalltalk string and inject the code into the JavaVM. Then an instance of that new class will be instantiated and finally a method of the object instance will be invoked:
<CODE><PRE>
classCode := '
package myPackage.test;

import java.awt.BorderLayout;
import java.awt.event.MouseAdapter;
import java.awt.event.MouseEvent;
import java.util.Calendar;

import javax.swing.JButton;
import javax.swing.JFrame;
import javax.swing.JLabel;;

public class MyInjectedClass {
public void createSampleApp(){
JFrame frame=new JFrame("Hello im injected");
frame.setLayout(new BorderLayout());
JButton button=new JButton("click me");
final JLabel label=new JLabel("Text");
button.addMouseListener(new MouseAdapter() {

@Override
public void mouseClicked(MouseEvent e) {
label.setText(Calendar.getInstance().getTime().toString());
}
});
frame.add(label,BorderLayout.NORTH);
frame.add(button,BorderLayout.SOUTH);
frame.setSize(300, 300);
frame.setVisible(true);
}
}
'.
classObject := java getJavaClass:'myPackage.test.MyInjectedClass' fromSource:classCode.
classObject new createSampleApp.
</PRE></CODE>
After the code has been injected, a new instance of <CODE>"MyInjectedClass"</CODE> is created and the <CODE>"createSampleApp"</CODE> method is called. Because the example implements a GUI, a Java window will open, containing a label and a button. Clicking the button displays the current time in the label.



=== Code Sources for Class injection ===
There are 3 possible types of class code sources which we can use to inject the code. In the examples before we directly used a simple <CODE>"String"</CODE> in the smalltalk code as a code source. We also can use a <CODE>"*.java"</CODE> file as source. Just read the content of the file into a string and use it as in the previous examples.

To inject a <CODE>"*.class"</CODE> file use the following code:
<pre>
java getJavaClass:'the.class.name' fromByteCode:classCode.
</pre>

== Examples ==

This example creates a JFrame with one button inside. Then a Mouselistener is created and registered on the button. When the button is pressed, the title of the window changes to <CODE>"onPressed"</CODE> and the Transcript shows the message <CODE>"onPressed"</CODE>. When the button is released, the title of the window is changed to <CODE>"onReleased"</CODE> and the Transcript shows <CODE>"onReleased"</CODE>. If the button lost the mouse focus, the bridge will exit (disconnect), and the Java side is terminated.
<CODE><PRE>
|java frame button listener|

"/getting a bridge
java := JAVA::JavaBridge newWithServer.

"/creating a new frame and button object
frame := java getJavaClass:'javax.swing.JFrame' new.
button := java JButton new:'Click'.

"/creating a new mouse listener and adding callback blocks
listener := java MouseListener new.

listener implementMethod:'mousePressed' as:[ Transcript showCR:'onPress'. frame setTitle:'onPressed' ].
listener implementMethod:'mouseReleased' as:[ Transcript showCR:'onReleased'. frame setTitle:'onReleased' ].
listener implementMethod:'mouseExited' as:[ Transcript showCR:'onExited'. java closeBridge. ].

"/register the mouse listener on the button and make the frame with button visible
button addMouseListener:listener.
frame add:button.
frame setSize:300 y:100.
frame setVisible: true.
</PRE></CODE>



==Differences between v1 and v2==
===General===
* A Java Bridge instance no longer requires multiple tcp ports to be open. This simplifies connection through ssh tunnels and firewalls.
* The identity of strings and primitve wrappers can be preserved. (see [[#API#JAVA::Java#instance protocol#boxedDo:aBlock | boxedDo]])
* Arrays of primitive types are serialized.

===Loading Applications===
* '''addJarByPath:''' and '''addToClassPath:''' are still supported but have been deprecated. use '''loadJar:''', '''loadJarByPath:''' and '''loadExtension:''' instead. The new methods no longer require the jar or library to be present on the remote machine.

[[Java Interface Library#Loading Applications (from the expecco side) | v1]] [[#Loading Applications (from the expecco side) | v2]]

===Java Class Access===
* Sending the fully qualified name with instances of "." replaced by "_" to the bridge handle is still supported, but not recommended.
* A new method '''getJavaClass:''' has been introduced (also available for v1 since expecco v2.9). This solves the side effects of "_" being a legal character in class names.

[[Java Interface Library#Java Package Import and Class Access | v1]] [[#Java Class Access | v2]]
===Callbacks from Java===
* A new method '''implementMethod:as:''' has been introduced to assign callback blocks to method names. The old way is still supported.

[[Java Interface Library#Callbacks from Java | v1]] [[#Callbacks from Java | v2]]

===Remote Dynamic Code Injection===
* Code injection was problematic in v1 and has now been re-implemented in v2.

[[#Remote Dynamic Code Injection | v2]]

== API ==
===JAVA::Java===
====class protocol====
=====newWithServer=====
* This will start a local JavaVM, running the JavaBridge, and establishes a connection on a random free port.
: A new connected instance of JAVA::Java class is returned.

=====newWithServerForJavaPath:aJavaPathFilename=====
* This is the same as newWithServer but the path to the java executable can be specified. The JavaVM version must be 1.6 or higher to run the JavaBridge.
:: '''aJavaPathFilename''' - must be a instance of Filename
Smalltalk: JAVA::Java newWithServerForJavaPath:('my\path\to\java.executable'asFilename).
JavaScript: JAVA::Java.newWithServerForJavaPath("my\path\to\java.executable".asFilename());

=====newConnectedTo:aHhostString port:aPortNumber withTimeout:aTimeoutSeconds=====
* This is used to connect to a running JavaBridge on the network. The JavaBridge must be started in server mode on the remote host. After connecting a new connected instance of JAVA::Java is returned.
:: '''aHostString''' - the hostname or IP of the remote machine as String
:: '''aPortNumber ''' - the port on which the remote machine is listening as Number
:: '''aTimeoutSeconds''' - a connect timeout in seconds as Number
Smalltalk: JAVA::Java newConnectedTo:'myHostName' port:4567 withTimeout:30.
JavaScript: JAVA::Java.newConnectedTo_port_withTimeout("myHostName",4567,30);

=====newWaitingForConnectOnHost:aListeningAddressString port:aListeningPortNumber withTimeout:aTimeoutSeconds=====
* This is used to wait for incomming connecions of a running JavaBridge on the network. The JavaBridge must be started in client mode on the remote host. After connecting a new connected instance of JAVA::Java is returned.
:: '''deprecated: aListeningAddressString''' - no longer used. Can be nil.
:: '''aListeningPortNumber ''' - the port on which to listen for incomming connections as Number
:: '''aTimeoutSeconds''' - a connect timeout in seconds as Number, If nil it will wait endless.

=====singletonInstance=====
* This will call newWithServer for the first time and then always returns the same connected JAVA::Java instance until the connection was closed, then a new connected instance is returned.

=====exitAllInstances=====
* This will close all instances of JAVA::Java.

====instance protocol====
=====loadJarByPath:aPath=====
* Adds a jar to the running JavaVM. If the jar depends on other jars or libraries you have to add them too.
:: '''aPath''' - the path to the jar file as String.

=====loadJar:aByteArray=====
* Adds a jar to the running JavaVM. If the jar depends on other jars or libraries you have to add them too.
:: '''aByteArrays''' - a ByteArray containing the JAR file.

=====loadExtension:aPath=====
* Adds a jar to the running JavaVM and caches it for subsequent usages. If the jar depends on other jars you have to add them too.
:: '''aPath''' - the path to the jar file as String.

=====boxedDo:aBlock=====
* Any autoboxed values in aBlock returned from the JavaVM are preserved as such. By default autoboxed values are automatically unboxed. This way, the identity of such objects is preserved.

=====isConnected=====
* Tests if a connection is still established.
:: '''return:''' - true if the connection is still established, else false.

=====isAlive=====
* Tests if a connection is still responding.
:: '''return:''' - true if the connection is still alive, else false. Does a message round trip.

=====closeBridge=====
* This will close the bridge connection. Depending on in which mode the JavaBridge was started, the JavaVM is also closed (-keepAlive startparameter not set).

=====exit=====
* Same as closeBridge.

== See Also==
The [[DOT NET Interface Library| DOTNET Interface Plugin & Library]], which implements a likewise interface for .NET applications/libraries.

<hr>
Back to [[Plugins]]

Java Interface Library v2

2016-05-31T16:10:47Z

Javogel: /* Differences between v1 and v2 */

== Introduction ==

This article discusses version 2 of the Java Bridge (which is as of expecco v2.9 still experimental).
The article for version 1 can be found [[Java Interface Library | here]].

The Java Interface library ("Java Bridge") is used to interact with Java objects inside an external Java Virtual Machine (JVM).

The access to Java objects, classes and programs is done via a framework called "''Java-Bridge''", which is similar in operation to the [[DOT NET Interface Library| dotNET bridge]]. This framework implements transparent forwarding of method (virtual function) calls to Java objects, which exist in a local or remote Java Virtual Machine (JVM). Also, return values, callBacks and exception information are passed back from the Java program to expecco. This is done by a proxy-object mechanism, which catches all function calls, wraps the arguments, sends a datagram to the other bridge side, awaits the reply and returns the result to the original caller. Thus, remote procedure calls are almost completely transparent to the Smalltalk/JavaScript code inside expecco. In your elementary code, you can write remote function calls as if they were to local objects.

Notice that this document describes the low level framework, which implements the bridge communication. A much easier to use high level interface (called "Groovy Blocks") exists and should normally be used, if you need access to a java application's internals during testing.
Please take a look at
[[Expecco_API#Groovy_Elementary_Blocks | "Groovy Block API"]]
and [[Testing Java Applications using Groovy blocks/en | "Testing Java Applications using Groovy blocks"]].

== Architecture ==

On the expecco side, the bridge consists of a number of Proxy objects,
which behave like regular Smalltalk objects as seen from elementary expecco code.
However, instead of performing an action when one of their methods (virtual functions) is called,
they send a message over a socket connection to the Java VM (actually: to a bridge software inside the
Java application) which decodes the message and sends it to the destination Java object.
The same is done in reverse direction with the return value.

+---------------------+ +----------+ +----------------+ +----------------+ +---------+
| | | | | | | | | Java |
| expecco |---->| Proxy |---->| Bridge |==>>==| Bridge |---->| Object |
| (elementary code) |<----| |<----| (expecco side) |==<<==| (Java side) |<----| |
+---------------------+ +----------+ +----------------+ +----------------+ +---------+

This setup allows for transparent communication with objects inside a local or remote Java VM. This may be either utility functions which happen to be convenient for the test application (for example: file parsing, syntax analysis, protocol implementaitons or access to specific hardware via driver libraries), or the tested application in the system under test itself.

Especially, it allows for the objects of the tested application to be looked into, manipulated and for functions of it or underlying frameworks to be called.

For expecco code, we tried to make this as transparent as possible, however there are a few exceptions, when function names need to be translated (for example, because the function naming syntax is different) or due to the fact that for some operations no corresponding name exists in Smalltalk (array access, for example).

Of course, multiple such connections can coexist and be served/handled in parallel. This enables an expecco test suite to communicate with both sides of a tested client-server Java application, for example.

Notice that a similar mechanism is used in expecco to communicate with DOTNET, Qt (C++) and C applications.

 

== Initializing / Releasing the Bridge ==

Before any communication can take place between expecco and any Java object, the Java side of the bridge has to be started, and a communication has to be established.
In expecco, all of the bridge classes are found in the <CODE>JAVA</CODE> namespace.

The main interface class is "<CODE>Java</CODE>", in the "<CODE>JAVA</CODE>" namespace:
<CODE><PRE>
java := JAVA::Java newWithServer.
</PRE></CODE>
or (in JavaScript):
<CODE><PRE>
java = JAVA::Java.newWithServer();
</PRE></CODE>

This starts the Java-side of the bridge (actually executes java as a background command) on the local machine, and establishes a connection to that JVM.

The bridge connection should be closed, if the bridge is no longer needed. Release the bridge with:
<CODE><PRE>
java.closeBridge();
</PRE></CODE>
which terminates the connection.

=== Start and Connect to a Remote Machine ===
The above started a Java VM and connected to it. Alternatively, you may want to connect to an already running Java program (typically, your system under test).
In order for your program to be reachable, it must allow for the bridge to connect to it via a special bridge-connection, which is a socket connection. For this, it must execute the server code found in the "JavaBridge.jar" file. To pass [[#Startup Parameters| parameters]] you will typically start it from a command line or a little shell/batch script.

Call (on the shell/cmd level):
$ java -jar <PATH_TO_JAVABRIDGE.JAR> <PARAMETERS>

The "JavaBridge.jar" file is found in the installation directory of expecco at:
\exept\expecco\packages\exept\bridgeFramework\javaBridge\javaBin\JavaBridge.jar

The Javabridge code allows for either side to initiate the connection - i.e. it can be run in server mode,
where it awaits an incoming connection, or in client mode, where it actively initiates a connection.
After connection establishment, there is no difference in the operation of the bridge, however depending on the setup of your network infrastructure, especially firewalls, either mechanism may be easier to be used.

Assuming that the bridge is already running on the remote machine as server (default),
use <CODE>newConnectedTo:port:withTimeout:</CODE> to connect to it from the expecco side:
java := JAVA::Java newConnectedTo:'myHost' port:4567 withTimeout:30.
This will initiate the connection setup from the expecco side.

Alternatively, if started in client mode use <CODE>newWaitingForConnectOnHost:port:withTimeout:</CODE>:
java := JAVA::Java newWaitingForConnectOnHost:'localhost' port:4567 withTimeout:30.
which will open a port on the expecco side, and wait until the Java side connects to it.
[[#JAVA::Java|For more details see API]]

====Startup Parameters====
You can use any parameter in any order.
If no parameter is used then the bridge listenes on port 14014 in server mode without keepAlive.
;<code>-help</code>
* Shows the help

;<code>-ip <aHostnameOrIP></code>
* In client mode this specifies the ip or hostname to connect to. In server mode this specifies the ip or hostname to bind to.

;<code>-port <aPortNumber> </code>
* In client mode this specifies the port to connect to. In server mode this specifies the listening port.

;<code>-asClient</code>
* The bridge will start in client mode. If not set the bridge is started in server mode.

;<code>-keepAlive</code>
* By setting this flag the bridge will not exit after the connection has closed and starts to connect or listen again. Otherwise, it will run for a single connection session only.

== Loading Applications (from the expecco side) ==

Normally, you would start your application with the required command line arguments and include the javabridge as jar there. However, in some situations, it may be required to dynamically load other jars into the connected Java VM.
By accessing a classloader, additional classes, or applications as contained in JAR files can be loaded from the expecco side.

This can be used to add a JAR file to the classloader:
<CODE><PRE>
java loadJarByPath:'pathToJarFile'. "/ assuming "java" is a handle as returned from the above connect
</PRE></CODE>

or, if the JAR file is loaded in memory:
<CODE><PRE>
java loadJar:jarByteArray. "/ where "jarByteArray" is a ByteArray containing the JAR file
</PRE></CODE>

If the JVM is on a remote machine, the path is resolved on the expecco side and the JAR will be transferred to the remote side.

Should transferring the JAR be too much overhead, an additional mechanism is provided:
<CODE><PRE>
java loadExtension:'pathToJarFile'.
</PRE></CODE>
this will cache the JAR file on the bridge side and eliminate the overhead of subsequent invocations.

== Java Class Access ==

This following code sample simply references (i.e. accesses) the class "JFrame" from the <CODE>"javax.swing"</CODE> package. The fully specified class name in Java would be <CODE>"javax.swing.JFrame"</CODE>:
<CODE><PRE>
java getJavaClass:'javax.swing.JFrame'
</PRE></CODE>

Or, if you want to load multiple classes:
<CODE><PRE>
java import:'javax.swing.JFrame' import:'javax.swing.JButton'
do:[:jFrame :jButton | "do something with JButton and JFrame" ].
</PRE></CODE>

v2 also supports dynamic compilation of java source code:
<CODE><PRE>
java getJavaClass:'className' fromSource:'classSource'. "/ where classSource is a String containing valid java source code
</PRE></CODE>

and loading precompiled java bytecode:
<CODE><PRE>
java getJavaClass:'className' fromByteCode:byteCode. "/ where byteCode is a ByteArray containing valid java bytecode
</PRE></CODE>

[[#Remote Dynamic Code Injection | for details see Remote Dynamic Code Injection]]

== Instantiating a Class ==

Object instances are created via the "new"-message, sent to a proxy of a Java class. You can get this proxy as described in the previous section. For example, if we want to create a new instance of a "JFrame" and a "JButton", write:
<CODE><PRE>
frame := java getJavaClass:'javax.swing.JFrame' new.
button := java getJavaClass:'javax.swing.JButton' new.
</PRE></CODE>
The first statement results in a proxy object for the "JFrame" instance. The second line results in a proxy for a new "JButton" object.

== Calling Instance Methods ==

A method call is done by a message send to a proxy object, where the message is the method name to call. For example, to call the <CODE>"setVisible(boolean isVisible)"</CODE> method on the above JFrame object, we send the following message to that proxy:
<CODE><PRE>
frame setVisible:true.
</PRE></CODE>

As method naming is different in Smalltalk and Java, a dynamic translation is applied when sending messages from Smalltalk code to a remote Java object. Smalltalk has arguments embedded inside parts of a so called "keyword" message, such as in "receiver foo:arg1 bar:arg2", where "foo:bar:" would be the message name, and "arg1", "arg2" be the arguments.

In Java, the message name is a single identifier, and arguments are written in an argument list after the message name: "receiver.fooBar(arg1, arg2)".

When message names are translated, only the very first part of the Smalltalk keyword message is taken ("foo" in the above example), and the remaining parts are simpl ignored. Thus, any of the Smalltalk messages "foo:bar:", "foo:xxxx:" and "foo:_:" (a single underscore as second part) all translate to the same Java message name "foo()".

Therefore, to call a method with more than one argument, like <CODE>"setSize(int width,int height)"</CODE> on a JFrame instance we can write:
<CODE><PRE>
frame setSize:300 _:200.
</PRE></CODE>
but just as well:
<CODE><PRE>
frame setSize:300 anyWord:200.
</PRE></CODE>
or any other selector with "setSize:" as its first component.
The selector translation mechanism simply takes the first part as the Java selector.

In practice, you should take a reasonably descriptive name, such as: "frame setSize:300 height:200" or only the Java name as first part, such as "frame setSize:300 _:200".

For a call of a method with 4 arguments, we could write:
<CODE><PRE>
frame setBounds:100 y:50 width:300 height:200.
</PRE></CODE>
or:
<CODE><PRE>
frame setBounds:100 _:50 _:300 _:200.
</PRE></CODE>

Also here the <CODE>"y: width: height:"</CODE> can be named as you want, but the first part must be "setBounds:".

=== Calling Static Methods ===

Calling a static method on an object is not different from calling non static methods. In most cases you will call a static method not on an object but directly on the class. This is done by using the class object as "receiver" of the message. For example, if we want to call the static method <CODE>"isDefaultLookAndFeelDecorated()"</CODE> of the JFrame class, write:
<CODE><PRE>
java getJavaClass:'javax.swing.JFrame' isDefaultLookAndFeelDecorated.
</PRE></CODE>

== Accessing Fields ==

As Smalltalk does not support access of an object's fields from the outside (it is fully encapsulated, and access from outside is ONLY allowed via getters/setters), an additional translation mechanism is provided for field access.

Accessing a field of a Java object or a class's static field uses the same syntax as method calls. To access a field, send a message where the message is the field name. To access the field of a class the field must be static.
For example, to get the value of the static field named <CODE>"EXIT_ON_CLOSE"</CODE> of the "JFrame" class, write
<CODE><PRE>
value := java getJavaClass:'javax.swing.JFrame' EXIT_ON_CLOSE.
</PRE></CODE>
The variable "value" now holds the integer value of the <CODE>"EXIT_ON_CLOSE"</CODE> constant.

Assuming that a "JFrame" object had a field named <CODE>"myField"</CODE>, to access this field, we'd have to write:
<CODE><PRE>
value := frame myField.
</PRE></CODE>
and "value" now holding whatever <CODE>"myField"</CODE> returns. This could be another object reference or any primitive value.

=== Setting Fields ===
To set a field, use a setter-like method call:
<CODE><PRE>
frame myField: newValue.
</PRE></CODE>

=== Name Conflicts ===

In very rare situations, a Java object may contain both a field and a method by the same name.
In this case, the Smalltalk code cannot depend on the dynamic translation mechanism (which actually looks for either a field or method name to match), but instead make it explicit, which operation is wanted:
Use:
<CODE><PRE>
frame getFieldByName:'myField'
</PRE></CODE>
to read a field, and:
<CODE><PRE>
frame setFieldByName:'myField' value:123.
</PRE></CODE>
to write the field.

If there are both fields and methods by the same name, and you use the non-explicit call,
the bridge will always assume that you want to call the getter/setter and perform a method call.
 

== Callbacks from Java ==
Sometimes you may want to execute a piece of Smalltalk code during the execution of the Java code. For example, we may want to install a Smalltalk observer to be notified when a button on a Java GUI was pressed,
or some other callback from a Java framework.

The following code registers a Smalltalk block as a callback for a mouse press event of a button:
<CODE><PRE>
listener := MouseListener new.
listener implementMethod:'mousePressed' as:[ Transcript showCR:'Hello from Java' ].
</PRE></CODE>
The above creates the callback and the listener, which can now be registered on a button:
<CODE><PRE>
button addMouseListener:listener.
</PRE></CODE>
Now, with the press of the button in the Java GUI, the Smalltalk block will be executed and writes <CODE>"Hello from Java"</CODE> to the Smalltalk console.
Of course, any other (Smalltalk-)action code can be made to run via this mechanism.

But be aware, that the callback is possibly called later (when the elementary action, which installed the code, has already finished long ago). Also, as the Java code execution is not synchronized with any of your expecco action execution, the callback may also be called at any arbutrary time, even at times when no activity at all is executed on the expecco side. If you forget to cleanup, and the Java object is still alive, it may even be called after you have finished your test run (if you keep the java bridge handle around and alive, for example in an expecoo environment variable).

So the Smalltalk callback code should not depend on any particular elementary action to be currently running, but instead in most cases write some information into a shared data container, preferably an instance of "SharedQueue", which is thread safe. Then, some other action (an elementary action) would read-wait and read events from that shared queue.

make sure that your test correctly cleans up any such callbacks afterwards. As a last resort, use the "Shutdown Bridge Connection" menu item, which closes the bridge connection, and thereby - as a side effect - removes any leftover callbacks. It does close the connection, and any remaining java proxy object handles become invalid, though.

Another example, using an observer could look like:
<CODE><PRE>
observer := java Observer new.
observer implementMethod:'update'
as:[:sourceObservable :argument|
argument notNil ifTrue:[ Transcript showCR:('I was notifyed with: ',argument toString) ]
ifFalse:[ Transcript showCR:'I was notifyed and the argument was nil' ].
].
myObservable addObserver:observer.
</PRE></CODE>
When the observable calls <CODE>"notifyObservers"</CODE>, the Smalltalk block will be executed.

== Exceptions in Java ==
Exceptions on the Java side are signalled back to the Smalltalk side and raise a corresponding exception there. However, on the Java side, the call stack which lead to the exception has already been unwound at that time (Java exceptions are not proceedable). So a proceed in the Smalltalk-side exception handler only affects the Smalltalk caller, but may leave the Java side in an undefined state.

== Remote Dynamic Code Injection ==
Sometimes we might want to execute code without the overhead of many rpc-messages being sent over the bridge, especially if we want to do something time critical, or want to make execution time measurements.
For this, it is possible to load a class at runtime into the JavaVM. The code of the class will first be sent to the JavaVM, which will compile and load the generated byte code. Then, the class can be accessed via the bridge just like any other preloaded class.

The following example specifies the class code in a smalltalk string and inject the code into the JavaVM. Then an instance of that new class will be instantiated and finally a method of the object instance will be invoked:
<CODE><PRE>
classCode := '
package myPackage.test;

import java.awt.BorderLayout;
import java.awt.event.MouseAdapter;
import java.awt.event.MouseEvent;
import java.util.Calendar;

import javax.swing.JButton;
import javax.swing.JFrame;
import javax.swing.JLabel;;

public class MyInjectedClass {
public void createSampleApp(){
JFrame frame=new JFrame("Hello im injected");
frame.setLayout(new BorderLayout());
JButton button=new JButton("click me");
final JLabel label=new JLabel("Text");
button.addMouseListener(new MouseAdapter() {

@Override
public void mouseClicked(MouseEvent e) {
label.setText(Calendar.getInstance().getTime().toString());
}
});
frame.add(label,BorderLayout.NORTH);
frame.add(button,BorderLayout.SOUTH);
frame.setSize(300, 300);
frame.setVisible(true);
}
}
'.
classObject := java getJavaClass:'myPackage.test.MyInjectedClass' fromSource:classCode.
classObject new createSampleApp.
</PRE></CODE>
After the code has been injected, a new instance of <CODE>"MyInjectedClass"</CODE> is created and the <CODE>"createSampleApp"</CODE> method is called. Because the example implements a GUI, a Java window will open, containing a label and a button. Clicking the button displays the current time in the label.



=== Code Sources for Class injection ===
There are 3 possible types of class code sources which we can use to inject the code. In the examples before we directly used a simple <CODE>"String"</CODE> in the smalltalk code as a code source. We also can use a <CODE>"*.java"</CODE> file as source. Just read the content of the file into a string and use it as in the previous examples.

To inject a <CODE>"*.class"</CODE> file use the following code:
<pre>
java getJavaClass:'the.class.name' fromByteCode:classCode.
</pre>

== Examples ==

This example creates a JFrame with one button inside. Then a Mouselistener is created and registered on the button. When the button is pressed, the title of the window changes to <CODE>"onPressed"</CODE> and the Transcript shows the message <CODE>"onPressed"</CODE>. When the button is released, the title of the window is changed to <CODE>"onReleased"</CODE> and the Transcript shows <CODE>"onReleased"</CODE>. If the button lost the mouse focus, the bridge will exit (disconnect), and the Java side is terminated.
<CODE><PRE>
|java frame button listener|

"/getting a bridge
java := JAVA::JavaBridge newWithServer.

"/creating a new frame and button object
frame := java getJavaClass:'javax.swing.JFrame' new.
button := java JButton new:'Click'.

"/creating a new mouse listener and adding callback blocks
listener := java MouseListener new.

listener implementMethod:'mousePressed' as:[ Transcript showCR:'onPress'. frame setTitle:'onPressed' ].
listener implementMethod:'mouseReleased' as:[ Transcript showCR:'onReleased'. frame setTitle:'onReleased' ].
listener implementMethod:'mouseExited' as:[ Transcript showCR:'onExited'. java closeBridge. ].

"/register the mouse listener on the button and make the frame with button visible
button addMouseListener:listener.
frame add:button.
frame setSize:300 y:100.
frame setVisible: true.
</PRE></CODE>



==Differences between v1 and v2==
===General===
* A Java Bridge instance no longer requires multiple tcp ports to be open. This simplifies connection through ssh tunnels and firewalls.
* The identity of strings and primitve wrappers can be preserved.
* Arrays of primitive types are serialized.

===Loading Applications===
* '''addJarByPath:''' and '''addToClassPath:''' are still supported but have been deprecated. use '''loadJar:''', '''loadJarByPath:''' and '''loadExtension:''' instead. The new methods no longer require the jar or library to be present on the remote machine.

[[Java Interface Library#Loading Applications (from the expecco side) | v1]] [[#Loading Applications (from the expecco side) | v2]]

===Java Class Access===
* Sending the fully qualified name with instances of "." replaced by "_" to the bridge handle is still supported, but not recommended.
* A new method '''getJavaClass:''' has been introduced (also available for v1 since expecco v2.9). This solves the side effects of "_" being a legal character in class names.

[[Java Interface Library#Java Package Import and Class Access | v1]] [[#Java Class Access | v2]]
===Callbacks from Java===
* A new method '''implementMethod:as:''' has been introduced to assign callback blocks to method names. The old way is still supported.

[[Java Interface Library#Callbacks from Java | v1]] [[#Callbacks from Java | v2]]

===Remote Dynamic Code Injection===
* Code injection was problematic in v1 and has now been re-implemented in v2.

[[#Remote Dynamic Code Injection | v2]]

== API ==
===JAVA::Java===
====class protocol====
=====newWithServer=====
* This will start a local JavaVM, running the JavaBridge, and establishes a connection on a random free port.
: A new connected instance of JAVA::Java class is returned.

=====newWithServerForJavaPath:aJavaPathFilename=====
* This is the same as newWithServer but the path to the java executable can be specified. The JavaVM version must be 1.6 or higher to run the JavaBridge.
:: '''aJavaPathFilename''' - must be a instance of Filename
Smalltalk: JAVA::Java newWithServerForJavaPath:('my\path\to\java.executable'asFilename).
JavaScript: JAVA::Java.newWithServerForJavaPath("my\path\to\java.executable".asFilename());

=====newConnectedTo:aHhostString port:aPortNumber withTimeout:aTimeoutSeconds=====
* This is used to connect to a running JavaBridge on the network. The JavaBridge must be started in server mode on the remote host. After connecting a new connected instance of JAVA::Java is returned.
:: '''aHostString''' - the hostname or IP of the remote machine as String
:: '''aPortNumber ''' - the port on which the remote machine is listening as Number
:: '''aTimeoutSeconds''' - a connect timeout in seconds as Number
Smalltalk: JAVA::Java newConnectedTo:'myHostName' port:4567 withTimeout:30.
JavaScript: JAVA::Java.newConnectedTo_port_withTimeout("myHostName",4567,30);

=====newWaitingForConnectOnHost:aListeningAddressString port:aListeningPortNumber withTimeout:aTimeoutSeconds=====
* This is used to wait for incomming connecions of a running JavaBridge on the network. The JavaBridge must be started in client mode on the remote host. After connecting a new connected instance of JAVA::Java is returned.
:: '''deprecated: aListeningAddressString''' - no longer used. Can be nil.
:: '''aListeningPortNumber ''' - the port on which to listen for incomming connections as Number
:: '''aTimeoutSeconds''' - a connect timeout in seconds as Number, If nil it will wait endless.

=====singletonInstance=====
* This will call newWithServer for the first time and then always returns the same connected JAVA::Java instance until the connection was closed, then a new connected instance is returned.

=====exitAllInstances=====
* This will close all instances of JAVA::Java.

====instance protocol====
=====loadJarByPath:aPath=====
* Adds a jar to the running JavaVM. If the jar depends on other jars or libraries you have to add them too.
:: '''aPath''' - the path to the jar file as String.

=====loadJar:aByteArray=====
* Adds a jar to the running JavaVM. If the jar depends on other jars or libraries you have to add them too.
:: '''aByteArrays''' - a ByteArray containing the JAR file.

=====loadExtension:aPath=====
* Adds a jar to the running JavaVM and caches it for subsequent usages. If the jar depends on other jars you have to add them too.
:: '''aPath''' - the path to the jar file as String.

=====boxedDo:aBlock=====
* Any autoboxed values in aBlock returned from the JavaVM are preserved as such. By default autoboxed values are automatically unboxed. This way, the identity of such objects is preserved.

=====isConnected=====
* Tests if a connection is still established.
:: '''return:''' - true if the connection is still established, else false.

=====isAlive=====
* Tests if a connection is still responding.
:: '''return:''' - true if the connection is still alive, else false. Does a message round trip.

=====closeBridge=====
* This will close the bridge connection. Depending on in which mode the JavaBridge was started, the JavaVM is also closed (-keepAlive startparameter not set).

=====exit=====
* Same as closeBridge.

== See Also==
The [[DOT NET Interface Library| DOTNET Interface Plugin & Library]], which implements a likewise interface for .NET applications/libraries.

<hr>
Back to [[Plugins]]

Java Interface Library v2

2016-05-31T16:06:08Z

Javogel: /* General */

== Introduction ==

This article discusses version 2 of the Java Bridge (which is as of expecco v2.9 still experimental).
The article for version 1 can be found [[Java Interface Library | here]].

The Java Interface library ("Java Bridge") is used to interact with Java objects inside an external Java Virtual Machine (JVM).

The access to Java objects, classes and programs is done via a framework called "''Java-Bridge''", which is similar in operation to the [[DOT NET Interface Library| dotNET bridge]]. This framework implements transparent forwarding of method (virtual function) calls to Java objects, which exist in a local or remote Java Virtual Machine (JVM). Also, return values, callBacks and exception information are passed back from the Java program to expecco. This is done by a proxy-object mechanism, which catches all function calls, wraps the arguments, sends a datagram to the other bridge side, awaits the reply and returns the result to the original caller. Thus, remote procedure calls are almost completely transparent to the Smalltalk/JavaScript code inside expecco. In your elementary code, you can write remote function calls as if they were to local objects.

Notice that this document describes the low level framework, which implements the bridge communication. A much easier to use high level interface (called "Groovy Blocks") exists and should normally be used, if you need access to a java application's internals during testing.
Please take a look at
[[Expecco_API#Groovy_Elementary_Blocks | "Groovy Block API"]]
and [[Testing Java Applications using Groovy blocks/en | "Testing Java Applications using Groovy blocks"]].

== Architecture ==

On the expecco side, the bridge consists of a number of Proxy objects,
which behave like regular Smalltalk objects as seen from elementary expecco code.
However, instead of performing an action when one of their methods (virtual functions) is called,
they send a message over a socket connection to the Java VM (actually: to a bridge software inside the
Java application) which decodes the message and sends it to the destination Java object.
The same is done in reverse direction with the return value.

+---------------------+ +----------+ +----------------+ +----------------+ +---------+
| | | | | | | | | Java |
| expecco |---->| Proxy |---->| Bridge |==>>==| Bridge |---->| Object |
| (elementary code) |<----| |<----| (expecco side) |==<<==| (Java side) |<----| |
+---------------------+ +----------+ +----------------+ +----------------+ +---------+

This setup allows for transparent communication with objects inside a local or remote Java VM. This may be either utility functions which happen to be convenient for the test application (for example: file parsing, syntax analysis, protocol implementaitons or access to specific hardware via driver libraries), or the tested application in the system under test itself.

Especially, it allows for the objects of the tested application to be looked into, manipulated and for functions of it or underlying frameworks to be called.

For expecco code, we tried to make this as transparent as possible, however there are a few exceptions, when function names need to be translated (for example, because the function naming syntax is different) or due to the fact that for some operations no corresponding name exists in Smalltalk (array access, for example).

Of course, multiple such connections can coexist and be served/handled in parallel. This enables an expecco test suite to communicate with both sides of a tested client-server Java application, for example.

Notice that a similar mechanism is used in expecco to communicate with DOTNET, Qt (C++) and C applications.

 

== Initializing / Releasing the Bridge ==

Before any communication can take place between expecco and any Java object, the Java side of the bridge has to be started, and a communication has to be established.
In expecco, all of the bridge classes are found in the <CODE>JAVA</CODE> namespace.

The main interface class is "<CODE>Java</CODE>", in the "<CODE>JAVA</CODE>" namespace:
<CODE><PRE>
java := JAVA::Java newWithServer.
</PRE></CODE>
or (in JavaScript):
<CODE><PRE>
java = JAVA::Java.newWithServer();
</PRE></CODE>

This starts the Java-side of the bridge (actually executes java as a background command) on the local machine, and establishes a connection to that JVM.

The bridge connection should be closed, if the bridge is no longer needed. Release the bridge with:
<CODE><PRE>
java.closeBridge();
</PRE></CODE>
which terminates the connection.

=== Start and Connect to a Remote Machine ===
The above started a Java VM and connected to it. Alternatively, you may want to connect to an already running Java program (typically, your system under test).
In order for your program to be reachable, it must allow for the bridge to connect to it via a special bridge-connection, which is a socket connection. For this, it must execute the server code found in the "JavaBridge.jar" file. To pass [[#Startup Parameters| parameters]] you will typically start it from a command line or a little shell/batch script.

Call (on the shell/cmd level):
$ java -jar <PATH_TO_JAVABRIDGE.JAR> <PARAMETERS>

The "JavaBridge.jar" file is found in the installation directory of expecco at:
\exept\expecco\packages\exept\bridgeFramework\javaBridge\javaBin\JavaBridge.jar

The Javabridge code allows for either side to initiate the connection - i.e. it can be run in server mode,
where it awaits an incoming connection, or in client mode, where it actively initiates a connection.
After connection establishment, there is no difference in the operation of the bridge, however depending on the setup of your network infrastructure, especially firewalls, either mechanism may be easier to be used.

Assuming that the bridge is already running on the remote machine as server (default),
use <CODE>newConnectedTo:port:withTimeout:</CODE> to connect to it from the expecco side:
java := JAVA::Java newConnectedTo:'myHost' port:4567 withTimeout:30.
This will initiate the connection setup from the expecco side.

Alternatively, if started in client mode use <CODE>newWaitingForConnectOnHost:port:withTimeout:</CODE>:
java := JAVA::Java newWaitingForConnectOnHost:'localhost' port:4567 withTimeout:30.
which will open a port on the expecco side, and wait until the Java side connects to it.
[[#JAVA::Java|For more details see API]]

====Startup Parameters====
You can use any parameter in any order.
If no parameter is used then the bridge listenes on port 14014 in server mode without keepAlive.
;<code>-help</code>
* Shows the help

;<code>-ip <aHostnameOrIP></code>
* In client mode this specifies the ip or hostname to connect to. In server mode this specifies the ip or hostname to bind to.

;<code>-port <aPortNumber> </code>
* In client mode this specifies the port to connect to. In server mode this specifies the listening port.

;<code>-asClient</code>
* The bridge will start in client mode. If not set the bridge is started in server mode.

;<code>-keepAlive</code>
* By setting this flag the bridge will not exit after the connection has closed and starts to connect or listen again. Otherwise, it will run for a single connection session only.

== Loading Applications (from the expecco side) ==

Normally, you would start your application with the required command line arguments and include the javabridge as jar there. However, in some situations, it may be required to dynamically load other jars into the connected Java VM.
By accessing a classloader, additional classes, or applications as contained in JAR files can be loaded from the expecco side.

This can be used to add a JAR file to the classloader:
<CODE><PRE>
java loadJarByPath:'pathToJarFile'. "/ assuming "java" is a handle as returned from the above connect
</PRE></CODE>

or, if the JAR file is loaded in memory:
<CODE><PRE>
java loadJar:jarByteArray. "/ where "jarByteArray" is a ByteArray containing the JAR file
</PRE></CODE>

If the JVM is on a remote machine, the path is resolved on the expecco side and the JAR will be transferred to the remote side.

Should transferring the JAR be too much overhead, an additional mechanism is provided:
<CODE><PRE>
java loadExtension:'pathToJarFile'.
</PRE></CODE>
this will cache the JAR file on the bridge side and eliminate the overhead of subsequent invocations.

== Java Class Access ==

This following code sample simply references (i.e. accesses) the class "JFrame" from the <CODE>"javax.swing"</CODE> package. The fully specified class name in Java would be <CODE>"javax.swing.JFrame"</CODE>:
<CODE><PRE>
java getJavaClass:'javax.swing.JFrame'
</PRE></CODE>

Or, if you want to load multiple classes:
<CODE><PRE>
java import:'javax.swing.JFrame' import:'javax.swing.JButton'
do:[:jFrame :jButton | "do something with JButton and JFrame" ].
</PRE></CODE>

v2 also supports dynamic compilation of java source code:
<CODE><PRE>
java getJavaClass:'className' fromSource:'classSource'. "/ where classSource is a String containing valid java source code
</PRE></CODE>

and loading precompiled java bytecode:
<CODE><PRE>
java getJavaClass:'className' fromByteCode:byteCode. "/ where byteCode is a ByteArray containing valid java bytecode
</PRE></CODE>

[[#Remote Dynamic Code Injection | for details see Remote Dynamic Code Injection]]

== Instantiating a Class ==

Object instances are created via the "new"-message, sent to a proxy of a Java class. You can get this proxy as described in the previous section. For example, if we want to create a new instance of a "JFrame" and a "JButton", write:
<CODE><PRE>
frame := java getJavaClass:'javax.swing.JFrame' new.
button := java getJavaClass:'javax.swing.JButton' new.
</PRE></CODE>
The first statement results in a proxy object for the "JFrame" instance. The second line results in a proxy for a new "JButton" object.

== Calling Instance Methods ==

A method call is done by a message send to a proxy object, where the message is the method name to call. For example, to call the <CODE>"setVisible(boolean isVisible)"</CODE> method on the above JFrame object, we send the following message to that proxy:
<CODE><PRE>
frame setVisible:true.
</PRE></CODE>

As method naming is different in Smalltalk and Java, a dynamic translation is applied when sending messages from Smalltalk code to a remote Java object. Smalltalk has arguments embedded inside parts of a so called "keyword" message, such as in "receiver foo:arg1 bar:arg2", where "foo:bar:" would be the message name, and "arg1", "arg2" be the arguments.

In Java, the message name is a single identifier, and arguments are written in an argument list after the message name: "receiver.fooBar(arg1, arg2)".

When message names are translated, only the very first part of the Smalltalk keyword message is taken ("foo" in the above example), and the remaining parts are simpl ignored. Thus, any of the Smalltalk messages "foo:bar:", "foo:xxxx:" and "foo:_:" (a single underscore as second part) all translate to the same Java message name "foo()".

Therefore, to call a method with more than one argument, like <CODE>"setSize(int width,int height)"</CODE> on a JFrame instance we can write:
<CODE><PRE>
frame setSize:300 _:200.
</PRE></CODE>
but just as well:
<CODE><PRE>
frame setSize:300 anyWord:200.
</PRE></CODE>
or any other selector with "setSize:" as its first component.
The selector translation mechanism simply takes the first part as the Java selector.

In practice, you should take a reasonably descriptive name, such as: "frame setSize:300 height:200" or only the Java name as first part, such as "frame setSize:300 _:200".

For a call of a method with 4 arguments, we could write:
<CODE><PRE>
frame setBounds:100 y:50 width:300 height:200.
</PRE></CODE>
or:
<CODE><PRE>
frame setBounds:100 _:50 _:300 _:200.
</PRE></CODE>

Also here the <CODE>"y: width: height:"</CODE> can be named as you want, but the first part must be "setBounds:".

=== Calling Static Methods ===

Calling a static method on an object is not different from calling non static methods. In most cases you will call a static method not on an object but directly on the class. This is done by using the class object as "receiver" of the message. For example, if we want to call the static method <CODE>"isDefaultLookAndFeelDecorated()"</CODE> of the JFrame class, write:
<CODE><PRE>
java getJavaClass:'javax.swing.JFrame' isDefaultLookAndFeelDecorated.
</PRE></CODE>

== Accessing Fields ==

As Smalltalk does not support access of an object's fields from the outside (it is fully encapsulated, and access from outside is ONLY allowed via getters/setters), an additional translation mechanism is provided for field access.

Accessing a field of a Java object or a class's static field uses the same syntax as method calls. To access a field, send a message where the message is the field name. To access the field of a class the field must be static.
For example, to get the value of the static field named <CODE>"EXIT_ON_CLOSE"</CODE> of the "JFrame" class, write
<CODE><PRE>
value := java getJavaClass:'javax.swing.JFrame' EXIT_ON_CLOSE.
</PRE></CODE>
The variable "value" now holds the integer value of the <CODE>"EXIT_ON_CLOSE"</CODE> constant.

Assuming that a "JFrame" object had a field named <CODE>"myField"</CODE>, to access this field, we'd have to write:
<CODE><PRE>
value := frame myField.
</PRE></CODE>
and "value" now holding whatever <CODE>"myField"</CODE> returns. This could be another object reference or any primitive value.

=== Setting Fields ===
To set a field, use a setter-like method call:
<CODE><PRE>
frame myField: newValue.
</PRE></CODE>

=== Name Conflicts ===

In very rare situations, a Java object may contain both a field and a method by the same name.
In this case, the Smalltalk code cannot depend on the dynamic translation mechanism (which actually looks for either a field or method name to match), but instead make it explicit, which operation is wanted:
Use:
<CODE><PRE>
frame getFieldByName:'myField'
</PRE></CODE>
to read a field, and:
<CODE><PRE>
frame setFieldByName:'myField' value:123.
</PRE></CODE>
to write the field.

If there are both fields and methods by the same name, and you use the non-explicit call,
the bridge will always assume that you want to call the getter/setter and perform a method call.
 

== Callbacks from Java ==
Sometimes you may want to execute a piece of Smalltalk code during the execution of the Java code. For example, we may want to install a Smalltalk observer to be notified when a button on a Java GUI was pressed,
or some other callback from a Java framework.

The following code registers a Smalltalk block as a callback for a mouse press event of a button:
<CODE><PRE>
listener := MouseListener new.
listener implementMethod:'mousePressed' as:[ Transcript showCR:'Hello from Java' ].
</PRE></CODE>
The above creates the callback and the listener, which can now be registered on a button:
<CODE><PRE>
button addMouseListener:listener.
</PRE></CODE>
Now, with the press of the button in the Java GUI, the Smalltalk block will be executed and writes <CODE>"Hello from Java"</CODE> to the Smalltalk console.
Of course, any other (Smalltalk-)action code can be made to run via this mechanism.

But be aware, that the callback is possibly called later (when the elementary action, which installed the code, has already finished long ago). Also, as the Java code execution is not synchronized with any of your expecco action execution, the callback may also be called at any arbutrary time, even at times when no activity at all is executed on the expecco side. If you forget to cleanup, and the Java object is still alive, it may even be called after you have finished your test run (if you keep the java bridge handle around and alive, for example in an expecoo environment variable).

So the Smalltalk callback code should not depend on any particular elementary action to be currently running, but instead in most cases write some information into a shared data container, preferably an instance of "SharedQueue", which is thread safe. Then, some other action (an elementary action) would read-wait and read events from that shared queue.

make sure that your test correctly cleans up any such callbacks afterwards. As a last resort, use the "Shutdown Bridge Connection" menu item, which closes the bridge connection, and thereby - as a side effect - removes any leftover callbacks. It does close the connection, and any remaining java proxy object handles become invalid, though.

Another example, using an observer could look like:
<CODE><PRE>
observer := java Observer new.
observer implementMethod:'update'
as:[:sourceObservable :argument|
argument notNil ifTrue:[ Transcript showCR:('I was notifyed with: ',argument toString) ]
ifFalse:[ Transcript showCR:'I was notifyed and the argument was nil' ].
].
myObservable addObserver:observer.
</PRE></CODE>
When the observable calls <CODE>"notifyObservers"</CODE>, the Smalltalk block will be executed.

== Exceptions in Java ==
Exceptions on the Java side are signalled back to the Smalltalk side and raise a corresponding exception there. However, on the Java side, the call stack which lead to the exception has already been unwound at that time (Java exceptions are not proceedable). So a proceed in the Smalltalk-side exception handler only affects the Smalltalk caller, but may leave the Java side in an undefined state.

== Remote Dynamic Code Injection ==
Sometimes we might want to execute code without the overhead of many rpc-messages being sent over the bridge, especially if we want to do something time critical, or want to make execution time measurements.
For this, it is possible to load a class at runtime into the JavaVM. The code of the class will first be sent to the JavaVM, which will compile and load the generated byte code. Then, the class can be accessed via the bridge just like any other preloaded class.

The following example specifies the class code in a smalltalk string and inject the code into the JavaVM. Then an instance of that new class will be instantiated and finally a method of the object instance will be invoked:
<CODE><PRE>
classCode := '
package myPackage.test;

import java.awt.BorderLayout;
import java.awt.event.MouseAdapter;
import java.awt.event.MouseEvent;
import java.util.Calendar;

import javax.swing.JButton;
import javax.swing.JFrame;
import javax.swing.JLabel;;

public class MyInjectedClass {
public void createSampleApp(){
JFrame frame=new JFrame("Hello im injected");
frame.setLayout(new BorderLayout());
JButton button=new JButton("click me");
final JLabel label=new JLabel("Text");
button.addMouseListener(new MouseAdapter() {

@Override
public void mouseClicked(MouseEvent e) {
label.setText(Calendar.getInstance().getTime().toString());
}
});
frame.add(label,BorderLayout.NORTH);
frame.add(button,BorderLayout.SOUTH);
frame.setSize(300, 300);
frame.setVisible(true);
}
}
'.
classObject := java getJavaClass:'myPackage.test.MyInjectedClass' fromSource:classCode.
classObject new createSampleApp.
</PRE></CODE>
After the code has been injected, a new instance of <CODE>"MyInjectedClass"</CODE> is created and the <CODE>"createSampleApp"</CODE> method is called. Because the example implements a GUI, a Java window will open, containing a label and a button. Clicking the button displays the current time in the label.



=== Code Sources for Class injection ===
There are 3 possible types of class code sources which we can use to inject the code. In the examples before we directly used a simple <CODE>"String"</CODE> in the smalltalk code as a code source. We also can use a <CODE>"*.java"</CODE> file as source. Just read the content of the file into a string and use it as in the previous examples.

To inject a <CODE>"*.class"</CODE> file use the following code:
<pre>
java getJavaClass:'the.class.name' fromByteCode:classCode.
</pre>

== Examples ==

This example creates a JFrame with one button inside. Then a Mouselistener is created and registered on the button. When the button is pressed, the title of the window changes to <CODE>"onPressed"</CODE> and the Transcript shows the message <CODE>"onPressed"</CODE>. When the button is released, the title of the window is changed to <CODE>"onReleased"</CODE> and the Transcript shows <CODE>"onReleased"</CODE>. If the button lost the mouse focus, the bridge will exit (disconnect), and the Java side is terminated.
<CODE><PRE>
|java frame button listener|

"/getting a bridge
java := JAVA::JavaBridge newWithServer.

"/creating a new frame and button object
frame := java getJavaClass:'javax.swing.JFrame' new.
button := java JButton new:'Click'.

"/creating a new mouse listener and adding callback blocks
listener := java MouseListener new.

listener implementMethod:'mousePressed' as:[ Transcript showCR:'onPress'. frame setTitle:'onPressed' ].
listener implementMethod:'mouseReleased' as:[ Transcript showCR:'onReleased'. frame setTitle:'onReleased' ].
listener implementMethod:'mouseExited' as:[ Transcript showCR:'onExited'. java closeBridge. ].

"/register the mouse listener on the button and make the frame with button visible
button addMouseListener:listener.
frame add:button.
frame setSize:300 y:100.
frame setVisible: true.
</PRE></CODE>



==Differences between v1 and v2==
===General===
* A Java Bridge instance no longer requires multiple tcp ports to be open. This simplifies connection through ssh tunnels and firewalls.
* The identity of strings and primitve wrappers can be preserved.
* Arrays of primitive types are serialized.

===Loading Applications===
* '''addJarByPath:''' and '''addToClassPath:''' are still supported but have been deprecated. use '''loadJar:''', '''loadJarByPath:''' and '''loadExtension:''' instead. The new methods no longer require the jar or library to be present on the remote machine.

[[Java Interface Library#Loading Applications (from the expecco side) | v1]] [[#Loading Applications (from the expecco side) | v2]]

===Java Class Access===
* Sending the fully qualified name with instances of "." replaced by "_" to the bridge handle is still supported, but not recommended.
* A new method '''getJavaClass:''' has been introduced. This solves the side effects of "_" being a legal character in class names.

[[Java Interface Library#Java Package Import and Class Access | v1]] [[#Java Class Access | v2]]
===Callbacks from Java===
* A new method '''implementMethod:as:''' has been introduced to assign callback blocks to method names. The old way is still supported.

[[Java Interface Library#Callbacks from Java | v1]] [[#Callbacks from Java | v2]]

===Remote Dynamic Code Injection===
* Code injection was problematic in v1 and has now been re-implemented in v2.

[[#Remote Dynamic Code Injection | v2]]

== API ==
===JAVA::Java===
====class protocol====
=====newWithServer=====
* This will start a local JavaVM, running the JavaBridge, and establishes a connection on a random free port.
: A new connected instance of JAVA::Java class is returned.

=====newWithServerForJavaPath:aJavaPathFilename=====
* This is the same as newWithServer but the path to the java executable can be specified. The JavaVM version must be 1.6 or higher to run the JavaBridge.
:: '''aJavaPathFilename''' - must be a instance of Filename
Smalltalk: JAVA::Java newWithServerForJavaPath:('my\path\to\java.executable'asFilename).
JavaScript: JAVA::Java.newWithServerForJavaPath("my\path\to\java.executable".asFilename());

=====newConnectedTo:aHhostString port:aPortNumber withTimeout:aTimeoutSeconds=====
* This is used to connect to a running JavaBridge on the network. The JavaBridge must be started in server mode on the remote host. After connecting a new connected instance of JAVA::Java is returned.
:: '''aHostString''' - the hostname or IP of the remote machine as String
:: '''aPortNumber ''' - the port on which the remote machine is listening as Number
:: '''aTimeoutSeconds''' - a connect timeout in seconds as Number
Smalltalk: JAVA::Java newConnectedTo:'myHostName' port:4567 withTimeout:30.
JavaScript: JAVA::Java.newConnectedTo_port_withTimeout("myHostName",4567,30);

=====newWaitingForConnectOnHost:aListeningAddressString port:aListeningPortNumber withTimeout:aTimeoutSeconds=====
* This is used to wait for incomming connecions of a running JavaBridge on the network. The JavaBridge must be started in client mode on the remote host. After connecting a new connected instance of JAVA::Java is returned.
:: '''deprecated: aListeningAddressString''' - no longer used. Can be nil.
:: '''aListeningPortNumber ''' - the port on which to listen for incomming connections as Number
:: '''aTimeoutSeconds''' - a connect timeout in seconds as Number, If nil it will wait endless.

=====singletonInstance=====
* This will call newWithServer for the first time and then always returns the same connected JAVA::Java instance until the connection was closed, then a new connected instance is returned.

=====exitAllInstances=====
* This will close all instances of JAVA::Java.

====instance protocol====
=====loadJarByPath:aPath=====
* Adds a jar to the running JavaVM. If the jar depends on other jars or libraries you have to add them too.
:: '''aPath''' - the path to the jar file as String.

=====loadJar:aByteArray=====
* Adds a jar to the running JavaVM. If the jar depends on other jars or libraries you have to add them too.
:: '''aByteArrays''' - a ByteArray containing the JAR file.

=====loadExtension:aPath=====
* Adds a jar to the running JavaVM and caches it for subsequent usages. If the jar depends on other jars you have to add them too.
:: '''aPath''' - the path to the jar file as String.

=====boxedDo:aBlock=====
* Any autoboxed values in aBlock returned from the JavaVM are preserved as such. By default autoboxed values are automatically unboxed. This way, the identity of such objects is preserved.

=====isConnected=====
* Tests if a connection is still established.
:: '''return:''' - true if the connection is still established, else false.

=====isAlive=====
* Tests if a connection is still responding.
:: '''return:''' - true if the connection is still alive, else false. Does a message round trip.

=====closeBridge=====
* This will close the bridge connection. Depending on in which mode the JavaBridge was started, the JavaVM is also closed (-keepAlive startparameter not set).

=====exit=====
* Same as closeBridge.

== See Also==
The [[DOT NET Interface Library| DOTNET Interface Plugin & Library]], which implements a likewise interface for .NET applications/libraries.

<hr>
Back to [[Plugins]]

Java Interface Library v2

2016-05-31T15:59:07Z

Javogel: /* See Also */

== Introduction ==

This article discusses version 2 of the Java Bridge (which is as of expecco v2.9 still experimental).
The article for version 1 can be found [[Java Interface Library | here]].

The Java Interface library ("Java Bridge") is used to interact with Java objects inside an external Java Virtual Machine (JVM).

The access to Java objects, classes and programs is done via a framework called "''Java-Bridge''", which is similar in operation to the [[DOT NET Interface Library| dotNET bridge]]. This framework implements transparent forwarding of method (virtual function) calls to Java objects, which exist in a local or remote Java Virtual Machine (JVM). Also, return values, callBacks and exception information are passed back from the Java program to expecco. This is done by a proxy-object mechanism, which catches all function calls, wraps the arguments, sends a datagram to the other bridge side, awaits the reply and returns the result to the original caller. Thus, remote procedure calls are almost completely transparent to the Smalltalk/JavaScript code inside expecco. In your elementary code, you can write remote function calls as if they were to local objects.

Notice that this document describes the low level framework, which implements the bridge communication. A much easier to use high level interface (called "Groovy Blocks") exists and should normally be used, if you need access to a java application's internals during testing.
Please take a look at
[[Expecco_API#Groovy_Elementary_Blocks | "Groovy Block API"]]
and [[Testing Java Applications using Groovy blocks/en | "Testing Java Applications using Groovy blocks"]].

== Architecture ==

On the expecco side, the bridge consists of a number of Proxy objects,
which behave like regular Smalltalk objects as seen from elementary expecco code.
However, instead of performing an action when one of their methods (virtual functions) is called,
they send a message over a socket connection to the Java VM (actually: to a bridge software inside the
Java application) which decodes the message and sends it to the destination Java object.
The same is done in reverse direction with the return value.

+---------------------+ +----------+ +----------------+ +----------------+ +---------+
| | | | | | | | | Java |
| expecco |---->| Proxy |---->| Bridge |==>>==| Bridge |---->| Object |
| (elementary code) |<----| |<----| (expecco side) |==<<==| (Java side) |<----| |
+---------------------+ +----------+ +----------------+ +----------------+ +---------+

This setup allows for transparent communication with objects inside a local or remote Java VM. This may be either utility functions which happen to be convenient for the test application (for example: file parsing, syntax analysis, protocol implementaitons or access to specific hardware via driver libraries), or the tested application in the system under test itself.

Especially, it allows for the objects of the tested application to be looked into, manipulated and for functions of it or underlying frameworks to be called.

For expecco code, we tried to make this as transparent as possible, however there are a few exceptions, when function names need to be translated (for example, because the function naming syntax is different) or due to the fact that for some operations no corresponding name exists in Smalltalk (array access, for example).

Of course, multiple such connections can coexist and be served/handled in parallel. This enables an expecco test suite to communicate with both sides of a tested client-server Java application, for example.

Notice that a similar mechanism is used in expecco to communicate with DOTNET, Qt (C++) and C applications.

 

== Initializing / Releasing the Bridge ==

Before any communication can take place between expecco and any Java object, the Java side of the bridge has to be started, and a communication has to be established.
In expecco, all of the bridge classes are found in the <CODE>JAVA</CODE> namespace.

The main interface class is "<CODE>Java</CODE>", in the "<CODE>JAVA</CODE>" namespace:
<CODE><PRE>
java := JAVA::Java newWithServer.
</PRE></CODE>
or (in JavaScript):
<CODE><PRE>
java = JAVA::Java.newWithServer();
</PRE></CODE>

This starts the Java-side of the bridge (actually executes java as a background command) on the local machine, and establishes a connection to that JVM.

The bridge connection should be closed, if the bridge is no longer needed. Release the bridge with:
<CODE><PRE>
java.closeBridge();
</PRE></CODE>
which terminates the connection.

=== Start and Connect to a Remote Machine ===
The above started a Java VM and connected to it. Alternatively, you may want to connect to an already running Java program (typically, your system under test).
In order for your program to be reachable, it must allow for the bridge to connect to it via a special bridge-connection, which is a socket connection. For this, it must execute the server code found in the "JavaBridge.jar" file. To pass [[#Startup Parameters| parameters]] you will typically start it from a command line or a little shell/batch script.

Call (on the shell/cmd level):
$ java -jar <PATH_TO_JAVABRIDGE.JAR> <PARAMETERS>

The "JavaBridge.jar" file is found in the installation directory of expecco at:
\exept\expecco\packages\exept\bridgeFramework\javaBridge\javaBin\JavaBridge.jar

The Javabridge code allows for either side to initiate the connection - i.e. it can be run in server mode,
where it awaits an incoming connection, or in client mode, where it actively initiates a connection.
After connection establishment, there is no difference in the operation of the bridge, however depending on the setup of your network infrastructure, especially firewalls, either mechanism may be easier to be used.

Assuming that the bridge is already running on the remote machine as server (default),
use <CODE>newConnectedTo:port:withTimeout:</CODE> to connect to it from the expecco side:
java := JAVA::Java newConnectedTo:'myHost' port:4567 withTimeout:30.
This will initiate the connection setup from the expecco side.

Alternatively, if started in client mode use <CODE>newWaitingForConnectOnHost:port:withTimeout:</CODE>:
java := JAVA::Java newWaitingForConnectOnHost:'localhost' port:4567 withTimeout:30.
which will open a port on the expecco side, and wait until the Java side connects to it.
[[#JAVA::Java|For more details see API]]

====Startup Parameters====
You can use any parameter in any order.
If no parameter is used then the bridge listenes on port 14014 in server mode without keepAlive.
;<code>-help</code>
* Shows the help

;<code>-ip <aHostnameOrIP></code>
* In client mode this specifies the ip or hostname to connect to. In server mode this specifies the ip or hostname to bind to.

;<code>-port <aPortNumber> </code>
* In client mode this specifies the port to connect to. In server mode this specifies the listening port.

;<code>-asClient</code>
* The bridge will start in client mode. If not set the bridge is started in server mode.

;<code>-keepAlive</code>
* By setting this flag the bridge will not exit after the connection has closed and starts to connect or listen again. Otherwise, it will run for a single connection session only.

== Loading Applications (from the expecco side) ==

Normally, you would start your application with the required command line arguments and include the javabridge as jar there. However, in some situations, it may be required to dynamically load other jars into the connected Java VM.
By accessing a classloader, additional classes, or applications as contained in JAR files can be loaded from the expecco side.

This can be used to add a JAR file to the classloader:
<CODE><PRE>
java loadJarByPath:'pathToJarFile'. "/ assuming "java" is a handle as returned from the above connect
</PRE></CODE>

or, if the JAR file is loaded in memory:
<CODE><PRE>
java loadJar:jarByteArray. "/ where "jarByteArray" is a ByteArray containing the JAR file
</PRE></CODE>

If the JVM is on a remote machine, the path is resolved on the expecco side and the JAR will be transferred to the remote side.

Should transferring the JAR be too much overhead, an additional mechanism is provided:
<CODE><PRE>
java loadExtension:'pathToJarFile'.
</PRE></CODE>
this will cache the JAR file on the bridge side and eliminate the overhead of subsequent invocations.

== Java Class Access ==

This following code sample simply references (i.e. accesses) the class "JFrame" from the <CODE>"javax.swing"</CODE> package. The fully specified class name in Java would be <CODE>"javax.swing.JFrame"</CODE>:
<CODE><PRE>
java getJavaClass:'javax.swing.JFrame'
</PRE></CODE>

Or, if you want to load multiple classes:
<CODE><PRE>
java import:'javax.swing.JFrame' import:'javax.swing.JButton'
do:[:jFrame :jButton | "do something with JButton and JFrame" ].
</PRE></CODE>

v2 also supports dynamic compilation of java source code:
<CODE><PRE>
java getJavaClass:'className' fromSource:'classSource'. "/ where classSource is a String containing valid java source code
</PRE></CODE>

and loading precompiled java bytecode:
<CODE><PRE>
java getJavaClass:'className' fromByteCode:byteCode. "/ where byteCode is a ByteArray containing valid java bytecode
</PRE></CODE>

[[#Remote Dynamic Code Injection | for details see Remote Dynamic Code Injection]]

== Instantiating a Class ==

Object instances are created via the "new"-message, sent to a proxy of a Java class. You can get this proxy as described in the previous section. For example, if we want to create a new instance of a "JFrame" and a "JButton", write:
<CODE><PRE>
frame := java getJavaClass:'javax.swing.JFrame' new.
button := java getJavaClass:'javax.swing.JButton' new.
</PRE></CODE>
The first statement results in a proxy object for the "JFrame" instance. The second line results in a proxy for a new "JButton" object.

== Calling Instance Methods ==

A method call is done by a message send to a proxy object, where the message is the method name to call. For example, to call the <CODE>"setVisible(boolean isVisible)"</CODE> method on the above JFrame object, we send the following message to that proxy:
<CODE><PRE>
frame setVisible:true.
</PRE></CODE>

As method naming is different in Smalltalk and Java, a dynamic translation is applied when sending messages from Smalltalk code to a remote Java object. Smalltalk has arguments embedded inside parts of a so called "keyword" message, such as in "receiver foo:arg1 bar:arg2", where "foo:bar:" would be the message name, and "arg1", "arg2" be the arguments.

In Java, the message name is a single identifier, and arguments are written in an argument list after the message name: "receiver.fooBar(arg1, arg2)".

When message names are translated, only the very first part of the Smalltalk keyword message is taken ("foo" in the above example), and the remaining parts are simpl ignored. Thus, any of the Smalltalk messages "foo:bar:", "foo:xxxx:" and "foo:_:" (a single underscore as second part) all translate to the same Java message name "foo()".

Therefore, to call a method with more than one argument, like <CODE>"setSize(int width,int height)"</CODE> on a JFrame instance we can write:
<CODE><PRE>
frame setSize:300 _:200.
</PRE></CODE>
but just as well:
<CODE><PRE>
frame setSize:300 anyWord:200.
</PRE></CODE>
or any other selector with "setSize:" as its first component.
The selector translation mechanism simply takes the first part as the Java selector.

In practice, you should take a reasonably descriptive name, such as: "frame setSize:300 height:200" or only the Java name as first part, such as "frame setSize:300 _:200".

For a call of a method with 4 arguments, we could write:
<CODE><PRE>
frame setBounds:100 y:50 width:300 height:200.
</PRE></CODE>
or:
<CODE><PRE>
frame setBounds:100 _:50 _:300 _:200.
</PRE></CODE>

Also here the <CODE>"y: width: height:"</CODE> can be named as you want, but the first part must be "setBounds:".

=== Calling Static Methods ===

Calling a static method on an object is not different from calling non static methods. In most cases you will call a static method not on an object but directly on the class. This is done by using the class object as "receiver" of the message. For example, if we want to call the static method <CODE>"isDefaultLookAndFeelDecorated()"</CODE> of the JFrame class, write:
<CODE><PRE>
java getJavaClass:'javax.swing.JFrame' isDefaultLookAndFeelDecorated.
</PRE></CODE>

== Accessing Fields ==

As Smalltalk does not support access of an object's fields from the outside (it is fully encapsulated, and access from outside is ONLY allowed via getters/setters), an additional translation mechanism is provided for field access.

Accessing a field of a Java object or a class's static field uses the same syntax as method calls. To access a field, send a message where the message is the field name. To access the field of a class the field must be static.
For example, to get the value of the static field named <CODE>"EXIT_ON_CLOSE"</CODE> of the "JFrame" class, write
<CODE><PRE>
value := java getJavaClass:'javax.swing.JFrame' EXIT_ON_CLOSE.
</PRE></CODE>
The variable "value" now holds the integer value of the <CODE>"EXIT_ON_CLOSE"</CODE> constant.

Assuming that a "JFrame" object had a field named <CODE>"myField"</CODE>, to access this field, we'd have to write:
<CODE><PRE>
value := frame myField.
</PRE></CODE>
and "value" now holding whatever <CODE>"myField"</CODE> returns. This could be another object reference or any primitive value.

=== Setting Fields ===
To set a field, use a setter-like method call:
<CODE><PRE>
frame myField: newValue.
</PRE></CODE>

=== Name Conflicts ===

In very rare situations, a Java object may contain both a field and a method by the same name.
In this case, the Smalltalk code cannot depend on the dynamic translation mechanism (which actually looks for either a field or method name to match), but instead make it explicit, which operation is wanted:
Use:
<CODE><PRE>
frame getFieldByName:'myField'
</PRE></CODE>
to read a field, and:
<CODE><PRE>
frame setFieldByName:'myField' value:123.
</PRE></CODE>
to write the field.

If there are both fields and methods by the same name, and you use the non-explicit call,
the bridge will always assume that you want to call the getter/setter and perform a method call.
 

== Callbacks from Java ==
Sometimes you may want to execute a piece of Smalltalk code during the execution of the Java code. For example, we may want to install a Smalltalk observer to be notified when a button on a Java GUI was pressed,
or some other callback from a Java framework.

The following code registers a Smalltalk block as a callback for a mouse press event of a button:
<CODE><PRE>
listener := MouseListener new.
listener implementMethod:'mousePressed' as:[ Transcript showCR:'Hello from Java' ].
</PRE></CODE>
The above creates the callback and the listener, which can now be registered on a button:
<CODE><PRE>
button addMouseListener:listener.
</PRE></CODE>
Now, with the press of the button in the Java GUI, the Smalltalk block will be executed and writes <CODE>"Hello from Java"</CODE> to the Smalltalk console.
Of course, any other (Smalltalk-)action code can be made to run via this mechanism.

But be aware, that the callback is possibly called later (when the elementary action, which installed the code, has already finished long ago). Also, as the Java code execution is not synchronized with any of your expecco action execution, the callback may also be called at any arbutrary time, even at times when no activity at all is executed on the expecco side. If you forget to cleanup, and the Java object is still alive, it may even be called after you have finished your test run (if you keep the java bridge handle around and alive, for example in an expecoo environment variable).

So the Smalltalk callback code should not depend on any particular elementary action to be currently running, but instead in most cases write some information into a shared data container, preferably an instance of "SharedQueue", which is thread safe. Then, some other action (an elementary action) would read-wait and read events from that shared queue.

make sure that your test correctly cleans up any such callbacks afterwards. As a last resort, use the "Shutdown Bridge Connection" menu item, which closes the bridge connection, and thereby - as a side effect - removes any leftover callbacks. It does close the connection, and any remaining java proxy object handles become invalid, though.

Another example, using an observer could look like:
<CODE><PRE>
observer := java Observer new.
observer implementMethod:'update'
as:[:sourceObservable :argument|
argument notNil ifTrue:[ Transcript showCR:('I was notifyed with: ',argument toString) ]
ifFalse:[ Transcript showCR:'I was notifyed and the argument was nil' ].
].
myObservable addObserver:observer.
</PRE></CODE>
When the observable calls <CODE>"notifyObservers"</CODE>, the Smalltalk block will be executed.

== Exceptions in Java ==
Exceptions on the Java side are signalled back to the Smalltalk side and raise a corresponding exception there. However, on the Java side, the call stack which lead to the exception has already been unwound at that time (Java exceptions are not proceedable). So a proceed in the Smalltalk-side exception handler only affects the Smalltalk caller, but may leave the Java side in an undefined state.

== Remote Dynamic Code Injection ==
Sometimes we might want to execute code without the overhead of many rpc-messages being sent over the bridge, especially if we want to do something time critical, or want to make execution time measurements.
For this, it is possible to load a class at runtime into the JavaVM. The code of the class will first be sent to the JavaVM, which will compile and load the generated byte code. Then, the class can be accessed via the bridge just like any other preloaded class.

The following example specifies the class code in a smalltalk string and inject the code into the JavaVM. Then an instance of that new class will be instantiated and finally a method of the object instance will be invoked:
<CODE><PRE>
classCode := '
package myPackage.test;

import java.awt.BorderLayout;
import java.awt.event.MouseAdapter;
import java.awt.event.MouseEvent;
import java.util.Calendar;

import javax.swing.JButton;
import javax.swing.JFrame;
import javax.swing.JLabel;;

public class MyInjectedClass {
public void createSampleApp(){
JFrame frame=new JFrame("Hello im injected");
frame.setLayout(new BorderLayout());
JButton button=new JButton("click me");
final JLabel label=new JLabel("Text");
button.addMouseListener(new MouseAdapter() {

@Override
public void mouseClicked(MouseEvent e) {
label.setText(Calendar.getInstance().getTime().toString());
}
});
frame.add(label,BorderLayout.NORTH);
frame.add(button,BorderLayout.SOUTH);
frame.setSize(300, 300);
frame.setVisible(true);
}
}
'.
classObject := java getJavaClass:'myPackage.test.MyInjectedClass' fromSource:classCode.
classObject new createSampleApp.
</PRE></CODE>
After the code has been injected, a new instance of <CODE>"MyInjectedClass"</CODE> is created and the <CODE>"createSampleApp"</CODE> method is called. Because the example implements a GUI, a Java window will open, containing a label and a button. Clicking the button displays the current time in the label.



=== Code Sources for Class injection ===
There are 3 possible types of class code sources which we can use to inject the code. In the examples before we directly used a simple <CODE>"String"</CODE> in the smalltalk code as a code source. We also can use a <CODE>"*.java"</CODE> file as source. Just read the content of the file into a string and use it as in the previous examples.

To inject a <CODE>"*.class"</CODE> file use the following code:
<pre>
java getJavaClass:'the.class.name' fromByteCode:classCode.
</pre>

== Examples ==

This example creates a JFrame with one button inside. Then a Mouselistener is created and registered on the button. When the button is pressed, the title of the window changes to <CODE>"onPressed"</CODE> and the Transcript shows the message <CODE>"onPressed"</CODE>. When the button is released, the title of the window is changed to <CODE>"onReleased"</CODE> and the Transcript shows <CODE>"onReleased"</CODE>. If the button lost the mouse focus, the bridge will exit (disconnect), and the Java side is terminated.
<CODE><PRE>
|java frame button listener|

"/getting a bridge
java := JAVA::JavaBridge newWithServer.

"/creating a new frame and button object
frame := java getJavaClass:'javax.swing.JFrame' new.
button := java JButton new:'Click'.

"/creating a new mouse listener and adding callback blocks
listener := java MouseListener new.

listener implementMethod:'mousePressed' as:[ Transcript showCR:'onPress'. frame setTitle:'onPressed' ].
listener implementMethod:'mouseReleased' as:[ Transcript showCR:'onReleased'. frame setTitle:'onReleased' ].
listener implementMethod:'mouseExited' as:[ Transcript showCR:'onExited'. java closeBridge. ].

"/register the mouse listener on the button and make the frame with button visible
button addMouseListener:listener.
frame add:button.
frame setSize:300 y:100.
frame setVisible: true.
</PRE></CODE>



==Differences between v1 and v2==
===General===
* A Java Bridge instance no longer requires multiple ports to be open. Only one port is required.
* The identity of strings and primitve wrappers can be preserved.
* Arrays of primitive types are serialized.

===Loading Applications===
* '''addJarByPath:''' and '''addToClassPath:''' are still supported but have been deprecated. use '''loadJar:''', '''loadJarByPath:''' and '''loadExtension:''' instead. The new methods no longer require the jar or library to be present on the remote machine.

[[Java Interface Library#Loading Applications (from the expecco side) | v1]] [[#Loading Applications (from the expecco side) | v2]]

===Java Class Access===
* Sending the fully qualified name with instances of "." replaced by "_" to the bridge handle is still supported, but not recommended.
* A new method '''getJavaClass:''' has been introduced. This solves the side effects of "_" being a legal character in class names.

[[Java Interface Library#Java Package Import and Class Access | v1]] [[#Java Class Access | v2]]
===Callbacks from Java===
* A new method '''implementMethod:as:''' has been introduced to assign callback blocks to method names. The old way is still supported.

[[Java Interface Library#Callbacks from Java | v1]] [[#Callbacks from Java | v2]]

===Remote Dynamic Code Injection===
* Code injection was problematic in v1 and has now been re-implemented in v2.

[[#Remote Dynamic Code Injection | v2]]

== API ==
===JAVA::Java===
====class protocol====
=====newWithServer=====
* This will start a local JavaVM, running the JavaBridge, and establishes a connection on a random free port.
: A new connected instance of JAVA::Java class is returned.

=====newWithServerForJavaPath:aJavaPathFilename=====
* This is the same as newWithServer but the path to the java executable can be specified. The JavaVM version must be 1.6 or higher to run the JavaBridge.
:: '''aJavaPathFilename''' - must be a instance of Filename
Smalltalk: JAVA::Java newWithServerForJavaPath:('my\path\to\java.executable'asFilename).
JavaScript: JAVA::Java.newWithServerForJavaPath("my\path\to\java.executable".asFilename());

=====newConnectedTo:aHhostString port:aPortNumber withTimeout:aTimeoutSeconds=====
* This is used to connect to a running JavaBridge on the network. The JavaBridge must be started in server mode on the remote host. After connecting a new connected instance of JAVA::Java is returned.
:: '''aHostString''' - the hostname or IP of the remote machine as String
:: '''aPortNumber ''' - the port on which the remote machine is listening as Number
:: '''aTimeoutSeconds''' - a connect timeout in seconds as Number
Smalltalk: JAVA::Java newConnectedTo:'myHostName' port:4567 withTimeout:30.
JavaScript: JAVA::Java.newConnectedTo_port_withTimeout("myHostName",4567,30);

=====newWaitingForConnectOnHost:aListeningAddressString port:aListeningPortNumber withTimeout:aTimeoutSeconds=====
* This is used to wait for incomming connecions of a running JavaBridge on the network. The JavaBridge must be started in client mode on the remote host. After connecting a new connected instance of JAVA::Java is returned.
:: '''deprecated: aListeningAddressString''' - no longer used. Can be nil.
:: '''aListeningPortNumber ''' - the port on which to listen for incomming connections as Number
:: '''aTimeoutSeconds''' - a connect timeout in seconds as Number, If nil it will wait endless.

=====singletonInstance=====
* This will call newWithServer for the first time and then always returns the same connected JAVA::Java instance until the connection was closed, then a new connected instance is returned.

=====exitAllInstances=====
* This will close all instances of JAVA::Java.

====instance protocol====
=====loadJarByPath:aPath=====
* Adds a jar to the running JavaVM. If the jar depends on other jars or libraries you have to add them too.
:: '''aPath''' - the path to the jar file as String.

=====loadJar:aByteArray=====
* Adds a jar to the running JavaVM. If the jar depends on other jars or libraries you have to add them too.
:: '''aByteArrays''' - a ByteArray containing the JAR file.

=====loadExtension:aPath=====
* Adds a jar to the running JavaVM and caches it for subsequent usages. If the jar depends on other jars you have to add them too.
:: '''aPath''' - the path to the jar file as String.

=====boxedDo:aBlock=====
* Any autoboxed values in aBlock returned from the JavaVM are preserved as such. By default autoboxed values are automatically unboxed. This way, the identity of such objects is preserved.

=====isConnected=====
* Tests if a connection is still established.
:: '''return:''' - true if the connection is still established, else false.

=====isAlive=====
* Tests if a connection is still responding.
:: '''return:''' - true if the connection is still alive, else false. Does a message round trip.

=====closeBridge=====
* This will close the bridge connection. Depending on in which mode the JavaBridge was started, the JavaVM is also closed (-keepAlive startparameter not set).

=====exit=====
* Same as closeBridge.

== See Also==
The [[DOT NET Interface Library| DOTNET Interface Plugin & Library]], which implements a likewise interface for .NET applications/libraries.

<hr>
Back to [[Plugins]]

Java Interface Library v2

2016-05-31T15:58:28Z

Javogel: /* Introduction */

== Introduction ==

This article discusses version 2 of the Java Bridge (which is as of expecco v2.9 still experimental).
The article for version 1 can be found [[Java Interface Library | here]].

The Java Interface library ("Java Bridge") is used to interact with Java objects inside an external Java Virtual Machine (JVM).

The access to Java objects, classes and programs is done via a framework called "''Java-Bridge''", which is similar in operation to the [[DOT NET Interface Library| dotNET bridge]]. This framework implements transparent forwarding of method (virtual function) calls to Java objects, which exist in a local or remote Java Virtual Machine (JVM). Also, return values, callBacks and exception information are passed back from the Java program to expecco. This is done by a proxy-object mechanism, which catches all function calls, wraps the arguments, sends a datagram to the other bridge side, awaits the reply and returns the result to the original caller. Thus, remote procedure calls are almost completely transparent to the Smalltalk/JavaScript code inside expecco. In your elementary code, you can write remote function calls as if they were to local objects.

Notice that this document describes the low level framework, which implements the bridge communication. A much easier to use high level interface (called "Groovy Blocks") exists and should normally be used, if you need access to a java application's internals during testing.
Please take a look at
[[Expecco_API#Groovy_Elementary_Blocks | "Groovy Block API"]]
and [[Testing Java Applications using Groovy blocks/en | "Testing Java Applications using Groovy blocks"]].

== Architecture ==

On the expecco side, the bridge consists of a number of Proxy objects,
which behave like regular Smalltalk objects as seen from elementary expecco code.
However, instead of performing an action when one of their methods (virtual functions) is called,
they send a message over a socket connection to the Java VM (actually: to a bridge software inside the
Java application) which decodes the message and sends it to the destination Java object.
The same is done in reverse direction with the return value.

+---------------------+ +----------+ +----------------+ +----------------+ +---------+
| | | | | | | | | Java |
| expecco |---->| Proxy |---->| Bridge |==>>==| Bridge |---->| Object |
| (elementary code) |<----| |<----| (expecco side) |==<<==| (Java side) |<----| |
+---------------------+ +----------+ +----------------+ +----------------+ +---------+

This setup allows for transparent communication with objects inside a local or remote Java VM. This may be either utility functions which happen to be convenient for the test application (for example: file parsing, syntax analysis, protocol implementaitons or access to specific hardware via driver libraries), or the tested application in the system under test itself.

Especially, it allows for the objects of the tested application to be looked into, manipulated and for functions of it or underlying frameworks to be called.

For expecco code, we tried to make this as transparent as possible, however there are a few exceptions, when function names need to be translated (for example, because the function naming syntax is different) or due to the fact that for some operations no corresponding name exists in Smalltalk (array access, for example).

Of course, multiple such connections can coexist and be served/handled in parallel. This enables an expecco test suite to communicate with both sides of a tested client-server Java application, for example.

Notice that a similar mechanism is used in expecco to communicate with DOTNET, Qt (C++) and C applications.

 

== Initializing / Releasing the Bridge ==

Before any communication can take place between expecco and any Java object, the Java side of the bridge has to be started, and a communication has to be established.
In expecco, all of the bridge classes are found in the <CODE>JAVA</CODE> namespace.

The main interface class is "<CODE>Java</CODE>", in the "<CODE>JAVA</CODE>" namespace:
<CODE><PRE>
java := JAVA::Java newWithServer.
</PRE></CODE>
or (in JavaScript):
<CODE><PRE>
java = JAVA::Java.newWithServer();
</PRE></CODE>

This starts the Java-side of the bridge (actually executes java as a background command) on the local machine, and establishes a connection to that JVM.

The bridge connection should be closed, if the bridge is no longer needed. Release the bridge with:
<CODE><PRE>
java.closeBridge();
</PRE></CODE>
which terminates the connection.

=== Start and Connect to a Remote Machine ===
The above started a Java VM and connected to it. Alternatively, you may want to connect to an already running Java program (typically, your system under test).
In order for your program to be reachable, it must allow for the bridge to connect to it via a special bridge-connection, which is a socket connection. For this, it must execute the server code found in the "JavaBridge.jar" file. To pass [[#Startup Parameters| parameters]] you will typically start it from a command line or a little shell/batch script.

Call (on the shell/cmd level):
$ java -jar <PATH_TO_JAVABRIDGE.JAR> <PARAMETERS>

The "JavaBridge.jar" file is found in the installation directory of expecco at:
\exept\expecco\packages\exept\bridgeFramework\javaBridge\javaBin\JavaBridge.jar

The Javabridge code allows for either side to initiate the connection - i.e. it can be run in server mode,
where it awaits an incoming connection, or in client mode, where it actively initiates a connection.
After connection establishment, there is no difference in the operation of the bridge, however depending on the setup of your network infrastructure, especially firewalls, either mechanism may be easier to be used.

Assuming that the bridge is already running on the remote machine as server (default),
use <CODE>newConnectedTo:port:withTimeout:</CODE> to connect to it from the expecco side:
java := JAVA::Java newConnectedTo:'myHost' port:4567 withTimeout:30.
This will initiate the connection setup from the expecco side.

Alternatively, if started in client mode use <CODE>newWaitingForConnectOnHost:port:withTimeout:</CODE>:
java := JAVA::Java newWaitingForConnectOnHost:'localhost' port:4567 withTimeout:30.
which will open a port on the expecco side, and wait until the Java side connects to it.
[[#JAVA::Java|For more details see API]]

====Startup Parameters====
You can use any parameter in any order.
If no parameter is used then the bridge listenes on port 14014 in server mode without keepAlive.
;<code>-help</code>
* Shows the help

;<code>-ip <aHostnameOrIP></code>
* In client mode this specifies the ip or hostname to connect to. In server mode this specifies the ip or hostname to bind to.

;<code>-port <aPortNumber> </code>
* In client mode this specifies the port to connect to. In server mode this specifies the listening port.

;<code>-asClient</code>
* The bridge will start in client mode. If not set the bridge is started in server mode.

;<code>-keepAlive</code>
* By setting this flag the bridge will not exit after the connection has closed and starts to connect or listen again. Otherwise, it will run for a single connection session only.

== Loading Applications (from the expecco side) ==

Normally, you would start your application with the required command line arguments and include the javabridge as jar there. However, in some situations, it may be required to dynamically load other jars into the connected Java VM.
By accessing a classloader, additional classes, or applications as contained in JAR files can be loaded from the expecco side.

This can be used to add a JAR file to the classloader:
<CODE><PRE>
java loadJarByPath:'pathToJarFile'. "/ assuming "java" is a handle as returned from the above connect
</PRE></CODE>

or, if the JAR file is loaded in memory:
<CODE><PRE>
java loadJar:jarByteArray. "/ where "jarByteArray" is a ByteArray containing the JAR file
</PRE></CODE>

If the JVM is on a remote machine, the path is resolved on the expecco side and the JAR will be transferred to the remote side.

Should transferring the JAR be too much overhead, an additional mechanism is provided:
<CODE><PRE>
java loadExtension:'pathToJarFile'.
</PRE></CODE>
this will cache the JAR file on the bridge side and eliminate the overhead of subsequent invocations.

== Java Class Access ==

This following code sample simply references (i.e. accesses) the class "JFrame" from the <CODE>"javax.swing"</CODE> package. The fully specified class name in Java would be <CODE>"javax.swing.JFrame"</CODE>:
<CODE><PRE>
java getJavaClass:'javax.swing.JFrame'
</PRE></CODE>

Or, if you want to load multiple classes:
<CODE><PRE>
java import:'javax.swing.JFrame' import:'javax.swing.JButton'
do:[:jFrame :jButton | "do something with JButton and JFrame" ].
</PRE></CODE>

v2 also supports dynamic compilation of java source code:
<CODE><PRE>
java getJavaClass:'className' fromSource:'classSource'. "/ where classSource is a String containing valid java source code
</PRE></CODE>

and loading precompiled java bytecode:
<CODE><PRE>
java getJavaClass:'className' fromByteCode:byteCode. "/ where byteCode is a ByteArray containing valid java bytecode
</PRE></CODE>

[[#Remote Dynamic Code Injection | for details see Remote Dynamic Code Injection]]

== Instantiating a Class ==

Object instances are created via the "new"-message, sent to a proxy of a Java class. You can get this proxy as described in the previous section. For example, if we want to create a new instance of a "JFrame" and a "JButton", write:
<CODE><PRE>
frame := java getJavaClass:'javax.swing.JFrame' new.
button := java getJavaClass:'javax.swing.JButton' new.
</PRE></CODE>
The first statement results in a proxy object for the "JFrame" instance. The second line results in a proxy for a new "JButton" object.

== Calling Instance Methods ==

A method call is done by a message send to a proxy object, where the message is the method name to call. For example, to call the <CODE>"setVisible(boolean isVisible)"</CODE> method on the above JFrame object, we send the following message to that proxy:
<CODE><PRE>
frame setVisible:true.
</PRE></CODE>

As method naming is different in Smalltalk and Java, a dynamic translation is applied when sending messages from Smalltalk code to a remote Java object. Smalltalk has arguments embedded inside parts of a so called "keyword" message, such as in "receiver foo:arg1 bar:arg2", where "foo:bar:" would be the message name, and "arg1", "arg2" be the arguments.

In Java, the message name is a single identifier, and arguments are written in an argument list after the message name: "receiver.fooBar(arg1, arg2)".

When message names are translated, only the very first part of the Smalltalk keyword message is taken ("foo" in the above example), and the remaining parts are simpl ignored. Thus, any of the Smalltalk messages "foo:bar:", "foo:xxxx:" and "foo:_:" (a single underscore as second part) all translate to the same Java message name "foo()".

Therefore, to call a method with more than one argument, like <CODE>"setSize(int width,int height)"</CODE> on a JFrame instance we can write:
<CODE><PRE>
frame setSize:300 _:200.
</PRE></CODE>
but just as well:
<CODE><PRE>
frame setSize:300 anyWord:200.
</PRE></CODE>
or any other selector with "setSize:" as its first component.
The selector translation mechanism simply takes the first part as the Java selector.

In practice, you should take a reasonably descriptive name, such as: "frame setSize:300 height:200" or only the Java name as first part, such as "frame setSize:300 _:200".

For a call of a method with 4 arguments, we could write:
<CODE><PRE>
frame setBounds:100 y:50 width:300 height:200.
</PRE></CODE>
or:
<CODE><PRE>
frame setBounds:100 _:50 _:300 _:200.
</PRE></CODE>

Also here the <CODE>"y: width: height:"</CODE> can be named as you want, but the first part must be "setBounds:".

=== Calling Static Methods ===

Calling a static method on an object is not different from calling non static methods. In most cases you will call a static method not on an object but directly on the class. This is done by using the class object as "receiver" of the message. For example, if we want to call the static method <CODE>"isDefaultLookAndFeelDecorated()"</CODE> of the JFrame class, write:
<CODE><PRE>
java getJavaClass:'javax.swing.JFrame' isDefaultLookAndFeelDecorated.
</PRE></CODE>

== Accessing Fields ==

As Smalltalk does not support access of an object's fields from the outside (it is fully encapsulated, and access from outside is ONLY allowed via getters/setters), an additional translation mechanism is provided for field access.

Accessing a field of a Java object or a class's static field uses the same syntax as method calls. To access a field, send a message where the message is the field name. To access the field of a class the field must be static.
For example, to get the value of the static field named <CODE>"EXIT_ON_CLOSE"</CODE> of the "JFrame" class, write
<CODE><PRE>
value := java getJavaClass:'javax.swing.JFrame' EXIT_ON_CLOSE.
</PRE></CODE>
The variable "value" now holds the integer value of the <CODE>"EXIT_ON_CLOSE"</CODE> constant.

Assuming that a "JFrame" object had a field named <CODE>"myField"</CODE>, to access this field, we'd have to write:
<CODE><PRE>
value := frame myField.
</PRE></CODE>
and "value" now holding whatever <CODE>"myField"</CODE> returns. This could be another object reference or any primitive value.

=== Setting Fields ===
To set a field, use a setter-like method call:
<CODE><PRE>
frame myField: newValue.
</PRE></CODE>

=== Name Conflicts ===

In very rare situations, a Java object may contain both a field and a method by the same name.
In this case, the Smalltalk code cannot depend on the dynamic translation mechanism (which actually looks for either a field or method name to match), but instead make it explicit, which operation is wanted:
Use:
<CODE><PRE>
frame getFieldByName:'myField'
</PRE></CODE>
to read a field, and:
<CODE><PRE>
frame setFieldByName:'myField' value:123.
</PRE></CODE>
to write the field.

If there are both fields and methods by the same name, and you use the non-explicit call,
the bridge will always assume that you want to call the getter/setter and perform a method call.
 

== Callbacks from Java ==
Sometimes you may want to execute a piece of Smalltalk code during the execution of the Java code. For example, we may want to install a Smalltalk observer to be notified when a button on a Java GUI was pressed,
or some other callback from a Java framework.

The following code registers a Smalltalk block as a callback for a mouse press event of a button:
<CODE><PRE>
listener := MouseListener new.
listener implementMethod:'mousePressed' as:[ Transcript showCR:'Hello from Java' ].
</PRE></CODE>
The above creates the callback and the listener, which can now be registered on a button:
<CODE><PRE>
button addMouseListener:listener.
</PRE></CODE>
Now, with the press of the button in the Java GUI, the Smalltalk block will be executed and writes <CODE>"Hello from Java"</CODE> to the Smalltalk console.
Of course, any other (Smalltalk-)action code can be made to run via this mechanism.

But be aware, that the callback is possibly called later (when the elementary action, which installed the code, has already finished long ago). Also, as the Java code execution is not synchronized with any of your expecco action execution, the callback may also be called at any arbutrary time, even at times when no activity at all is executed on the expecco side. If you forget to cleanup, and the Java object is still alive, it may even be called after you have finished your test run (if you keep the java bridge handle around and alive, for example in an expecoo environment variable).

So the Smalltalk callback code should not depend on any particular elementary action to be currently running, but instead in most cases write some information into a shared data container, preferably an instance of "SharedQueue", which is thread safe. Then, some other action (an elementary action) would read-wait and read events from that shared queue.

make sure that your test correctly cleans up any such callbacks afterwards. As a last resort, use the "Shutdown Bridge Connection" menu item, which closes the bridge connection, and thereby - as a side effect - removes any leftover callbacks. It does close the connection, and any remaining java proxy object handles become invalid, though.

Another example, using an observer could look like:
<CODE><PRE>
observer := java Observer new.
observer implementMethod:'update'
as:[:sourceObservable :argument|
argument notNil ifTrue:[ Transcript showCR:('I was notifyed with: ',argument toString) ]
ifFalse:[ Transcript showCR:'I was notifyed and the argument was nil' ].
].
myObservable addObserver:observer.
</PRE></CODE>
When the observable calls <CODE>"notifyObservers"</CODE>, the Smalltalk block will be executed.

== Exceptions in Java ==
Exceptions on the Java side are signalled back to the Smalltalk side and raise a corresponding exception there. However, on the Java side, the call stack which lead to the exception has already been unwound at that time (Java exceptions are not proceedable). So a proceed in the Smalltalk-side exception handler only affects the Smalltalk caller, but may leave the Java side in an undefined state.

== Remote Dynamic Code Injection ==
Sometimes we might want to execute code without the overhead of many rpc-messages being sent over the bridge, especially if we want to do something time critical, or want to make execution time measurements.
For this, it is possible to load a class at runtime into the JavaVM. The code of the class will first be sent to the JavaVM, which will compile and load the generated byte code. Then, the class can be accessed via the bridge just like any other preloaded class.

The following example specifies the class code in a smalltalk string and inject the code into the JavaVM. Then an instance of that new class will be instantiated and finally a method of the object instance will be invoked:
<CODE><PRE>
classCode := '
package myPackage.test;

import java.awt.BorderLayout;
import java.awt.event.MouseAdapter;
import java.awt.event.MouseEvent;
import java.util.Calendar;

import javax.swing.JButton;
import javax.swing.JFrame;
import javax.swing.JLabel;;

public class MyInjectedClass {
public void createSampleApp(){
JFrame frame=new JFrame("Hello im injected");
frame.setLayout(new BorderLayout());
JButton button=new JButton("click me");
final JLabel label=new JLabel("Text");
button.addMouseListener(new MouseAdapter() {

@Override
public void mouseClicked(MouseEvent e) {
label.setText(Calendar.getInstance().getTime().toString());
}
});
frame.add(label,BorderLayout.NORTH);
frame.add(button,BorderLayout.SOUTH);
frame.setSize(300, 300);
frame.setVisible(true);
}
}
'.
classObject := java getJavaClass:'myPackage.test.MyInjectedClass' fromSource:classCode.
classObject new createSampleApp.
</PRE></CODE>
After the code has been injected, a new instance of <CODE>"MyInjectedClass"</CODE> is created and the <CODE>"createSampleApp"</CODE> method is called. Because the example implements a GUI, a Java window will open, containing a label and a button. Clicking the button displays the current time in the label.



=== Code Sources for Class injection ===
There are 3 possible types of class code sources which we can use to inject the code. In the examples before we directly used a simple <CODE>"String"</CODE> in the smalltalk code as a code source. We also can use a <CODE>"*.java"</CODE> file as source. Just read the content of the file into a string and use it as in the previous examples.

To inject a <CODE>"*.class"</CODE> file use the following code:
<pre>
java getJavaClass:'the.class.name' fromByteCode:classCode.
</pre>

== Examples ==

This example creates a JFrame with one button inside. Then a Mouselistener is created and registered on the button. When the button is pressed, the title of the window changes to <CODE>"onPressed"</CODE> and the Transcript shows the message <CODE>"onPressed"</CODE>. When the button is released, the title of the window is changed to <CODE>"onReleased"</CODE> and the Transcript shows <CODE>"onReleased"</CODE>. If the button lost the mouse focus, the bridge will exit (disconnect), and the Java side is terminated.
<CODE><PRE>
|java frame button listener|

"/getting a bridge
java := JAVA::JavaBridge newWithServer.

"/creating a new frame and button object
frame := java getJavaClass:'javax.swing.JFrame' new.
button := java JButton new:'Click'.

"/creating a new mouse listener and adding callback blocks
listener := java MouseListener new.

listener implementMethod:'mousePressed' as:[ Transcript showCR:'onPress'. frame setTitle:'onPressed' ].
listener implementMethod:'mouseReleased' as:[ Transcript showCR:'onReleased'. frame setTitle:'onReleased' ].
listener implementMethod:'mouseExited' as:[ Transcript showCR:'onExited'. java closeBridge. ].

"/register the mouse listener on the button and make the frame with button visible
button addMouseListener:listener.
frame add:button.
frame setSize:300 y:100.
frame setVisible: true.
</PRE></CODE>



==Differences between v1 and v2==
===General===
* A Java Bridge instance no longer requires multiple ports to be open. Only one port is required.
* The identity of strings and primitve wrappers can be preserved.
* Arrays of primitive types are serialized.

===Loading Applications===
* '''addJarByPath:''' and '''addToClassPath:''' are still supported but have been deprecated. use '''loadJar:''', '''loadJarByPath:''' and '''loadExtension:''' instead. The new methods no longer require the jar or library to be present on the remote machine.

[[Java Interface Library#Loading Applications (from the expecco side) | v1]] [[#Loading Applications (from the expecco side) | v2]]

===Java Class Access===
* Sending the fully qualified name with instances of "." replaced by "_" to the bridge handle is still supported, but not recommended.
* A new method '''getJavaClass:''' has been introduced. This solves the side effects of "_" being a legal character in class names.

[[Java Interface Library#Java Package Import and Class Access | v1]] [[#Java Class Access | v2]]
===Callbacks from Java===
* A new method '''implementMethod:as:''' has been introduced to assign callback blocks to method names. The old way is still supported.

[[Java Interface Library#Callbacks from Java | v1]] [[#Callbacks from Java | v2]]

===Remote Dynamic Code Injection===
* Code injection was problematic in v1 and has now been re-implemented in v2.

[[#Remote Dynamic Code Injection | v2]]

== API ==
===JAVA::Java===
====class protocol====
=====newWithServer=====
* This will start a local JavaVM, running the JavaBridge, and establishes a connection on a random free port.
: A new connected instance of JAVA::Java class is returned.

=====newWithServerForJavaPath:aJavaPathFilename=====
* This is the same as newWithServer but the path to the java executable can be specified. The JavaVM version must be 1.6 or higher to run the JavaBridge.
:: '''aJavaPathFilename''' - must be a instance of Filename
Smalltalk: JAVA::Java newWithServerForJavaPath:('my\path\to\java.executable'asFilename).
JavaScript: JAVA::Java.newWithServerForJavaPath("my\path\to\java.executable".asFilename());

=====newConnectedTo:aHhostString port:aPortNumber withTimeout:aTimeoutSeconds=====
* This is used to connect to a running JavaBridge on the network. The JavaBridge must be started in server mode on the remote host. After connecting a new connected instance of JAVA::Java is returned.
:: '''aHostString''' - the hostname or IP of the remote machine as String
:: '''aPortNumber ''' - the port on which the remote machine is listening as Number
:: '''aTimeoutSeconds''' - a connect timeout in seconds as Number
Smalltalk: JAVA::Java newConnectedTo:'myHostName' port:4567 withTimeout:30.
JavaScript: JAVA::Java.newConnectedTo_port_withTimeout("myHostName",4567,30);

=====newWaitingForConnectOnHost:aListeningAddressString port:aListeningPortNumber withTimeout:aTimeoutSeconds=====
* This is used to wait for incomming connecions of a running JavaBridge on the network. The JavaBridge must be started in client mode on the remote host. After connecting a new connected instance of JAVA::Java is returned.
:: '''deprecated: aListeningAddressString''' - no longer used. Can be nil.
:: '''aListeningPortNumber ''' - the port on which to listen for incomming connections as Number
:: '''aTimeoutSeconds''' - a connect timeout in seconds as Number, If nil it will wait endless.

=====singletonInstance=====
* This will call newWithServer for the first time and then always returns the same connected JAVA::Java instance until the connection was closed, then a new connected instance is returned.

=====exitAllInstances=====
* This will close all instances of JAVA::Java.

====instance protocol====
=====loadJarByPath:aPath=====
* Adds a jar to the running JavaVM. If the jar depends on other jars or libraries you have to add them too.
:: '''aPath''' - the path to the jar file as String.

=====loadJar:aByteArray=====
* Adds a jar to the running JavaVM. If the jar depends on other jars or libraries you have to add them too.
:: '''aByteArrays''' - a ByteArray containing the JAR file.

=====loadExtension:aPath=====
* Adds a jar to the running JavaVM and caches it for subsequent usages. If the jar depends on other jars you have to add them too.
:: '''aPath''' - the path to the jar file as String.

=====boxedDo:aBlock=====
* Any autoboxed values in aBlock returned from the JavaVM are preserved as such. By default autoboxed values are automatically unboxed. This way, the identity of such objects is preserved.

=====isConnected=====
* Tests if a connection is still established.
:: '''return:''' - true if the connection is still established, else false.

=====isAlive=====
* Tests if a connection is still responding.
:: '''return:''' - true if the connection is still alive, else false. Does a message round trip.

=====closeBridge=====
* This will close the bridge connection. Depending on in which mode the JavaBridge was started, the JavaVM is also closed (-keepAlive startparameter not set).

=====exit=====
* Same as closeBridge.

== See Also==
The [[DOT NET Interface Library| DOTNET Interface Plugin & Library]], which implements a likewise interface for .NET applications/libraries.

<hr>
Back to [[Plugins]] 
Back to [[OnlineDocumentation#Library and Plugin Overview|Online Documentation]].

Java Interface Library v2

2016-05-31T15:34:14Z

Javogel: /* General */

== Introduction ==

The Java Interface library ("Java Bridge") is used to interact with Java objects inside an external Java Virtual Machine (JVM).

The access to Java objects, classes and programs is done via a framework called "''Java-Bridge''", which is similar in operation to the [[DOT NET Interface Library| dotNET bridge]]. This framework implements transparent forwarding of method (virtual function) calls to Java objects, which exist in a local or remote Java Virtual Machine (JVM). Also, return values, callBacks and exception information are passed back from the Java program to expecco. This is done by a proxy-object mechanism, which catches all function calls, wraps the arguments, sends a datagram to the other bridge side, awaits the reply and returns the result to the original caller. Thus, remote procedure calls are almost completely transparent to the Smalltalk/JavaScript code inside expecco. In your elementary code, you can write remote function calls as if they were to local objects.

Notice that this document describes the low level framework, which implements the bridge communication. A much easier to use high level interface (called "Groovy Blocks") exists and should normally be used, if you need access to a java application's internals during testing.
Please take a look at
[[Expecco_API#Groovy_Elementary_Blocks | "Groovy Block API"]]
and [[Testing Java Applications using Groovy blocks/en | "Testing Java Applications using Groovy blocks"]].

This article discusses version 2 of the Java Bridge. The article for version 1 can be found [[Java Interface Library | here]]

== Architecture ==

On the expecco side, the bridge consists of a number of Proxy objects,
which behave like regular Smalltalk objects as seen from elementary expecco code.
However, instead of performing an action when one of their methods (virtual functions) is called,
they send a message over a socket connection to the Java VM (actually: to a bridge software inside the
Java application) which decodes the message and sends it to the destination Java object.
The same is done in reverse direction with the return value.

+---------------------+ +----------+ +----------------+ +----------------+ +---------+
| | | | | | | | | Java |
| expecco |---->| Proxy |---->| Bridge |==>>==| Bridge |---->| Object |
| (elementary code) |<----| |<----| (expecco side) |==<<==| (Java side) |<----| |
+---------------------+ +----------+ +----------------+ +----------------+ +---------+

This setup allows for transparent communication with objects inside a local or remote Java VM. This may be either utility functions which happen to be convenient for the test application (for example: file parsing, syntax analysis, protocol implementaitons or access to specific hardware via driver libraries), or the tested application in the system under test itself.

Especially, it allows for the objects of the tested application to be looked into, manipulated and for functions of it or underlying frameworks to be called.

For expecco code, we tried to make this as transparent as possible, however there are a few exceptions, when function names need to be translated (for example, because the function naming syntax is different) or due to the fact that for some operations no corresponding name exists in Smalltalk (array access, for example).

Of course, multiple such connections can coexist and be served/handled in parallel. This enables an expecco test suite to communicate with both sides of a tested client-server Java application, for example.

Notice that a similar mechanism is used in expecco to communicate with DOTNET, Qt (C++) and C applications.

 

== Initializing / Releasing the Bridge ==

Before any communication can take place between expecco and any Java object, the Java side of the bridge has to be started, and a communication has to be established.
In expecco, all of the bridge classes are found in the <CODE>JAVA</CODE> namespace.

The main interface class is "<CODE>Java</CODE>", in the "<CODE>JAVA</CODE>" namespace:
<CODE><PRE>
java := JAVA::Java newWithServer.
</PRE></CODE>
or (in JavaScript):
<CODE><PRE>
java = JAVA::Java.newWithServer();
</PRE></CODE>

This starts the Java-side of the bridge (actually executes java as a background command) on the local machine, and establishes a connection to that JVM.

The bridge connection should be closed, if the bridge is no longer needed. Release the bridge with:
<CODE><PRE>
java.closeBridge();
</PRE></CODE>
which terminates the connection.

=== Start and Connect to a Remote Machine ===
The above started a Java VM and connected to it. Alternatively, you may want to connect to an already running Java program (typically, your system under test).
In order for your program to be reachable, it must allow for the bridge to connect to it via a special bridge-connection, which is a socket connection. For this, it must execute the server code found in the "JavaBridge.jar" file. To pass [[#Startup Parameters| parameters]] you will typically start it from a command line or a little shell/batch script.

Call (on the shell/cmd level):
$ java -jar <PATH_TO_JAVABRIDGE.JAR> <PARAMETERS>

The "JavaBridge.jar" file is found in the installation directory of expecco at:
\exept\expecco\packages\exept\bridgeFramework\javaBridge\javaBin\JavaBridge.jar

The Javabridge code allows for either side to initiate the connection - i.e. it can be run in server mode,
where it awaits an incoming connection, or in client mode, where it actively initiates a connection.
After connection establishment, there is no difference in the operation of the bridge, however depending on the setup of your network infrastructure, especially firewalls, either mechanism may be easier to be used.

Assuming that the bridge is already running on the remote machine as server (default),
use <CODE>newConnectedTo:port:withTimeout:</CODE> to connect to it from the expecco side:
java := JAVA::Java newConnectedTo:'myHost' port:4567 withTimeout:30.
This will initiate the connection setup from the expecco side.

Alternatively, if started in client mode use <CODE>newWaitingForConnectOnHost:port:withTimeout:</CODE>:
java := JAVA::Java newWaitingForConnectOnHost:'localhost' port:4567 withTimeout:30.
which will open a port on the expecco side, and wait until the Java side connects to it.
[[#JAVA::Java|For more details see API]]

====Startup Parameters====
You can use any parameter in any order.
If no parameter is used then the bridge listenes on port 14014 in server mode without keepAlive.
;<code>-help</code>
* Shows the help

;<code>-ip <aHostnameOrIP></code>
* In client mode this specifies the ip or hostname to connect to. In server mode this specifies the ip or hostname to bind to.

;<code>-port <aPortNumber> </code>
* In client mode this specifies the port to connect to. In server mode this specifies the listening port.

;<code>-asClient</code>
* The bridge will start in client mode. If not set the bridge is started in server mode.

;<code>-keepAlive</code>
* By setting this flag the bridge will not exit after the connection has closed and starts to connect or listen again. Otherwise, it will run for a single connection session only.

== Loading Applications (from the expecco side) ==

Normally, you would start your application with the required command line arguments and include the javabridge as jar there. However, in some situations, it may be required to dynamically load other jars into the connected Java VM.
By accessing a classloader, additional classes, or applications as contained in JAR files can be loaded from the expecco side.

This can be used to add a JAR file to the classloader:
<CODE><PRE>
java loadJarByPath:'pathToJarFile'. "/ assuming "java" is a handle as returned from the above connect
</PRE></CODE>

or, if the JAR file is loaded in memory:
<CODE><PRE>
java loadJar:jarByteArray. "/ where "jarByteArray" is a ByteArray containing the JAR file
</PRE></CODE>

If the JVM is on a remote machine, the path is resolved on the expecco side and the JAR will be transferred to the remote side.

Should transferring the JAR be too much overhead, an additional mechanism is provided:
<CODE><PRE>
java loadExtension:'pathToJarFile'.
</PRE></CODE>
this will cache the JAR file on the bridge side and eliminate the overhead of subsequent invocations.

== Java Class Access ==

This following code sample simply references (i.e. accesses) the class "JFrame" from the <CODE>"javax.swing"</CODE> package. The fully specified class name in Java would be <CODE>"javax.swing.JFrame"</CODE>:
<CODE><PRE>
java getJavaClass:'javax.swing.JFrame'
</PRE></CODE>

Or, if you want to load multiple classes:
<CODE><PRE>
java import:'javax.swing.JFrame' import:'javax.swing.JButton'
do:[:jFrame :jButton | "do something with JButton and JFrame" ].
</PRE></CODE>

v2 also supports dynamic compilation of java source code:
<CODE><PRE>
java getJavaClass:'className' fromSource:'classSource'. "/ where classSource is a String containing valid java source code
</PRE></CODE>

and loading precompiled java bytecode:
<CODE><PRE>
java getJavaClass:'className' fromByteCode:byteCode. "/ where byteCode is a ByteArray containing valid java bytecode
</PRE></CODE>

[[#Remote Dynamic Code Injection | for details see Remote Dynamic Code Injection]]

== Instantiating a Class ==

Object instances are created via the "new"-message, sent to a proxy of a Java class. You can get this proxy as described in the previous section. For example, if we want to create a new instance of a "JFrame" and a "JButton", write:
<CODE><PRE>
frame := java getJavaClass:'javax.swing.JFrame' new.
button := java getJavaClass:'javax.swing.JButton' new.
</PRE></CODE>
The first statement results in a proxy object for the "JFrame" instance. The second line results in a proxy for a new "JButton" object.

== Calling Instance Methods ==

A method call is done by a message send to a proxy object, where the message is the method name to call. For example, to call the <CODE>"setVisible(boolean isVisible)"</CODE> method on the above JFrame object, we send the following message to that proxy:
<CODE><PRE>
frame setVisible:true.
</PRE></CODE>

As method naming is different in Smalltalk and Java, a dynamic translation is applied when sending messages from Smalltalk code to a remote Java object. Smalltalk has arguments embedded inside parts of a so called "keyword" message, such as in "receiver foo:arg1 bar:arg2", where "foo:bar:" would be the message name, and "arg1", "arg2" be the arguments.

In Java, the message name is a single identifier, and arguments are written in an argument list after the message name: "receiver.fooBar(arg1, arg2)".

When message names are translated, only the very first part of the Smalltalk keyword message is taken ("foo" in the above example), and the remaining parts are simpl ignored. Thus, any of the Smalltalk messages "foo:bar:", "foo:xxxx:" and "foo:_:" (a single underscore as second part) all translate to the same Java message name "foo()".

Therefore, to call a method with more than one argument, like <CODE>"setSize(int width,int height)"</CODE> on a JFrame instance we can write:
<CODE><PRE>
frame setSize:300 _:200.
</PRE></CODE>
but just as well:
<CODE><PRE>
frame setSize:300 anyWord:200.
</PRE></CODE>
or any other selector with "setSize:" as its first component.
The selector translation mechanism simply takes the first part as the Java selector.

In practice, you should take a reasonably descriptive name, such as: "frame setSize:300 height:200" or only the Java name as first part, such as "frame setSize:300 _:200".

For a call of a method with 4 arguments, we could write:
<CODE><PRE>
frame setBounds:100 y:50 width:300 height:200.
</PRE></CODE>
or:
<CODE><PRE>
frame setBounds:100 _:50 _:300 _:200.
</PRE></CODE>

Also here the <CODE>"y: width: height:"</CODE> can be named as you want, but the first part must be "setBounds:".

=== Calling Static Methods ===

Calling a static method on an object is not different from calling non static methods. In most cases you will call a static method not on an object but directly on the class. This is done by using the class object as "receiver" of the message. For example, if we want to call the static method <CODE>"isDefaultLookAndFeelDecorated()"</CODE> of the JFrame class, write:
<CODE><PRE>
java getJavaClass:'javax.swing.JFrame' isDefaultLookAndFeelDecorated.
</PRE></CODE>

== Accessing Fields ==

As Smalltalk does not support access of an object's fields from the outside (it is fully encapsulated, and access from outside is ONLY allowed via getters/setters), an additional translation mechanism is provided for field access.

Accessing a field of a Java object or a class's static field uses the same syntax as method calls. To access a field, send a message where the message is the field name. To access the field of a class the field must be static.
For example, to get the value of the static field named <CODE>"EXIT_ON_CLOSE"</CODE> of the "JFrame" class, write
<CODE><PRE>
value := java getJavaClass:'javax.swing.JFrame' EXIT_ON_CLOSE.
</PRE></CODE>
The variable "value" now holds the integer value of the <CODE>"EXIT_ON_CLOSE"</CODE> constant.

Assuming that a "JFrame" object had a field named <CODE>"myField"</CODE>, to access this field, we'd have to write:
<CODE><PRE>
value := frame myField.
</PRE></CODE>
and "value" now holding whatever <CODE>"myField"</CODE> returns. This could be another object reference or any primitive value.

=== Setting Fields ===
To set a field, use a setter-like method call:
<CODE><PRE>
frame myField: newValue.
</PRE></CODE>

=== Name Conflicts ===

In very rare situations, a Java object may contain both a field and a method by the same name.
In this case, the Smalltalk code cannot depend on the dynamic translation mechanism (which actually looks for either a field or method name to match), but instead make it explicit, which operation is wanted:
Use:
<CODE><PRE>
frame getFieldByName:'myField'
</PRE></CODE>
to read a field, and:
<CODE><PRE>
frame setFieldByName:'myField' value:123.
</PRE></CODE>
to write the field.

If there are both fields and methods by the same name, and you use the non-explicit call,
the bridge will always assume that you want to call the getter/setter and perform a method call.
 

== Callbacks from Java ==
Sometimes you may want to execute a piece of Smalltalk code during the execution of the Java code. For example, we may want to install a Smalltalk observer to be notified when a button on a Java GUI was pressed,
or some other callback from a Java framework.

The following code registers a Smalltalk block as a callback for a mouse press event of a button:
<CODE><PRE>
listener := MouseListener new.
listener implementMethod:'mousePressed' as:[ Transcript showCR:'Hello from Java' ].
</PRE></CODE>
The above creates the callback and the listener, which can now be registered on a button:
<CODE><PRE>
button addMouseListener:listener.
</PRE></CODE>
Now, with the press of the button in the Java GUI, the Smalltalk block will be executed and writes <CODE>"Hello from Java"</CODE> to the Smalltalk console.
Of course, any other (Smalltalk-)action code can be made to run via this mechanism.

But be aware, that the callback is possibly called later (when the elementary action, which installed the code, has already finished long ago). Also, as the Java code execution is not synchronized with any of your expecco action execution, the callback may also be called at any arbutrary time, even at times when no activity at all is executed on the expecco side. If you forget to cleanup, and the Java object is still alive, it may even be called after you have finished your test run (if you keep the java bridge handle around and alive, for example in an expecoo environment variable).

So the Smalltalk callback code should not depend on any particular elementary action to be currently running, but instead in most cases write some information into a shared data container, preferably an instance of "SharedQueue", which is thread safe. Then, some other action (an elementary action) would read-wait and read events from that shared queue.

make sure that your test correctly cleans up any such callbacks afterwards. As a last resort, use the "Shutdown Bridge Connection" menu item, which closes the bridge connection, and thereby - as a side effect - removes any leftover callbacks. It does close the connection, and any remaining java proxy object handles become invalid, though.

Another example, using an observer could look like:
<CODE><PRE>
observer := java Observer new.
observer implementMethod:'update'
as:[:sourceObservable :argument|
argument notNil ifTrue:[ Transcript showCR:('I was notifyed with: ',argument toString) ]
ifFalse:[ Transcript showCR:'I was notifyed and the argument was nil' ].
].
myObservable addObserver:observer.
</PRE></CODE>
When the observable calls <CODE>"notifyObservers"</CODE>, the Smalltalk block will be executed.

== Exceptions in Java ==
Exceptions on the Java side are signalled back to the Smalltalk side and raise a corresponding exception there. However, on the Java side, the call stack which lead to the exception has already been unwound at that time (Java exceptions are not proceedable). So a proceed in the Smalltalk-side exception handler only affects the Smalltalk caller, but may leave the Java side in an undefined state.

== Remote Dynamic Code Injection ==
Sometimes we might want to execute code without the overhead of many rpc-messages being sent over the bridge, especially if we want to do something time critical, or want to make execution time measurements.
For this, it is possible to load a class at runtime into the JavaVM. The code of the class will first be sent to the JavaVM, which will compile and load the generated byte code. Then, the class can be accessed via the bridge just like any other preloaded class.

The following example specifies the class code in a smalltalk string and inject the code into the JavaVM. Then an instance of that new class will be instantiated and finally a method of the object instance will be invoked:
<CODE><PRE>
classCode := '
package myPackage.test;

import java.awt.BorderLayout;
import java.awt.event.MouseAdapter;
import java.awt.event.MouseEvent;
import java.util.Calendar;

import javax.swing.JButton;
import javax.swing.JFrame;
import javax.swing.JLabel;;

public class MyInjectedClass {
public void createSampleApp(){
JFrame frame=new JFrame("Hello im injected");
frame.setLayout(new BorderLayout());
JButton button=new JButton("click me");
final JLabel label=new JLabel("Text");
button.addMouseListener(new MouseAdapter() {

@Override
public void mouseClicked(MouseEvent e) {
label.setText(Calendar.getInstance().getTime().toString());
}
});
frame.add(label,BorderLayout.NORTH);
frame.add(button,BorderLayout.SOUTH);
frame.setSize(300, 300);
frame.setVisible(true);
}
}
'.
classObject := java getJavaClass:'myPackage.test.MyInjectedClass' fromSource:classCode.
classObject new createSampleApp.
</PRE></CODE>
After the code has been injected, a new instance of <CODE>"MyInjectedClass"</CODE> is created and the <CODE>"createSampleApp"</CODE> method is called. Because the example implements a GUI, a Java window will open, containing a label and a button. Clicking the button displays the current time in the label.



=== Code Sources for Class injection ===
There are 3 possible types of class code sources which we can use to inject the code. In the examples before we directly used a simple <CODE>"String"</CODE> in the smalltalk code as a code source. We also can use a <CODE>"*.java"</CODE> file as source. Just read the content of the file into a string and use it as in the previous examples.

To inject a <CODE>"*.class"</CODE> file use the following code:
<pre>
java getJavaClass:'the.class.name' fromByteCode:classCode.
</pre>

== Examples ==

This example creates a JFrame with one button inside. Then a Mouselistener is created and registered on the button. When the button is pressed, the title of the window changes to <CODE>"onPressed"</CODE> and the Transcript shows the message <CODE>"onPressed"</CODE>. When the button is released, the title of the window is changed to <CODE>"onReleased"</CODE> and the Transcript shows <CODE>"onReleased"</CODE>. If the button lost the mouse focus, the bridge will exit (disconnect), and the Java side is terminated.
<CODE><PRE>
|java frame button listener|

"/getting a bridge
java := JAVA::JavaBridge newWithServer.

"/creating a new frame and button object
frame := java getJavaClass:'javax.swing.JFrame' new.
button := java JButton new:'Click'.

"/creating a new mouse listener and adding callback blocks
listener := java MouseListener new.

listener implementMethod:'mousePressed' as:[ Transcript showCR:'onPress'. frame setTitle:'onPressed' ].
listener implementMethod:'mouseReleased' as:[ Transcript showCR:'onReleased'. frame setTitle:'onReleased' ].
listener implementMethod:'mouseExited' as:[ Transcript showCR:'onExited'. java closeBridge. ].

"/register the mouse listener on the button and make the frame with button visible
button addMouseListener:listener.
frame add:button.
frame setSize:300 y:100.
frame setVisible: true.
</PRE></CODE>



==Differences between v1 and v2==
===General===
* A Java Bridge instance no longer requires multiple ports to be open. Only one port is required.
* The identity of strings and primitve wrappers can be preserved.
* Arrays of primitive types are serialized.

===Loading Applications===
* '''addJarByPath:''' and '''addToClassPath:''' are still supported but have been deprecated. use '''loadJar:''', '''loadJarByPath:''' and '''loadExtension:''' instead. The new methods no longer require the jar or library to be present on the remote machine.

[[Java Interface Library#Loading Applications (from the expecco side) | v1]] [[#Loading Applications (from the expecco side) | v2]]

===Java Class Access===
* Sending the fully qualified name with instances of "." replaced by "_" to the bridge handle is still supported, but not recommended.
* A new method '''getJavaClass:''' has been introduced. This solves the side effects of "_" being a legal character in class names.

[[Java Interface Library#Java Package Import and Class Access | v1]] [[#Java Class Access | v2]]
===Callbacks from Java===
* A new method '''implementMethod:as:''' has been introduced to assign callback blocks to method names. The old way is still supported.

[[Java Interface Library#Callbacks from Java | v1]] [[#Callbacks from Java | v2]]

===Remote Dynamic Code Injection===
* Code injection was problematic in v1 and has now been re-implemented in v2.

[[#Remote Dynamic Code Injection | v2]]

== API ==
===JAVA::Java===
====class protocol====
=====newWithServer=====
* This will start a local JavaVM, running the JavaBridge, and establishes a connection on a random free port.
: A new connected instance of JAVA::Java class is returned.

=====newWithServerForJavaPath:aJavaPathFilename=====
* This is the same as newWithServer but the path to the java executable can be specified. The JavaVM version must be 1.6 or higher to run the JavaBridge.
:: '''aJavaPathFilename''' - must be a instance of Filename
Smalltalk: JAVA::Java newWithServerForJavaPath:('my\path\to\java.executable'asFilename).
JavaScript: JAVA::Java.newWithServerForJavaPath("my\path\to\java.executable".asFilename());

=====newConnectedTo:aHhostString port:aPortNumber withTimeout:aTimeoutSeconds=====
* This is used to connect to a running JavaBridge on the network. The JavaBridge must be started in server mode on the remote host. After connecting a new connected instance of JAVA::Java is returned.
:: '''aHostString''' - the hostname or IP of the remote machine as String
:: '''aPortNumber ''' - the port on which the remote machine is listening as Number
:: '''aTimeoutSeconds''' - a connect timeout in seconds as Number
Smalltalk: JAVA::Java newConnectedTo:'myHostName' port:4567 withTimeout:30.
JavaScript: JAVA::Java.newConnectedTo_port_withTimeout("myHostName",4567,30);

=====newWaitingForConnectOnHost:aListeningAddressString port:aListeningPortNumber withTimeout:aTimeoutSeconds=====
* This is used to wait for incomming connecions of a running JavaBridge on the network. The JavaBridge must be started in client mode on the remote host. After connecting a new connected instance of JAVA::Java is returned.
:: '''deprecated: aListeningAddressString''' - no longer used. Can be nil.
:: '''aListeningPortNumber ''' - the port on which to listen for incomming connections as Number
:: '''aTimeoutSeconds''' - a connect timeout in seconds as Number, If nil it will wait endless.

=====singletonInstance=====
* This will call newWithServer for the first time and then always returns the same connected JAVA::Java instance until the connection was closed, then a new connected instance is returned.

=====exitAllInstances=====
* This will close all instances of JAVA::Java.

====instance protocol====
=====loadJarByPath:aPath=====
* Adds a jar to the running JavaVM. If the jar depends on other jars or libraries you have to add them too.
:: '''aPath''' - the path to the jar file as String.

=====loadJar:aByteArray=====
* Adds a jar to the running JavaVM. If the jar depends on other jars or libraries you have to add them too.
:: '''aByteArrays''' - a ByteArray containing the JAR file.

=====loadExtension:aPath=====
* Adds a jar to the running JavaVM and caches it for subsequent usages. If the jar depends on other jars you have to add them too.
:: '''aPath''' - the path to the jar file as String.

=====boxedDo:aBlock=====
* Any autoboxed values in aBlock returned from the JavaVM are preserved as such. By default autoboxed values are automatically unboxed. This way, the identity of such objects is preserved.

=====isConnected=====
* Tests if a connection is still established.
:: '''return:''' - true if the connection is still established, else false.

=====isAlive=====
* Tests if a connection is still responding.
:: '''return:''' - true if the connection is still alive, else false. Does a message round trip.

=====closeBridge=====
* This will close the bridge connection. Depending on in which mode the JavaBridge was started, the JavaVM is also closed (-keepAlive startparameter not set).

=====exit=====
* Same as closeBridge.

== See Also==
The [[DOT NET Interface Library| DOTNET Interface Plugin & Library]], which implements a likewise interface for .NET applications/libraries.

<hr>
Back to [[Plugins]] 
Back to [[OnlineDocumentation#Library and Plugin Overview|Online Documentation]].

Java Interface Library v2

2016-05-31T15:31:52Z

Javogel: /* Differences between v1 and v2 */

== Introduction ==

The Java Interface library ("Java Bridge") is used to interact with Java objects inside an external Java Virtual Machine (JVM).

The access to Java objects, classes and programs is done via a framework called "''Java-Bridge''", which is similar in operation to the [[DOT NET Interface Library| dotNET bridge]]. This framework implements transparent forwarding of method (virtual function) calls to Java objects, which exist in a local or remote Java Virtual Machine (JVM). Also, return values, callBacks and exception information are passed back from the Java program to expecco. This is done by a proxy-object mechanism, which catches all function calls, wraps the arguments, sends a datagram to the other bridge side, awaits the reply and returns the result to the original caller. Thus, remote procedure calls are almost completely transparent to the Smalltalk/JavaScript code inside expecco. In your elementary code, you can write remote function calls as if they were to local objects.

Notice that this document describes the low level framework, which implements the bridge communication. A much easier to use high level interface (called "Groovy Blocks") exists and should normally be used, if you need access to a java application's internals during testing.
Please take a look at
[[Expecco_API#Groovy_Elementary_Blocks | "Groovy Block API"]]
and [[Testing Java Applications using Groovy blocks/en | "Testing Java Applications using Groovy blocks"]].

This article discusses version 2 of the Java Bridge. The article for version 1 can be found [[Java Interface Library | here]]

== Architecture ==

On the expecco side, the bridge consists of a number of Proxy objects,
which behave like regular Smalltalk objects as seen from elementary expecco code.
However, instead of performing an action when one of their methods (virtual functions) is called,
they send a message over a socket connection to the Java VM (actually: to a bridge software inside the
Java application) which decodes the message and sends it to the destination Java object.
The same is done in reverse direction with the return value.

+---------------------+ +----------+ +----------------+ +----------------+ +---------+
| | | | | | | | | Java |
| expecco |---->| Proxy |---->| Bridge |==>>==| Bridge |---->| Object |
| (elementary code) |<----| |<----| (expecco side) |==<<==| (Java side) |<----| |
+---------------------+ +----------+ +----------------+ +----------------+ +---------+

This setup allows for transparent communication with objects inside a local or remote Java VM. This may be either utility functions which happen to be convenient for the test application (for example: file parsing, syntax analysis, protocol implementaitons or access to specific hardware via driver libraries), or the tested application in the system under test itself.

Especially, it allows for the objects of the tested application to be looked into, manipulated and for functions of it or underlying frameworks to be called.

For expecco code, we tried to make this as transparent as possible, however there are a few exceptions, when function names need to be translated (for example, because the function naming syntax is different) or due to the fact that for some operations no corresponding name exists in Smalltalk (array access, for example).

Of course, multiple such connections can coexist and be served/handled in parallel. This enables an expecco test suite to communicate with both sides of a tested client-server Java application, for example.

Notice that a similar mechanism is used in expecco to communicate with DOTNET, Qt (C++) and C applications.

 

== Initializing / Releasing the Bridge ==

Before any communication can take place between expecco and any Java object, the Java side of the bridge has to be started, and a communication has to be established.
In expecco, all of the bridge classes are found in the <CODE>JAVA</CODE> namespace.

The main interface class is "<CODE>Java</CODE>", in the "<CODE>JAVA</CODE>" namespace:
<CODE><PRE>
java := JAVA::Java newWithServer.
</PRE></CODE>
or (in JavaScript):
<CODE><PRE>
java = JAVA::Java.newWithServer();
</PRE></CODE>

This starts the Java-side of the bridge (actually executes java as a background command) on the local machine, and establishes a connection to that JVM.

The bridge connection should be closed, if the bridge is no longer needed. Release the bridge with:
<CODE><PRE>
java.closeBridge();
</PRE></CODE>
which terminates the connection.

=== Start and Connect to a Remote Machine ===
The above started a Java VM and connected to it. Alternatively, you may want to connect to an already running Java program (typically, your system under test).
In order for your program to be reachable, it must allow for the bridge to connect to it via a special bridge-connection, which is a socket connection. For this, it must execute the server code found in the "JavaBridge.jar" file. To pass [[#Startup Parameters| parameters]] you will typically start it from a command line or a little shell/batch script.

Call (on the shell/cmd level):
$ java -jar <PATH_TO_JAVABRIDGE.JAR> <PARAMETERS>

The "JavaBridge.jar" file is found in the installation directory of expecco at:
\exept\expecco\packages\exept\bridgeFramework\javaBridge\javaBin\JavaBridge.jar

The Javabridge code allows for either side to initiate the connection - i.e. it can be run in server mode,
where it awaits an incoming connection, or in client mode, where it actively initiates a connection.
After connection establishment, there is no difference in the operation of the bridge, however depending on the setup of your network infrastructure, especially firewalls, either mechanism may be easier to be used.

Assuming that the bridge is already running on the remote machine as server (default),
use <CODE>newConnectedTo:port:withTimeout:</CODE> to connect to it from the expecco side:
java := JAVA::Java newConnectedTo:'myHost' port:4567 withTimeout:30.
This will initiate the connection setup from the expecco side.

Alternatively, if started in client mode use <CODE>newWaitingForConnectOnHost:port:withTimeout:</CODE>:
java := JAVA::Java newWaitingForConnectOnHost:'localhost' port:4567 withTimeout:30.
which will open a port on the expecco side, and wait until the Java side connects to it.
[[#JAVA::Java|For more details see API]]

====Startup Parameters====
You can use any parameter in any order.
If no parameter is used then the bridge listenes on port 14014 in server mode without keepAlive.
;<code>-help</code>
* Shows the help

;<code>-ip <aHostnameOrIP></code>
* In client mode this specifies the ip or hostname to connect to. In server mode this specifies the ip or hostname to bind to.

;<code>-port <aPortNumber> </code>
* In client mode this specifies the port to connect to. In server mode this specifies the listening port.

;<code>-asClient</code>
* The bridge will start in client mode. If not set the bridge is started in server mode.

;<code>-keepAlive</code>
* By setting this flag the bridge will not exit after the connection has closed and starts to connect or listen again. Otherwise, it will run for a single connection session only.

== Loading Applications (from the expecco side) ==

Normally, you would start your application with the required command line arguments and include the javabridge as jar there. However, in some situations, it may be required to dynamically load other jars into the connected Java VM.
By accessing a classloader, additional classes, or applications as contained in JAR files can be loaded from the expecco side.

This can be used to add a JAR file to the classloader:
<CODE><PRE>
java loadJarByPath:'pathToJarFile'. "/ assuming "java" is a handle as returned from the above connect
</PRE></CODE>

or, if the JAR file is loaded in memory:
<CODE><PRE>
java loadJar:jarByteArray. "/ where "jarByteArray" is a ByteArray containing the JAR file
</PRE></CODE>

If the JVM is on a remote machine, the path is resolved on the expecco side and the JAR will be transferred to the remote side.

Should transferring the JAR be too much overhead, an additional mechanism is provided:
<CODE><PRE>
java loadExtension:'pathToJarFile'.
</PRE></CODE>
this will cache the JAR file on the bridge side and eliminate the overhead of subsequent invocations.

== Java Class Access ==

This following code sample simply references (i.e. accesses) the class "JFrame" from the <CODE>"javax.swing"</CODE> package. The fully specified class name in Java would be <CODE>"javax.swing.JFrame"</CODE>:
<CODE><PRE>
java getJavaClass:'javax.swing.JFrame'
</PRE></CODE>

Or, if you want to load multiple classes:
<CODE><PRE>
java import:'javax.swing.JFrame' import:'javax.swing.JButton'
do:[:jFrame :jButton | "do something with JButton and JFrame" ].
</PRE></CODE>

v2 also supports dynamic compilation of java source code:
<CODE><PRE>
java getJavaClass:'className' fromSource:'classSource'. "/ where classSource is a String containing valid java source code
</PRE></CODE>

and loading precompiled java bytecode:
<CODE><PRE>
java getJavaClass:'className' fromByteCode:byteCode. "/ where byteCode is a ByteArray containing valid java bytecode
</PRE></CODE>

[[#Remote Dynamic Code Injection | for details see Remote Dynamic Code Injection]]

== Instantiating a Class ==

Object instances are created via the "new"-message, sent to a proxy of a Java class. You can get this proxy as described in the previous section. For example, if we want to create a new instance of a "JFrame" and a "JButton", write:
<CODE><PRE>
frame := java getJavaClass:'javax.swing.JFrame' new.
button := java getJavaClass:'javax.swing.JButton' new.
</PRE></CODE>
The first statement results in a proxy object for the "JFrame" instance. The second line results in a proxy for a new "JButton" object.

== Calling Instance Methods ==

A method call is done by a message send to a proxy object, where the message is the method name to call. For example, to call the <CODE>"setVisible(boolean isVisible)"</CODE> method on the above JFrame object, we send the following message to that proxy:
<CODE><PRE>
frame setVisible:true.
</PRE></CODE>

As method naming is different in Smalltalk and Java, a dynamic translation is applied when sending messages from Smalltalk code to a remote Java object. Smalltalk has arguments embedded inside parts of a so called "keyword" message, such as in "receiver foo:arg1 bar:arg2", where "foo:bar:" would be the message name, and "arg1", "arg2" be the arguments.

In Java, the message name is a single identifier, and arguments are written in an argument list after the message name: "receiver.fooBar(arg1, arg2)".

When message names are translated, only the very first part of the Smalltalk keyword message is taken ("foo" in the above example), and the remaining parts are simpl ignored. Thus, any of the Smalltalk messages "foo:bar:", "foo:xxxx:" and "foo:_:" (a single underscore as second part) all translate to the same Java message name "foo()".

Therefore, to call a method with more than one argument, like <CODE>"setSize(int width,int height)"</CODE> on a JFrame instance we can write:
<CODE><PRE>
frame setSize:300 _:200.
</PRE></CODE>
but just as well:
<CODE><PRE>
frame setSize:300 anyWord:200.
</PRE></CODE>
or any other selector with "setSize:" as its first component.
The selector translation mechanism simply takes the first part as the Java selector.

In practice, you should take a reasonably descriptive name, such as: "frame setSize:300 height:200" or only the Java name as first part, such as "frame setSize:300 _:200".

For a call of a method with 4 arguments, we could write:
<CODE><PRE>
frame setBounds:100 y:50 width:300 height:200.
</PRE></CODE>
or:
<CODE><PRE>
frame setBounds:100 _:50 _:300 _:200.
</PRE></CODE>

Also here the <CODE>"y: width: height:"</CODE> can be named as you want, but the first part must be "setBounds:".

=== Calling Static Methods ===

Calling a static method on an object is not different from calling non static methods. In most cases you will call a static method not on an object but directly on the class. This is done by using the class object as "receiver" of the message. For example, if we want to call the static method <CODE>"isDefaultLookAndFeelDecorated()"</CODE> of the JFrame class, write:
<CODE><PRE>
java getJavaClass:'javax.swing.JFrame' isDefaultLookAndFeelDecorated.
</PRE></CODE>

== Accessing Fields ==

As Smalltalk does not support access of an object's fields from the outside (it is fully encapsulated, and access from outside is ONLY allowed via getters/setters), an additional translation mechanism is provided for field access.

Accessing a field of a Java object or a class's static field uses the same syntax as method calls. To access a field, send a message where the message is the field name. To access the field of a class the field must be static.
For example, to get the value of the static field named <CODE>"EXIT_ON_CLOSE"</CODE> of the "JFrame" class, write
<CODE><PRE>
value := java getJavaClass:'javax.swing.JFrame' EXIT_ON_CLOSE.
</PRE></CODE>
The variable "value" now holds the integer value of the <CODE>"EXIT_ON_CLOSE"</CODE> constant.

Assuming that a "JFrame" object had a field named <CODE>"myField"</CODE>, to access this field, we'd have to write:
<CODE><PRE>
value := frame myField.
</PRE></CODE>
and "value" now holding whatever <CODE>"myField"</CODE> returns. This could be another object reference or any primitive value.

=== Setting Fields ===
To set a field, use a setter-like method call:
<CODE><PRE>
frame myField: newValue.
</PRE></CODE>

=== Name Conflicts ===

In very rare situations, a Java object may contain both a field and a method by the same name.
In this case, the Smalltalk code cannot depend on the dynamic translation mechanism (which actually looks for either a field or method name to match), but instead make it explicit, which operation is wanted:
Use:
<CODE><PRE>
frame getFieldByName:'myField'
</PRE></CODE>
to read a field, and:
<CODE><PRE>
frame setFieldByName:'myField' value:123.
</PRE></CODE>
to write the field.

If there are both fields and methods by the same name, and you use the non-explicit call,
the bridge will always assume that you want to call the getter/setter and perform a method call.
 

== Callbacks from Java ==
Sometimes you may want to execute a piece of Smalltalk code during the execution of the Java code. For example, we may want to install a Smalltalk observer to be notified when a button on a Java GUI was pressed,
or some other callback from a Java framework.

The following code registers a Smalltalk block as a callback for a mouse press event of a button:
<CODE><PRE>
listener := MouseListener new.
listener implementMethod:'mousePressed' as:[ Transcript showCR:'Hello from Java' ].
</PRE></CODE>
The above creates the callback and the listener, which can now be registered on a button:
<CODE><PRE>
button addMouseListener:listener.
</PRE></CODE>
Now, with the press of the button in the Java GUI, the Smalltalk block will be executed and writes <CODE>"Hello from Java"</CODE> to the Smalltalk console.
Of course, any other (Smalltalk-)action code can be made to run via this mechanism.

But be aware, that the callback is possibly called later (when the elementary action, which installed the code, has already finished long ago). Also, as the Java code execution is not synchronized with any of your expecco action execution, the callback may also be called at any arbutrary time, even at times when no activity at all is executed on the expecco side. If you forget to cleanup, and the Java object is still alive, it may even be called after you have finished your test run (if you keep the java bridge handle around and alive, for example in an expecoo environment variable).

So the Smalltalk callback code should not depend on any particular elementary action to be currently running, but instead in most cases write some information into a shared data container, preferably an instance of "SharedQueue", which is thread safe. Then, some other action (an elementary action) would read-wait and read events from that shared queue.

make sure that your test correctly cleans up any such callbacks afterwards. As a last resort, use the "Shutdown Bridge Connection" menu item, which closes the bridge connection, and thereby - as a side effect - removes any leftover callbacks. It does close the connection, and any remaining java proxy object handles become invalid, though.

Another example, using an observer could look like:
<CODE><PRE>
observer := java Observer new.
observer implementMethod:'update'
as:[:sourceObservable :argument|
argument notNil ifTrue:[ Transcript showCR:('I was notifyed with: ',argument toString) ]
ifFalse:[ Transcript showCR:'I was notifyed and the argument was nil' ].
].
myObservable addObserver:observer.
</PRE></CODE>
When the observable calls <CODE>"notifyObservers"</CODE>, the Smalltalk block will be executed.

== Exceptions in Java ==
Exceptions on the Java side are signalled back to the Smalltalk side and raise a corresponding exception there. However, on the Java side, the call stack which lead to the exception has already been unwound at that time (Java exceptions are not proceedable). So a proceed in the Smalltalk-side exception handler only affects the Smalltalk caller, but may leave the Java side in an undefined state.

== Remote Dynamic Code Injection ==
Sometimes we might want to execute code without the overhead of many rpc-messages being sent over the bridge, especially if we want to do something time critical, or want to make execution time measurements.
For this, it is possible to load a class at runtime into the JavaVM. The code of the class will first be sent to the JavaVM, which will compile and load the generated byte code. Then, the class can be accessed via the bridge just like any other preloaded class.

The following example specifies the class code in a smalltalk string and inject the code into the JavaVM. Then an instance of that new class will be instantiated and finally a method of the object instance will be invoked:
<CODE><PRE>
classCode := '
package myPackage.test;

import java.awt.BorderLayout;
import java.awt.event.MouseAdapter;
import java.awt.event.MouseEvent;
import java.util.Calendar;

import javax.swing.JButton;
import javax.swing.JFrame;
import javax.swing.JLabel;;

public class MyInjectedClass {
public void createSampleApp(){
JFrame frame=new JFrame("Hello im injected");
frame.setLayout(new BorderLayout());
JButton button=new JButton("click me");
final JLabel label=new JLabel("Text");
button.addMouseListener(new MouseAdapter() {

@Override
public void mouseClicked(MouseEvent e) {
label.setText(Calendar.getInstance().getTime().toString());
}
});
frame.add(label,BorderLayout.NORTH);
frame.add(button,BorderLayout.SOUTH);
frame.setSize(300, 300);
frame.setVisible(true);
}
}
'.
classObject := java getJavaClass:'myPackage.test.MyInjectedClass' fromSource:classCode.
classObject new createSampleApp.
</PRE></CODE>
After the code has been injected, a new instance of <CODE>"MyInjectedClass"</CODE> is created and the <CODE>"createSampleApp"</CODE> method is called. Because the example implements a GUI, a Java window will open, containing a label and a button. Clicking the button displays the current time in the label.



=== Code Sources for Class injection ===
There are 3 possible types of class code sources which we can use to inject the code. In the examples before we directly used a simple <CODE>"String"</CODE> in the smalltalk code as a code source. We also can use a <CODE>"*.java"</CODE> file as source. Just read the content of the file into a string and use it as in the previous examples.

To inject a <CODE>"*.class"</CODE> file use the following code:
<pre>
java getJavaClass:'the.class.name' fromByteCode:classCode.
</pre>

== Examples ==

This example creates a JFrame with one button inside. Then a Mouselistener is created and registered on the button. When the button is pressed, the title of the window changes to <CODE>"onPressed"</CODE> and the Transcript shows the message <CODE>"onPressed"</CODE>. When the button is released, the title of the window is changed to <CODE>"onReleased"</CODE> and the Transcript shows <CODE>"onReleased"</CODE>. If the button lost the mouse focus, the bridge will exit (disconnect), and the Java side is terminated.
<CODE><PRE>
|java frame button listener|

"/getting a bridge
java := JAVA::JavaBridge newWithServer.

"/creating a new frame and button object
frame := java getJavaClass:'javax.swing.JFrame' new.
button := java JButton new:'Click'.

"/creating a new mouse listener and adding callback blocks
listener := java MouseListener new.

listener implementMethod:'mousePressed' as:[ Transcript showCR:'onPress'. frame setTitle:'onPressed' ].
listener implementMethod:'mouseReleased' as:[ Transcript showCR:'onReleased'. frame setTitle:'onReleased' ].
listener implementMethod:'mouseExited' as:[ Transcript showCR:'onExited'. java closeBridge. ].

"/register the mouse listener on the button and make the frame with button visible
button addMouseListener:listener.
frame add:button.
frame setSize:300 y:100.
frame setVisible: true.
</PRE></CODE>



==Differences between v1 and v2==
===General===
* A Java Bridge instance no longer requires multiple ports to be open. Only one port is required.
* The identity of strings and autoboxed values can be preserved.
* Arrays of primitive types are serialized.

===Loading Applications===
* '''addJarByPath:''' and '''addToClassPath:''' are still supported but have been deprecated. use '''loadJar:''', '''loadJarByPath:''' and '''loadExtension:''' instead. The new methods no longer require the jar or library to be present on the remote machine.

[[Java Interface Library#Loading Applications (from the expecco side) | v1]] [[#Loading Applications (from the expecco side) | v2]]

===Java Class Access===
* Sending the fully qualified name with instances of "." replaced by "_" to the bridge handle is still supported, but not recommended.
* A new method '''getJavaClass:''' has been introduced. This solves the side effects of "_" being a legal character in class names.

[[Java Interface Library#Java Package Import and Class Access | v1]] [[#Java Class Access | v2]]
===Callbacks from Java===
* A new method '''implementMethod:as:''' has been introduced to assign callback blocks to method names. The old way is still supported.

[[Java Interface Library#Callbacks from Java | v1]] [[#Callbacks from Java | v2]]

===Remote Dynamic Code Injection===
* Code injection was problematic in v1 and has now been re-implemented in v2.

[[#Remote Dynamic Code Injection | v2]]

== API ==
===JAVA::Java===
====class protocol====
=====newWithServer=====
* This will start a local JavaVM, running the JavaBridge, and establishes a connection on a random free port.
: A new connected instance of JAVA::Java class is returned.

=====newWithServerForJavaPath:aJavaPathFilename=====
* This is the same as newWithServer but the path to the java executable can be specified. The JavaVM version must be 1.6 or higher to run the JavaBridge.
:: '''aJavaPathFilename''' - must be a instance of Filename
Smalltalk: JAVA::Java newWithServerForJavaPath:('my\path\to\java.executable'asFilename).
JavaScript: JAVA::Java.newWithServerForJavaPath("my\path\to\java.executable".asFilename());

=====newConnectedTo:aHhostString port:aPortNumber withTimeout:aTimeoutSeconds=====
* This is used to connect to a running JavaBridge on the network. The JavaBridge must be started in server mode on the remote host. After connecting a new connected instance of JAVA::Java is returned.
:: '''aHostString''' - the hostname or IP of the remote machine as String
:: '''aPortNumber ''' - the port on which the remote machine is listening as Number
:: '''aTimeoutSeconds''' - a connect timeout in seconds as Number
Smalltalk: JAVA::Java newConnectedTo:'myHostName' port:4567 withTimeout:30.
JavaScript: JAVA::Java.newConnectedTo_port_withTimeout("myHostName",4567,30);

=====newWaitingForConnectOnHost:aListeningAddressString port:aListeningPortNumber withTimeout:aTimeoutSeconds=====
* This is used to wait for incomming connecions of a running JavaBridge on the network. The JavaBridge must be started in client mode on the remote host. After connecting a new connected instance of JAVA::Java is returned.
:: '''deprecated: aListeningAddressString''' - no longer used. Can be nil.
:: '''aListeningPortNumber ''' - the port on which to listen for incomming connections as Number
:: '''aTimeoutSeconds''' - a connect timeout in seconds as Number, If nil it will wait endless.

=====singletonInstance=====
* This will call newWithServer for the first time and then always returns the same connected JAVA::Java instance until the connection was closed, then a new connected instance is returned.

=====exitAllInstances=====
* This will close all instances of JAVA::Java.

====instance protocol====
=====loadJarByPath:aPath=====
* Adds a jar to the running JavaVM. If the jar depends on other jars or libraries you have to add them too.
:: '''aPath''' - the path to the jar file as String.

=====loadJar:aByteArray=====
* Adds a jar to the running JavaVM. If the jar depends on other jars or libraries you have to add them too.
:: '''aByteArrays''' - a ByteArray containing the JAR file.

=====loadExtension:aPath=====
* Adds a jar to the running JavaVM and caches it for subsequent usages. If the jar depends on other jars you have to add them too.
:: '''aPath''' - the path to the jar file as String.

=====boxedDo:aBlock=====
* Any autoboxed values in aBlock returned from the JavaVM are preserved as such. By default autoboxed values are automatically unboxed. This way, the identity of such objects is preserved.

=====isConnected=====
* Tests if a connection is still established.
:: '''return:''' - true if the connection is still established, else false.

=====isAlive=====
* Tests if a connection is still responding.
:: '''return:''' - true if the connection is still alive, else false. Does a message round trip.

=====closeBridge=====
* This will close the bridge connection. Depending on in which mode the JavaBridge was started, the JavaVM is also closed (-keepAlive startparameter not set).

=====exit=====
* Same as closeBridge.

== See Also==
The [[DOT NET Interface Library| DOTNET Interface Plugin & Library]], which implements a likewise interface for .NET applications/libraries.

<hr>
Back to [[Plugins]] 
Back to [[OnlineDocumentation#Library and Plugin Overview|Online Documentation]].

Java Interface Library v2

2016-05-31T15:26:07Z

Javogel:

== Introduction ==

The Java Interface library ("Java Bridge") is used to interact with Java objects inside an external Java Virtual Machine (JVM).

The access to Java objects, classes and programs is done via a framework called "''Java-Bridge''", which is similar in operation to the [[DOT NET Interface Library| dotNET bridge]]. This framework implements transparent forwarding of method (virtual function) calls to Java objects, which exist in a local or remote Java Virtual Machine (JVM). Also, return values, callBacks and exception information are passed back from the Java program to expecco. This is done by a proxy-object mechanism, which catches all function calls, wraps the arguments, sends a datagram to the other bridge side, awaits the reply and returns the result to the original caller. Thus, remote procedure calls are almost completely transparent to the Smalltalk/JavaScript code inside expecco. In your elementary code, you can write remote function calls as if they were to local objects.

Notice that this document describes the low level framework, which implements the bridge communication. A much easier to use high level interface (called "Groovy Blocks") exists and should normally be used, if you need access to a java application's internals during testing.
Please take a look at
[[Expecco_API#Groovy_Elementary_Blocks | "Groovy Block API"]]
and [[Testing Java Applications using Groovy blocks/en | "Testing Java Applications using Groovy blocks"]].

This article discusses version 2 of the Java Bridge. The article for version 1 can be found [[Java Interface Library | here]]

== Architecture ==

On the expecco side, the bridge consists of a number of Proxy objects,
which behave like regular Smalltalk objects as seen from elementary expecco code.
However, instead of performing an action when one of their methods (virtual functions) is called,
they send a message over a socket connection to the Java VM (actually: to a bridge software inside the
Java application) which decodes the message and sends it to the destination Java object.
The same is done in reverse direction with the return value.

+---------------------+ +----------+ +----------------+ +----------------+ +---------+
| | | | | | | | | Java |
| expecco |---->| Proxy |---->| Bridge |==>>==| Bridge |---->| Object |
| (elementary code) |<----| |<----| (expecco side) |==<<==| (Java side) |<----| |
+---------------------+ +----------+ +----------------+ +----------------+ +---------+

This setup allows for transparent communication with objects inside a local or remote Java VM. This may be either utility functions which happen to be convenient for the test application (for example: file parsing, syntax analysis, protocol implementaitons or access to specific hardware via driver libraries), or the tested application in the system under test itself.

Especially, it allows for the objects of the tested application to be looked into, manipulated and for functions of it or underlying frameworks to be called.

For expecco code, we tried to make this as transparent as possible, however there are a few exceptions, when function names need to be translated (for example, because the function naming syntax is different) or due to the fact that for some operations no corresponding name exists in Smalltalk (array access, for example).

Of course, multiple such connections can coexist and be served/handled in parallel. This enables an expecco test suite to communicate with both sides of a tested client-server Java application, for example.

Notice that a similar mechanism is used in expecco to communicate with DOTNET, Qt (C++) and C applications.

 

== Initializing / Releasing the Bridge ==

Before any communication can take place between expecco and any Java object, the Java side of the bridge has to be started, and a communication has to be established.
In expecco, all of the bridge classes are found in the <CODE>JAVA</CODE> namespace.

The main interface class is "<CODE>Java</CODE>", in the "<CODE>JAVA</CODE>" namespace:
<CODE><PRE>
java := JAVA::Java newWithServer.
</PRE></CODE>
or (in JavaScript):
<CODE><PRE>
java = JAVA::Java.newWithServer();
</PRE></CODE>

This starts the Java-side of the bridge (actually executes java as a background command) on the local machine, and establishes a connection to that JVM.

The bridge connection should be closed, if the bridge is no longer needed. Release the bridge with:
<CODE><PRE>
java.closeBridge();
</PRE></CODE>
which terminates the connection.

=== Start and Connect to a Remote Machine ===
The above started a Java VM and connected to it. Alternatively, you may want to connect to an already running Java program (typically, your system under test).
In order for your program to be reachable, it must allow for the bridge to connect to it via a special bridge-connection, which is a socket connection. For this, it must execute the server code found in the "JavaBridge.jar" file. To pass [[#Startup Parameters| parameters]] you will typically start it from a command line or a little shell/batch script.

Call (on the shell/cmd level):
$ java -jar <PATH_TO_JAVABRIDGE.JAR> <PARAMETERS>

The "JavaBridge.jar" file is found in the installation directory of expecco at:
\exept\expecco\packages\exept\bridgeFramework\javaBridge\javaBin\JavaBridge.jar

The Javabridge code allows for either side to initiate the connection - i.e. it can be run in server mode,
where it awaits an incoming connection, or in client mode, where it actively initiates a connection.
After connection establishment, there is no difference in the operation of the bridge, however depending on the setup of your network infrastructure, especially firewalls, either mechanism may be easier to be used.

Assuming that the bridge is already running on the remote machine as server (default),
use <CODE>newConnectedTo:port:withTimeout:</CODE> to connect to it from the expecco side:
java := JAVA::Java newConnectedTo:'myHost' port:4567 withTimeout:30.
This will initiate the connection setup from the expecco side.

Alternatively, if started in client mode use <CODE>newWaitingForConnectOnHost:port:withTimeout:</CODE>:
java := JAVA::Java newWaitingForConnectOnHost:'localhost' port:4567 withTimeout:30.
which will open a port on the expecco side, and wait until the Java side connects to it.
[[#JAVA::Java|For more details see API]]

====Startup Parameters====
You can use any parameter in any order.
If no parameter is used then the bridge listenes on port 14014 in server mode without keepAlive.
;<code>-help</code>
* Shows the help

;<code>-ip <aHostnameOrIP></code>
* In client mode this specifies the ip or hostname to connect to. In server mode this specifies the ip or hostname to bind to.

;<code>-port <aPortNumber> </code>
* In client mode this specifies the port to connect to. In server mode this specifies the listening port.

;<code>-asClient</code>
* The bridge will start in client mode. If not set the bridge is started in server mode.

;<code>-keepAlive</code>
* By setting this flag the bridge will not exit after the connection has closed and starts to connect or listen again. Otherwise, it will run for a single connection session only.

== Loading Applications (from the expecco side) ==

Normally, you would start your application with the required command line arguments and include the javabridge as jar there. However, in some situations, it may be required to dynamically load other jars into the connected Java VM.
By accessing a classloader, additional classes, or applications as contained in JAR files can be loaded from the expecco side.

This can be used to add a JAR file to the classloader:
<CODE><PRE>
java loadJarByPath:'pathToJarFile'. "/ assuming "java" is a handle as returned from the above connect
</PRE></CODE>

or, if the JAR file is loaded in memory:
<CODE><PRE>
java loadJar:jarByteArray. "/ where "jarByteArray" is a ByteArray containing the JAR file
</PRE></CODE>

If the JVM is on a remote machine, the path is resolved on the expecco side and the JAR will be transferred to the remote side.

Should transferring the JAR be too much overhead, an additional mechanism is provided:
<CODE><PRE>
java loadExtension:'pathToJarFile'.
</PRE></CODE>
this will cache the JAR file on the bridge side and eliminate the overhead of subsequent invocations.

== Java Class Access ==

This following code sample simply references (i.e. accesses) the class "JFrame" from the <CODE>"javax.swing"</CODE> package. The fully specified class name in Java would be <CODE>"javax.swing.JFrame"</CODE>:
<CODE><PRE>
java getJavaClass:'javax.swing.JFrame'
</PRE></CODE>

Or, if you want to load multiple classes:
<CODE><PRE>
java import:'javax.swing.JFrame' import:'javax.swing.JButton'
do:[:jFrame :jButton | "do something with JButton and JFrame" ].
</PRE></CODE>

v2 also supports dynamic compilation of java source code:
<CODE><PRE>
java getJavaClass:'className' fromSource:'classSource'. "/ where classSource is a String containing valid java source code
</PRE></CODE>

and loading precompiled java bytecode:
<CODE><PRE>
java getJavaClass:'className' fromByteCode:byteCode. "/ where byteCode is a ByteArray containing valid java bytecode
</PRE></CODE>

[[#Remote Dynamic Code Injection | for details see Remote Dynamic Code Injection]]

== Instantiating a Class ==

Object instances are created via the "new"-message, sent to a proxy of a Java class. You can get this proxy as described in the previous section. For example, if we want to create a new instance of a "JFrame" and a "JButton", write:
<CODE><PRE>
frame := java getJavaClass:'javax.swing.JFrame' new.
button := java getJavaClass:'javax.swing.JButton' new.
</PRE></CODE>
The first statement results in a proxy object for the "JFrame" instance. The second line results in a proxy for a new "JButton" object.

== Calling Instance Methods ==

A method call is done by a message send to a proxy object, where the message is the method name to call. For example, to call the <CODE>"setVisible(boolean isVisible)"</CODE> method on the above JFrame object, we send the following message to that proxy:
<CODE><PRE>
frame setVisible:true.
</PRE></CODE>

As method naming is different in Smalltalk and Java, a dynamic translation is applied when sending messages from Smalltalk code to a remote Java object. Smalltalk has arguments embedded inside parts of a so called "keyword" message, such as in "receiver foo:arg1 bar:arg2", where "foo:bar:" would be the message name, and "arg1", "arg2" be the arguments.

In Java, the message name is a single identifier, and arguments are written in an argument list after the message name: "receiver.fooBar(arg1, arg2)".

When message names are translated, only the very first part of the Smalltalk keyword message is taken ("foo" in the above example), and the remaining parts are simpl ignored. Thus, any of the Smalltalk messages "foo:bar:", "foo:xxxx:" and "foo:_:" (a single underscore as second part) all translate to the same Java message name "foo()".

Therefore, to call a method with more than one argument, like <CODE>"setSize(int width,int height)"</CODE> on a JFrame instance we can write:
<CODE><PRE>
frame setSize:300 _:200.
</PRE></CODE>
but just as well:
<CODE><PRE>
frame setSize:300 anyWord:200.
</PRE></CODE>
or any other selector with "setSize:" as its first component.
The selector translation mechanism simply takes the first part as the Java selector.

In practice, you should take a reasonably descriptive name, such as: "frame setSize:300 height:200" or only the Java name as first part, such as "frame setSize:300 _:200".

For a call of a method with 4 arguments, we could write:
<CODE><PRE>
frame setBounds:100 y:50 width:300 height:200.
</PRE></CODE>
or:
<CODE><PRE>
frame setBounds:100 _:50 _:300 _:200.
</PRE></CODE>

Also here the <CODE>"y: width: height:"</CODE> can be named as you want, but the first part must be "setBounds:".

=== Calling Static Methods ===

Calling a static method on an object is not different from calling non static methods. In most cases you will call a static method not on an object but directly on the class. This is done by using the class object as "receiver" of the message. For example, if we want to call the static method <CODE>"isDefaultLookAndFeelDecorated()"</CODE> of the JFrame class, write:
<CODE><PRE>
java getJavaClass:'javax.swing.JFrame' isDefaultLookAndFeelDecorated.
</PRE></CODE>

== Accessing Fields ==

As Smalltalk does not support access of an object's fields from the outside (it is fully encapsulated, and access from outside is ONLY allowed via getters/setters), an additional translation mechanism is provided for field access.

Accessing a field of a Java object or a class's static field uses the same syntax as method calls. To access a field, send a message where the message is the field name. To access the field of a class the field must be static.
For example, to get the value of the static field named <CODE>"EXIT_ON_CLOSE"</CODE> of the "JFrame" class, write
<CODE><PRE>
value := java getJavaClass:'javax.swing.JFrame' EXIT_ON_CLOSE.
</PRE></CODE>
The variable "value" now holds the integer value of the <CODE>"EXIT_ON_CLOSE"</CODE> constant.

Assuming that a "JFrame" object had a field named <CODE>"myField"</CODE>, to access this field, we'd have to write:
<CODE><PRE>
value := frame myField.
</PRE></CODE>
and "value" now holding whatever <CODE>"myField"</CODE> returns. This could be another object reference or any primitive value.

=== Setting Fields ===
To set a field, use a setter-like method call:
<CODE><PRE>
frame myField: newValue.
</PRE></CODE>

=== Name Conflicts ===

In very rare situations, a Java object may contain both a field and a method by the same name.
In this case, the Smalltalk code cannot depend on the dynamic translation mechanism (which actually looks for either a field or method name to match), but instead make it explicit, which operation is wanted:
Use:
<CODE><PRE>
frame getFieldByName:'myField'
</PRE></CODE>
to read a field, and:
<CODE><PRE>
frame setFieldByName:'myField' value:123.
</PRE></CODE>
to write the field.

If there are both fields and methods by the same name, and you use the non-explicit call,
the bridge will always assume that you want to call the getter/setter and perform a method call.
 

== Callbacks from Java ==
Sometimes you may want to execute a piece of Smalltalk code during the execution of the Java code. For example, we may want to install a Smalltalk observer to be notified when a button on a Java GUI was pressed,
or some other callback from a Java framework.

The following code registers a Smalltalk block as a callback for a mouse press event of a button:
<CODE><PRE>
listener := MouseListener new.
listener implementMethod:'mousePressed' as:[ Transcript showCR:'Hello from Java' ].
</PRE></CODE>
The above creates the callback and the listener, which can now be registered on a button:
<CODE><PRE>
button addMouseListener:listener.
</PRE></CODE>
Now, with the press of the button in the Java GUI, the Smalltalk block will be executed and writes <CODE>"Hello from Java"</CODE> to the Smalltalk console.
Of course, any other (Smalltalk-)action code can be made to run via this mechanism.

But be aware, that the callback is possibly called later (when the elementary action, which installed the code, has already finished long ago). Also, as the Java code execution is not synchronized with any of your expecco action execution, the callback may also be called at any arbutrary time, even at times when no activity at all is executed on the expecco side. If you forget to cleanup, and the Java object is still alive, it may even be called after you have finished your test run (if you keep the java bridge handle around and alive, for example in an expecoo environment variable).

So the Smalltalk callback code should not depend on any particular elementary action to be currently running, but instead in most cases write some information into a shared data container, preferably an instance of "SharedQueue", which is thread safe. Then, some other action (an elementary action) would read-wait and read events from that shared queue.

make sure that your test correctly cleans up any such callbacks afterwards. As a last resort, use the "Shutdown Bridge Connection" menu item, which closes the bridge connection, and thereby - as a side effect - removes any leftover callbacks. It does close the connection, and any remaining java proxy object handles become invalid, though.

Another example, using an observer could look like:
<CODE><PRE>
observer := java Observer new.
observer implementMethod:'update'
as:[:sourceObservable :argument|
argument notNil ifTrue:[ Transcript showCR:('I was notifyed with: ',argument toString) ]
ifFalse:[ Transcript showCR:'I was notifyed and the argument was nil' ].
].
myObservable addObserver:observer.
</PRE></CODE>
When the observable calls <CODE>"notifyObservers"</CODE>, the Smalltalk block will be executed.

== Exceptions in Java ==
Exceptions on the Java side are signalled back to the Smalltalk side and raise a corresponding exception there. However, on the Java side, the call stack which lead to the exception has already been unwound at that time (Java exceptions are not proceedable). So a proceed in the Smalltalk-side exception handler only affects the Smalltalk caller, but may leave the Java side in an undefined state.

== Remote Dynamic Code Injection ==
Sometimes we might want to execute code without the overhead of many rpc-messages being sent over the bridge, especially if we want to do something time critical, or want to make execution time measurements.
For this, it is possible to load a class at runtime into the JavaVM. The code of the class will first be sent to the JavaVM, which will compile and load the generated byte code. Then, the class can be accessed via the bridge just like any other preloaded class.

The following example specifies the class code in a smalltalk string and inject the code into the JavaVM. Then an instance of that new class will be instantiated and finally a method of the object instance will be invoked:
<CODE><PRE>
classCode := '
package myPackage.test;

import java.awt.BorderLayout;
import java.awt.event.MouseAdapter;
import java.awt.event.MouseEvent;
import java.util.Calendar;

import javax.swing.JButton;
import javax.swing.JFrame;
import javax.swing.JLabel;;

public class MyInjectedClass {
public void createSampleApp(){
JFrame frame=new JFrame("Hello im injected");
frame.setLayout(new BorderLayout());
JButton button=new JButton("click me");
final JLabel label=new JLabel("Text");
button.addMouseListener(new MouseAdapter() {

@Override
public void mouseClicked(MouseEvent e) {
label.setText(Calendar.getInstance().getTime().toString());
}
});
frame.add(label,BorderLayout.NORTH);
frame.add(button,BorderLayout.SOUTH);
frame.setSize(300, 300);
frame.setVisible(true);
}
}
'.
classObject := java getJavaClass:'myPackage.test.MyInjectedClass' fromSource:classCode.
classObject new createSampleApp.
</PRE></CODE>
After the code has been injected, a new instance of <CODE>"MyInjectedClass"</CODE> is created and the <CODE>"createSampleApp"</CODE> method is called. Because the example implements a GUI, a Java window will open, containing a label and a button. Clicking the button displays the current time in the label.



=== Code Sources for Class injection ===
There are 3 possible types of class code sources which we can use to inject the code. In the examples before we directly used a simple <CODE>"String"</CODE> in the smalltalk code as a code source. We also can use a <CODE>"*.java"</CODE> file as source. Just read the content of the file into a string and use it as in the previous examples.

To inject a <CODE>"*.class"</CODE> file use the following code:
<pre>
java getJavaClass:'the.class.name' fromByteCode:classCode.
</pre>

== Examples ==

This example creates a JFrame with one button inside. Then a Mouselistener is created and registered on the button. When the button is pressed, the title of the window changes to <CODE>"onPressed"</CODE> and the Transcript shows the message <CODE>"onPressed"</CODE>. When the button is released, the title of the window is changed to <CODE>"onReleased"</CODE> and the Transcript shows <CODE>"onReleased"</CODE>. If the button lost the mouse focus, the bridge will exit (disconnect), and the Java side is terminated.
<CODE><PRE>
|java frame button listener|

"/getting a bridge
java := JAVA::JavaBridge newWithServer.

"/creating a new frame and button object
frame := java getJavaClass:'javax.swing.JFrame' new.
button := java JButton new:'Click'.

"/creating a new mouse listener and adding callback blocks
listener := java MouseListener new.

listener implementMethod:'mousePressed' as:[ Transcript showCR:'onPress'. frame setTitle:'onPressed' ].
listener implementMethod:'mouseReleased' as:[ Transcript showCR:'onReleased'. frame setTitle:'onReleased' ].
listener implementMethod:'mouseExited' as:[ Transcript showCR:'onExited'. java closeBridge. ].

"/register the mouse listener on the button and make the frame with button visible
button addMouseListener:listener.
frame add:button.
frame setSize:300 y:100.
frame setVisible: true.
</PRE></CODE>



==Differences between v1 and v2==
===Loading Applications===
* '''addJarByPath:''' and '''addToClassPath:''' are still supported but have been deprecated. use '''loadJar:''', '''loadJarByPath:''' and '''loadExtension:''' instead. The new methods no longer require the jar or library to be present on the remote machine.

[[Java Interface Library#Loading Applications (from the expecco side) | v1]] [[#Loading Applications (from the expecco side) | v2]]

===Java Class Access===
* Sending the fully qualified name with instances of "." replaced by "_" to the bridge handle is still supported, but not recommended.
A new method '''getJavaClass:''' has been introduced. This solves the side effects of "_" being a legal character in class names.

[[Java Interface Library#Java Package Import and Class Access | v1]] [[#Java Class Access | v2]]
===Callbacks from Java===
* A new method '''implementMethod:as:''' has been introduced to assign callback blocks to method names. The old way is still supported.

[[Java Interface Library#Callbacks from Java | v1]] [[#Callbacks from Java | v2]]

===Remote Dynamic Code Injection===
* Code injection was problematic in v1 and has now been re-implemented in v2.

[[#Remote Dynamic Code Injection | v2]]

== API ==
===JAVA::Java===
====class protocol====
=====newWithServer=====
* This will start a local JavaVM, running the JavaBridge, and establishes a connection on a random free port.
: A new connected instance of JAVA::Java class is returned.

=====newWithServerForJavaPath:aJavaPathFilename=====
* This is the same as newWithServer but the path to the java executable can be specified. The JavaVM version must be 1.6 or higher to run the JavaBridge.
:: '''aJavaPathFilename''' - must be a instance of Filename
Smalltalk: JAVA::Java newWithServerForJavaPath:('my\path\to\java.executable'asFilename).
JavaScript: JAVA::Java.newWithServerForJavaPath("my\path\to\java.executable".asFilename());

=====newConnectedTo:aHhostString port:aPortNumber withTimeout:aTimeoutSeconds=====
* This is used to connect to a running JavaBridge on the network. The JavaBridge must be started in server mode on the remote host. After connecting a new connected instance of JAVA::Java is returned.
:: '''aHostString''' - the hostname or IP of the remote machine as String
:: '''aPortNumber ''' - the port on which the remote machine is listening as Number
:: '''aTimeoutSeconds''' - a connect timeout in seconds as Number
Smalltalk: JAVA::Java newConnectedTo:'myHostName' port:4567 withTimeout:30.
JavaScript: JAVA::Java.newConnectedTo_port_withTimeout("myHostName",4567,30);

=====newWaitingForConnectOnHost:aListeningAddressString port:aListeningPortNumber withTimeout:aTimeoutSeconds=====
* This is used to wait for incomming connecions of a running JavaBridge on the network. The JavaBridge must be started in client mode on the remote host. After connecting a new connected instance of JAVA::Java is returned.
:: '''deprecated: aListeningAddressString''' - no longer used. Can be nil.
:: '''aListeningPortNumber ''' - the port on which to listen for incomming connections as Number
:: '''aTimeoutSeconds''' - a connect timeout in seconds as Number, If nil it will wait endless.

=====singletonInstance=====
* This will call newWithServer for the first time and then always returns the same connected JAVA::Java instance until the connection was closed, then a new connected instance is returned.

=====exitAllInstances=====
* This will close all instances of JAVA::Java.

====instance protocol====
=====loadJarByPath:aPath=====
* Adds a jar to the running JavaVM. If the jar depends on other jars or libraries you have to add them too.
:: '''aPath''' - the path to the jar file as String.

=====loadJar:aByteArray=====
* Adds a jar to the running JavaVM. If the jar depends on other jars or libraries you have to add them too.
:: '''aByteArrays''' - a ByteArray containing the JAR file.

=====loadExtension:aPath=====
* Adds a jar to the running JavaVM and caches it for subsequent usages. If the jar depends on other jars you have to add them too.
:: '''aPath''' - the path to the jar file as String.

=====boxedDo:aBlock=====
* Any autoboxed values in aBlock returned from the JavaVM are preserved as such. By default autoboxed values are automatically unboxed. This way, the identity of such objects is preserved.

=====isConnected=====
* Tests if a connection is still established.
:: '''return:''' - true if the connection is still established, else false.

=====isAlive=====
* Tests if a connection is still responding.
:: '''return:''' - true if the connection is still alive, else false. Does a message round trip.

=====closeBridge=====
* This will close the bridge connection. Depending on in which mode the JavaBridge was started, the JavaVM is also closed (-keepAlive startparameter not set).

=====exit=====
* Same as closeBridge.

== See Also==
The [[DOT NET Interface Library| DOTNET Interface Plugin & Library]], which implements a likewise interface for .NET applications/libraries.

<hr>
Back to [[Plugins]] 
Back to [[OnlineDocumentation#Library and Plugin Overview|Online Documentation]].

Java Interface Library v2

2016-05-31T14:28:06Z

Javogel: /* Java Class Access */

== Introduction ==

The Java Interface library ("Java Bridge") is used to interact with Java objects inside an external Java Virtual Machine (JVM).

The access to Java objects, classes and programs is done via a framework called "''Java-Bridge''", which is similar in operation to the [[DOT NET Interface Library| dotNET bridge]]. This framework implements transparent forwarding of method (virtual function) calls to Java objects, which exist in a local or remote Java Virtual Machine (JVM). Also, return values, callBacks and exception information are passed back from the Java program to expecco. This is done by a proxy-object mechanism, which catches all function calls, wraps the arguments, sends a datagram to the other bridge side, awaits the reply and returns the result to the original caller. Thus, remote procedure calls are almost completely transparent to the Smalltalk/JavaScript code inside expecco. In your elementary code, you can write remote function calls as if they were to local objects.

Notice that this document describes the low level framework, which implements the bridge communication. A much easier to use high level interface (called "Groovy Blocks") exists and should normally be used, if you need access to a java application's internals during testing.
Please take a look at
[[Expecco_API#Groovy_Elementary_Blocks | "Groovy Block API"]]
and [[Testing Java Applications using Groovy blocks/en | "Testing Java Applications using Groovy blocks"]].

== Architecture ==

On the expecco side, the bridge consists of a number of Proxy objects,
which behave like regular Smalltalk objects as seen from elementary expecco code.
However, instead of performing an action when one of their methods (virtual functions) is called,
they send a message over a socket connection to the Java VM (actually: to a bridge software inside the
Java application) which decodes the message and sends it to the destination Java object.
The same is done in reverse direction with the return value.

+---------------------+ +----------+ +----------------+ +----------------+ +---------+
| | | | | | | | | Java |
| expecco |---->| Proxy |---->| Bridge |==>>==| Bridge |---->| Object |
| (elementary code) |<----| |<----| (expecco side) |==<<==| (Java side) |<----| |
+---------------------+ +----------+ +----------------+ +----------------+ +---------+

This setup allows for transparent communication with objects inside a local or remote Java VM. This may be either utility functions which happen to be convenient for the test application (for example: file parsing, syntax analysis, protocol implementaitons or access to specific hardware via driver libraries), or the tested application in the system under test itself.

Especially, it allows for the objects of the tested application to be looked into, manipulated and for functions of it or underlying frameworks to be called.

For expecco code, we tried to make this as transparent as possible, however there are a few exceptions, when function names need to be translated (for example, because the function naming syntax is different) or due to the fact that for some operations no corresponding name exists in Smalltalk (array access, for example).

Of course, multiple such connections can coexist and be served/handled in parallel. This enables an expecco test suite to communicate with both sides of a tested client-server Java application, for example.

Notice that a similar mechanism is used in expecco to communicate with DOTNET, Qt (C++) and C applications.

 

== Initializing / Releasing the Bridge ==

Before any communication can take place between expecco and any Java object, the Java side of the bridge has to be started, and a communication has to be established.
In expecco, all of the bridge classes are found in the <CODE>JAVA</CODE> namespace.

The main interface class is "<CODE>Java</CODE>", in the "<CODE>JAVA</CODE>" namespace:
<CODE><PRE>
java := JAVA::Java newWithServer.
</PRE></CODE>
or (in JavaScript):
<CODE><PRE>
java = JAVA::Java.newWithServer();
</PRE></CODE>

This starts the Java-side of the bridge (actually executes java as a background command) on the local machine, and establishes a connection to that JVM.

The bridge connection should be closed, if the bridge is no longer needed. Release the bridge with:
<CODE><PRE>
java.closeBridge();
</PRE></CODE>
which terminates the connection.

=== Start and Connect to a Remote Machine ===
The above started a Java VM and connected to it. Alternatively, you may want to connect to an already running Java program (typically, your system under test).
In order for your program to be reachable, it must allow for the bridge to connect to it via a special bridge-connection, which is a socket connection. For this, it must execute the server code found in the "JavaBridge.jar" file. To pass [[#Startup Parameters| parameters]] you will typically start it from a command line or a little shell/batch script.

Call (on the shell/cmd level):
$ java -jar <PATH_TO_JAVABRIDGE.JAR> <PARAMETERS>

The "JavaBridge.jar" file is found in the installation directory of expecco at:
\exept\expecco\packages\exept\bridgeFramework\javaBridge\javaBin\JavaBridge.jar

The Javabridge code allows for either side to initiate the connection - i.e. it can be run in server mode,
where it awaits an incoming connection, or in client mode, where it actively initiates a connection.
After connection establishment, there is no difference in the operation of the bridge, however depending on the setup of your network infrastructure, especially firewalls, either mechanism may be easier to be used.

Assuming that the bridge is already running on the remote machine as server (default),
use <CODE>newConnectedTo:port:withTimeout:</CODE> to connect to it from the expecco side:
java := JAVA::Java newConnectedTo:'myHost' port:4567 withTimeout:30.
This will initiate the connection setup from the expecco side.

Alternatively, if started in client mode use <CODE>newWaitingForConnectOnHost:port:withTimeout:</CODE>:
java := JAVA::Java newWaitingForConnectOnHost:'localhost' port:4567 withTimeout:30.
which will open a port on the expecco side, and wait until the Java side connects to it.
[[#JAVA::Java|For more details see API]]

====Startup Parameters====
You can use any parameter in any order.
If no parameter is used then the bridge listenes on port 14014 in server mode without keepAlive.
;<code>-help</code>
* Shows the help

;<code>-ip <aHostnameOrIP></code>
* In client mode this specifies the ip or hostname to connect to. In server mode this specifies the ip or hostname to bind to.

;<code>-port <aPortNumber> </code>
* In client mode this specifies the port to connect to. In server mode this specifies the listening port.

;<code>-asClient</code>
* The bridge will start in client mode. If not set the bridge is started in server mode.

;<code>-keepAlive</code>
* By setting this flag the bridge will not exit after the connection has closed and starts to connect or listen again. Otherwise, it will run for a single connection session only.

== Loading Applications (from the expecco side) ==

Normally, you would start your application with the required command line arguments and include the javabridge as jar there. However, in some situations, it may be required to dynamically load other jars into the connected Java VM.
By accessing a classloader, additional classes, or applications as contained in JAR files can be loaded from the expecco side.

This can be used to add a JAR file to the classloader:
<CODE><PRE>
java loadJarByPath:'pathToJarFile'. "/ assuming "java" is a handle as returned from the above connect
</PRE></CODE>

or, if the JAR file is loaded in memory:
<CODE><PRE>
java loadJar:jarByteArray. "/ where "jarByteArray" is a ByteArray containing the JAR file
</PRE></CODE>

If the JVM is on a remote machine, the path is resolved on the expecco side and the JAR will be transferred to the remote side.

Should transferring the JAR be too much overhead, an additional mechanism is provided:
<CODE><PRE>
java loadExtension:'pathToJarFile'.
</PRE></CODE>
this will cache the JAR file on the bridge side and eliminate the overhead of subsequent invocations.

== Java Class Access ==

This following code sample simply references (i.e. accesses) the class "JFrame" from the <CODE>"javax.swing"</CODE> package. The fully specified class name in Java would be <CODE>"javax.swing.JFrame"</CODE>:
<CODE><PRE>
java getJavaClass:'javax.swing.JFrame'
</PRE></CODE>

Or, if you want to load multiple classes:
<CODE><PRE>
java import:'javax.swing.JFrame' import:'javax.swing.JButton'
do:[:jFrame :jButton | "do something with JButton and JFrame" ].
</PRE></CODE>

v2 also supports dynamic compilation of java source code:
<CODE><PRE>
java getJavaClass:'className' fromSource:'classSource'. "/ where classSource is a String containing valid java source code
</PRE></CODE>

and loading precompiled java bytecode:
<CODE><PRE>
java getJavaClass:'className' fromByteCode:byteCode. "/ where byteCode is a ByteArray containing valid java bytecode
</PRE></CODE>

== Instantiating a Class ==

Object instances are created via the "new"-message, sent to a proxy of a Java class. You can get this proxy as described in the previous section. For example, if we want to create a new instance of a "JFrame" and a "JButton", write:
<CODE><PRE>
frame := java getJavaClass:'javax.swing.JFrame' new.
button := java getJavaClass:'javax.swing.JButton' new.
</PRE></CODE>
The first statement results in a proxy object for the "JFrame" instance. The second line results in a proxy for a new "JButton" object.

== Calling Instance Methods ==

A method call is done by a message send to a proxy object, where the message is the method name to call. For example, to call the <CODE>"setVisible(boolean isVisible)"</CODE> method on the above JFrame object, we send the following message to that proxy:
<CODE><PRE>
frame setVisible:true.
</PRE></CODE>

As method naming is different in Smalltalk and Java, a dynamic translation is applied when sending messages from Smalltalk code to a remote Java object. Smalltalk has arguments embedded inside parts of a so called "keyword" message, such as in "receiver foo:arg1 bar:arg2", where "foo:bar:" would be the message name, and "arg1", "arg2" be the arguments.

In Java, the message name is a single identifier, and arguments are written in an argument list after the message name: "receiver.fooBar(arg1, arg2)".

When message names are translated, only the very first part of the Smalltalk keyword message is taken ("foo" in the above example), and the remaining parts are simpl ignored. Thus, any of the Smalltalk messages "foo:bar:", "foo:xxxx:" and "foo:_:" (a single underscore as second part) all translate to the same Java message name "foo()".

Therefore, to call a method with more than one argument, like <CODE>"setSize(int width,int height)"</CODE> on a JFrame instance we can write:
<CODE><PRE>
frame setSize:300 _:200.
</PRE></CODE>
but just as well:
<CODE><PRE>
frame setSize:300 anyWord:200.
</PRE></CODE>
or any other selector with "setSize:" as its first component.
The selector translation mechanism simply takes the first part as the Java selector.

In practice, you should take a reasonably descriptive name, such as: "frame setSize:300 height:200" or only the Java name as first part, such as "frame setSize:300 _:200".

For a call of a method with 4 arguments, we could write:
<CODE><PRE>
frame setBounds:100 y:50 width:300 height:200.
</PRE></CODE>
or:
<CODE><PRE>
frame setBounds:100 _:50 _:300 _:200.
</PRE></CODE>

Also here the <CODE>"y: width: height:"</CODE> can be named as you want, but the first part must be "setBounds:".

=== Calling Static Methods ===

Calling a static method on an object is not different from calling non static methods. In most cases you will call a static method not on an object but directly on the class. This is done by using the class object as "receiver" of the message. For example, if we want to call the static method <CODE>"isDefaultLookAndFeelDecorated()"</CODE> of the JFrame class, write:
<CODE><PRE>
java getJavaClass:'javax.swing.JFrame' isDefaultLookAndFeelDecorated.
</PRE></CODE>

== Accessing Fields ==

As Smalltalk does not support access of an object's fields from the outside (it is fully encapsulated, and access from outside is ONLY allowed via getters/setters), an additional translation mechanism is provided for field access.

Accessing a field of a Java object or a class's static field uses the same syntax as method calls. To access a field, send a message where the message is the field name. To access the field of a class the field must be static.
For example, to get the value of the static field named <CODE>"EXIT_ON_CLOSE"</CODE> of the "JFrame" class, write
<CODE><PRE>
value := java getJavaClass:'javax.swing.JFrame' EXIT_ON_CLOSE.
</PRE></CODE>
The variable "value" now holds the integer value of the <CODE>"EXIT_ON_CLOSE"</CODE> constant.

Assuming that a "JFrame" object had a field named <CODE>"myField"</CODE>, to access this field, we'd have to write:
<CODE><PRE>
value := frame myField.
</PRE></CODE>
and "value" now holding whatever <CODE>"myField"</CODE> returns. This could be another object reference or any primitive value.

=== Setting Fields ===
To set a field, use a setter-like method call:
<CODE><PRE>
frame myField: newValue.
</PRE></CODE>

=== Name Conflicts ===

In very rare situations, a Java object may contain both a field and a method by the same name.
In this case, the Smalltalk code cannot depend on the dynamic translation mechanism (which actually looks for either a field or method name to match), but instead make it explicit, which operation is wanted:
Use:
<CODE><PRE>
frame getFieldByName:'myField'
</PRE></CODE>
to read a field, and:
<CODE><PRE>
frame setFieldByName:'myField' value:123.
</PRE></CODE>
to write the field.

If there are both fields and methods by the same name, and you use the non-explicit call,
the bridge will always assume that you want to call the getter/setter and perform a method call.
 

== Callbacks from Java ==
Sometimes you may want to execute a piece of Smalltalk code during the execution of the Java code. For example, we may want to install a Smalltalk observer to be notified when a button on a Java GUI was pressed,
or some other callback from a Java framework.

The following code registers a Smalltalk block as a callback for a mouse press event of a button:
<CODE><PRE>
listener := MouseListener new.
listener implementMethod:'mousePressed' as:[ Transcript showCR:'Hello from Java' ].
</PRE></CODE>
The above creates the callback and the listener, which can now be registered on a button:
<CODE><PRE>
button addMouseListener:listener.
</PRE></CODE>
Now, with the press of the button in the Java GUI, the Smalltalk block will be executed and writes <CODE>"Hello from Java"</CODE> to the Smalltalk console.
Of course, any other (Smalltalk-)action code can be made to run via this mechanism.

But be aware, that the callback is possibly called later (when the elementary action, which installed the code, has already finished long ago). Also, as the Java code execution is not synchronized with any of your expecco action execution, the callback may also be called at any arbutrary time, even at times when no activity at all is executed on the expecco side. If you forget to cleanup, and the Java object is still alive, it may even be called after you have finished your test run (if you keep the java bridge handle around and alive, for example in an expecoo environment variable).

So the Smalltalk callback code should not depend on any particular elementary action to be currently running, but instead in most cases write some information into a shared data container, preferably an instance of "SharedQueue", which is thread safe. Then, some other action (an elementary action) would read-wait and read events from that shared queue.

make sure that your test correctly cleans up any such callbacks afterwards. As a last resort, use the "Shutdown Bridge Connection" menu item, which closes the bridge connection, and thereby - as a side effect - removes any leftover callbacks. It does close the connection, and any remaining java proxy object handles become invalid, though.

Another example, using an observer could look like:
<CODE><PRE>
observer := java Observer new.
observer implementMethod:'update'
as:[:sourceObservable :argument|
argument notNil ifTrue:[ Transcript showCR:('I was notifyed with: ',argument toString) ]
ifFalse:[ Transcript showCR:'I was notifyed and the argument was nil' ].
].
myObservable addObserver:observer.
</PRE></CODE>
When the observable calls <CODE>"notifyObservers"</CODE>, the Smalltalk block will be executed.

== Exceptions in Java ==
Exceptions on the Java side are signalled back to the Smalltalk side and raise a corresponding exception there. However, on the Java side, the call stack which lead to the exception has already been unwound at that time (Java exceptions are not proceedable). So a proceed in the Smalltalk-side exception handler only affects the Smalltalk caller, but may leave the Java side in an undefined state.

== Remote Dynamic Code Injection ==
Sometimes we might want to execute code without the overhead of many rpc-messages being sent over the bridge, especially if we want to do something time critical, or want to make execution time measurements.
For this, it is possible to load a class at runtime into the JavaVM. The code of the class will first be sent to the JavaVM, which will compile and load the generated byte code. Then, the class can be accessed via the bridge just like any other preloaded class.

The following example specifies the class code in a smalltalk string and inject the code into the JavaVM. Then an instance of that new class will be instantiated and finally a method of the object instance will be invoked:
<CODE><PRE>
classCode := '
package myPackage.test;

import java.awt.BorderLayout;
import java.awt.event.MouseAdapter;
import java.awt.event.MouseEvent;
import java.util.Calendar;

import javax.swing.JButton;
import javax.swing.JFrame;
import javax.swing.JLabel;;

public class MyInjectedClass {
public void createSampleApp(){
JFrame frame=new JFrame("Hello im injected");
frame.setLayout(new BorderLayout());
JButton button=new JButton("click me");
final JLabel label=new JLabel("Text");
button.addMouseListener(new MouseAdapter() {

@Override
public void mouseClicked(MouseEvent e) {
label.setText(Calendar.getInstance().getTime().toString());
}
});
frame.add(label,BorderLayout.NORTH);
frame.add(button,BorderLayout.SOUTH);
frame.setSize(300, 300);
frame.setVisible(true);
}
}
'.
classObject := java getJavaClass:'myPackage.test.MyInjectedClass' fromSource:classCode.
classObject new createSampleApp.
</PRE></CODE>
After the code has been injected, a new instance of <CODE>"MyInjectedClass"</CODE> is created and the <CODE>"createSampleApp"</CODE> method is called. Because the example implements a GUI, a Java window will open, containing a label and a button. Clicking the button displays the current time in the label.



=== Code Sources for Class injection ===
There are 3 possible types of class code sources which we can use to inject the code. In the examples before we directly used a simple <CODE>"String"</CODE> in the smalltalk code as a code source. We also can use a <CODE>"*.java"</CODE> file as source. Just read the content of the file into a string and use it as in the previous examples.

To inject a <CODE>"*.class"</CODE> file use the following code:
<pre>
java getJavaClass:'the.class.name' fromByteCode:classCode.
</pre>

== Examples ==

This example creates a JFrame with one button inside. Then a Mouselistener is created and registered on the button. When the button is pressed, the title of the window changes to <CODE>"onPressed"</CODE> and the Transcript shows the message <CODE>"onPressed"</CODE>. When the button is released, the title of the window is changed to <CODE>"onReleased"</CODE> and the Transcript shows <CODE>"onReleased"</CODE>. If the button lost the mouse focus, the bridge will exit (disconnect), and the Java side is terminated.
<CODE><PRE>
|java frame button listener|

"/getting a bridge
java := JAVA::JavaBridge newWithServer.

"/creating a new frame and button object
frame := java getJavaClass:'javax.swing.JFrame' new.
button := java JButton new:'Click'.

"/creating a new mouse listener and adding callback blocks
listener := java MouseListener new.

listener implementMethod:'mousePressed' as:[ Transcript showCR:'onPress'. frame setTitle:'onPressed' ].
listener implementMethod:'mouseReleased' as:[ Transcript showCR:'onReleased'. frame setTitle:'onReleased' ].
listener implementMethod:'mouseExited' as:[ Transcript showCR:'onExited'. java closeBridge. ].

"/register the mouse listener on the button and make the frame with button visible
button addMouseListener:listener.
frame add:button.
frame setSize:300 y:100.
frame setVisible: true.
</PRE></CODE>



== API ==
===JAVA::Java===
====class protocol====
=====newWithServer=====
* This will start a local JavaVM, running the JavaBridge, and establishes a connection on a random free port.
: A new connected instance of JAVA::Java class is returned.

=====newWithServerForJavaPath:aJavaPathFilename=====
* This is the same as newWithServer but the path to the java executable can be specified. The JavaVM version must be 1.6 or higher to run the JavaBridge.
:: '''aJavaPathFilename''' - must be a instance of Filename
Smalltalk: JAVA::Java newWithServerForJavaPath:('my\path\to\java.executable'asFilename).
JavaScript: JAVA::Java.newWithServerForJavaPath("my\path\to\java.executable".asFilename());

=====newConnectedTo:aHhostString port:aPortNumber withTimeout:aTimeoutSeconds=====
* This is used to connect to a running JavaBridge on the network. The JavaBridge must be started in server mode on the remote host. After connecting a new connected instance of JAVA::Java is returned.
:: '''aHostString''' - the hostname or IP of the remote machine as String
:: '''aPortNumber ''' - the port on which the remote machine is listening as Number
:: '''aTimeoutSeconds''' - a connect timeout in seconds as Number
Smalltalk: JAVA::Java newConnectedTo:'myHostName' port:4567 withTimeout:30.
JavaScript: JAVA::Java.newConnectedTo_port_withTimeout("myHostName",4567,30);

=====newWaitingForConnectOnHost:aListeningAddressString port:aListeningPortNumber withTimeout:aTimeoutSeconds=====
* This is used to wait for incomming connecions of a running JavaBridge on the network. The JavaBridge must be started in client mode on the remote host. After connecting a new connected instance of JAVA::Java is returned.
:: '''deprecated: aListeningAddressString''' - no longer used. Can be nil.
:: '''aListeningPortNumber ''' - the port on which to listen for incomming connections as Number
:: '''aTimeoutSeconds''' - a connect timeout in seconds as Number, If nil it will wait endless.

=====singletonInstance=====
* This will call newWithServer for the first time and then always returns the same connected JAVA::Java instance until the connection was closed, then a new connected instance is returned.

=====exitAllInstances=====
* This will close all instances of JAVA::Java.

====instance protocol====
=====loadJarByPath:aPath=====
* Adds a jar to the running JavaVM. If the jar depends on other jars or libraries you have to add them too.
:: '''aPath''' - the path to the jar file as String.

=====loadJar:aByteArray=====
* Adds a jar to the running JavaVM. If the jar depends on other jars or libraries you have to add them too.
:: '''aByteArrays''' - a ByteArray containing the JAR file.

=====loadExtension:aPath=====
* Adds a jar to the running JavaVM and caches it for subsequent usages. If the jar depends on other jars you have to add them too.
:: '''aPath''' - the path to the jar file as String.

=====boxedDo:aBlock=====
* Any autoboxed values in aBlock returned from the JavaVM are preserved as such. By default autoboxed values are automatically unboxed. This way, the identity of such objects is preserved.

=====isConnected=====
* Tests if a connection is still established.
:: '''return:''' - true if the connection is still established, else false.

=====isAlive=====
* Tests if a connection is still responding.
:: '''return:''' - true if the connection is still alive, else false. Does a message round trip.

=====closeBridge=====
* This will close the bridge connection. Depending on in which mode the JavaBridge was started, the JavaVM is also closed (-keepAlive startparameter not set).

=====exit=====
* Same as closeBridge.

== See Also==
The [[DOT NET Interface Library| DOTNET Interface Plugin & Library]], which implements a likewise interface for .NET applications/libraries.

<hr>
Back to [[Plugins]] 
Back to [[OnlineDocumentation#Library and Plugin Overview|Online Documentation]].

Java Interface Library v2

2016-05-31T14:25:59Z

Javogel: Die Seite wurde neu angelegt: „== Introduction == The Java Interface library ("Java Bridge") is used to interact with Java objects inside an external Java Virtual Machine (JVM). The access…“

== Introduction ==

The Java Interface library ("Java Bridge") is used to interact with Java objects inside an external Java Virtual Machine (JVM).

The access to Java objects, classes and programs is done via a framework called "''Java-Bridge''", which is similar in operation to the [[DOT NET Interface Library| dotNET bridge]]. This framework implements transparent forwarding of method (virtual function) calls to Java objects, which exist in a local or remote Java Virtual Machine (JVM). Also, return values, callBacks and exception information are passed back from the Java program to expecco. This is done by a proxy-object mechanism, which catches all function calls, wraps the arguments, sends a datagram to the other bridge side, awaits the reply and returns the result to the original caller. Thus, remote procedure calls are almost completely transparent to the Smalltalk/JavaScript code inside expecco. In your elementary code, you can write remote function calls as if they were to local objects.

Notice that this document describes the low level framework, which implements the bridge communication. A much easier to use high level interface (called "Groovy Blocks") exists and should normally be used, if you need access to a java application's internals during testing.
Please take a look at
[[Expecco_API#Groovy_Elementary_Blocks | "Groovy Block API"]]
and [[Testing Java Applications using Groovy blocks/en | "Testing Java Applications using Groovy blocks"]].

== Architecture ==

On the expecco side, the bridge consists of a number of Proxy objects,
which behave like regular Smalltalk objects as seen from elementary expecco code.
However, instead of performing an action when one of their methods (virtual functions) is called,
they send a message over a socket connection to the Java VM (actually: to a bridge software inside the
Java application) which decodes the message and sends it to the destination Java object.
The same is done in reverse direction with the return value.

+---------------------+ +----------+ +----------------+ +----------------+ +---------+
| | | | | | | | | Java |
| expecco |---->| Proxy |---->| Bridge |==>>==| Bridge |---->| Object |
| (elementary code) |<----| |<----| (expecco side) |==<<==| (Java side) |<----| |
+---------------------+ +----------+ +----------------+ +----------------+ +---------+

This setup allows for transparent communication with objects inside a local or remote Java VM. This may be either utility functions which happen to be convenient for the test application (for example: file parsing, syntax analysis, protocol implementaitons or access to specific hardware via driver libraries), or the tested application in the system under test itself.

Especially, it allows for the objects of the tested application to be looked into, manipulated and for functions of it or underlying frameworks to be called.

For expecco code, we tried to make this as transparent as possible, however there are a few exceptions, when function names need to be translated (for example, because the function naming syntax is different) or due to the fact that for some operations no corresponding name exists in Smalltalk (array access, for example).

Of course, multiple such connections can coexist and be served/handled in parallel. This enables an expecco test suite to communicate with both sides of a tested client-server Java application, for example.

Notice that a similar mechanism is used in expecco to communicate with DOTNET, Qt (C++) and C applications.

 

== Initializing / Releasing the Bridge ==

Before any communication can take place between expecco and any Java object, the Java side of the bridge has to be started, and a communication has to be established.
In expecco, all of the bridge classes are found in the <CODE>JAVA</CODE> namespace.

The main interface class is "<CODE>Java</CODE>", in the "<CODE>JAVA</CODE>" namespace:
<CODE><PRE>
java := JAVA::Java newWithServer.
</PRE></CODE>
or (in JavaScript):
<CODE><PRE>
java = JAVA::Java.newWithServer();
</PRE></CODE>

This starts the Java-side of the bridge (actually executes java as a background command) on the local machine, and establishes a connection to that JVM.

The bridge connection should be closed, if the bridge is no longer needed. Release the bridge with:
<CODE><PRE>
java.closeBridge();
</PRE></CODE>
which terminates the connection.

=== Start and Connect to a Remote Machine ===
The above started a Java VM and connected to it. Alternatively, you may want to connect to an already running Java program (typically, your system under test).
In order for your program to be reachable, it must allow for the bridge to connect to it via a special bridge-connection, which is a socket connection. For this, it must execute the server code found in the "JavaBridge.jar" file. To pass [[#Startup Parameters| parameters]] you will typically start it from a command line or a little shell/batch script.

Call (on the shell/cmd level):
$ java -jar <PATH_TO_JAVABRIDGE.JAR> <PARAMETERS>

The "JavaBridge.jar" file is found in the installation directory of expecco at:
\exept\expecco\packages\exept\bridgeFramework\javaBridge\javaBin\JavaBridge.jar

The Javabridge code allows for either side to initiate the connection - i.e. it can be run in server mode,
where it awaits an incoming connection, or in client mode, where it actively initiates a connection.
After connection establishment, there is no difference in the operation of the bridge, however depending on the setup of your network infrastructure, especially firewalls, either mechanism may be easier to be used.

Assuming that the bridge is already running on the remote machine as server (default),
use <CODE>newConnectedTo:port:withTimeout:</CODE> to connect to it from the expecco side:
java := JAVA::Java newConnectedTo:'myHost' port:4567 withTimeout:30.
This will initiate the connection setup from the expecco side.

Alternatively, if started in client mode use <CODE>newWaitingForConnectOnHost:port:withTimeout:</CODE>:
java := JAVA::Java newWaitingForConnectOnHost:'localhost' port:4567 withTimeout:30.
which will open a port on the expecco side, and wait until the Java side connects to it.
[[#JAVA::Java|For more details see API]]

====Startup Parameters====
You can use any parameter in any order.
If no parameter is used then the bridge listenes on port 14014 in server mode without keepAlive.
;<code>-help</code>
* Shows the help

;<code>-ip <aHostnameOrIP></code>
* In client mode this specifies the ip or hostname to connect to. In server mode this specifies the ip or hostname to bind to.

;<code>-port <aPortNumber> </code>
* In client mode this specifies the port to connect to. In server mode this specifies the listening port.

;<code>-asClient</code>
* The bridge will start in client mode. If not set the bridge is started in server mode.

;<code>-keepAlive</code>
* By setting this flag the bridge will not exit after the connection has closed and starts to connect or listen again. Otherwise, it will run for a single connection session only.

== Loading Applications (from the expecco side) ==

Normally, you would start your application with the required command line arguments and include the javabridge as jar there. However, in some situations, it may be required to dynamically load other jars into the connected Java VM.
By accessing a classloader, additional classes, or applications as contained in JAR files can be loaded from the expecco side.

This can be used to add a JAR file to the classloader:
<CODE><PRE>
java loadJarByPath:'pathToJarFile'. "/ assuming "java" is a handle as returned from the above connect
</PRE></CODE>

or, if the JAR file is loaded in memory:
<CODE><PRE>
java loadJar:jarByteArray. "/ where "jarByteArray" is a ByteArray containing the JAR file
</PRE></CODE>

If the JVM is on a remote machine, the path is resolved on the expecco side and the JAR will be transferred to the remote side.

Should transferring the JAR be too much overhead, an additional mechanism is provided:
<CODE><PRE>
java loadExtension:'pathToJarFile'.
</PRE></CODE>
this will cache the JAR file on the bridge side and eliminate the overhead of subsequent invocations.

== Java Class Access ==

This following code sample simply references (i.e. accesses) the class "JFrame" from the <CODE>"javax.swing"</CODE> package. The fully specified class name in Java would be <CODE>"javax.swing.JFrame"</CODE>:
<CODE><PRE>
java getJavaClass:'javax.swing.JFrame'
</PRE></CODE>

Or, if you want to load multiple classes:
<CODE><PRE>
java import:'javax.swing.JFrame' import:'javax.swing.JButton'
do:[:jFrame :jButton | "do something with JButton and JFrame" ].
</PRE></CODE>

v2 also supports dynamic compilation of java source code:
<CODE><PRE>
java getJavaClass:'className' fromSource:'classSource'. "/ where classSource is a String containing valid java source code
</PRE></CODE>

and loading already compiled java byte code:
<CODE><PRE>
java getJavaClass:'className' fromByteCode:byteCode. "/ where byteCode is a ByteArray containing valid java byte code
</PRE></CODE>

== Instantiating a Class ==

Object instances are created via the "new"-message, sent to a proxy of a Java class. You can get this proxy as described in the previous section. For example, if we want to create a new instance of a "JFrame" and a "JButton", write:
<CODE><PRE>
frame := java getJavaClass:'javax.swing.JFrame' new.
button := java getJavaClass:'javax.swing.JButton' new.
</PRE></CODE>
The first statement results in a proxy object for the "JFrame" instance. The second line results in a proxy for a new "JButton" object.

== Calling Instance Methods ==

A method call is done by a message send to a proxy object, where the message is the method name to call. For example, to call the <CODE>"setVisible(boolean isVisible)"</CODE> method on the above JFrame object, we send the following message to that proxy:
<CODE><PRE>
frame setVisible:true.
</PRE></CODE>

As method naming is different in Smalltalk and Java, a dynamic translation is applied when sending messages from Smalltalk code to a remote Java object. Smalltalk has arguments embedded inside parts of a so called "keyword" message, such as in "receiver foo:arg1 bar:arg2", where "foo:bar:" would be the message name, and "arg1", "arg2" be the arguments.

In Java, the message name is a single identifier, and arguments are written in an argument list after the message name: "receiver.fooBar(arg1, arg2)".

When message names are translated, only the very first part of the Smalltalk keyword message is taken ("foo" in the above example), and the remaining parts are simpl ignored. Thus, any of the Smalltalk messages "foo:bar:", "foo:xxxx:" and "foo:_:" (a single underscore as second part) all translate to the same Java message name "foo()".

Therefore, to call a method with more than one argument, like <CODE>"setSize(int width,int height)"</CODE> on a JFrame instance we can write:
<CODE><PRE>
frame setSize:300 _:200.
</PRE></CODE>
but just as well:
<CODE><PRE>
frame setSize:300 anyWord:200.
</PRE></CODE>
or any other selector with "setSize:" as its first component.
The selector translation mechanism simply takes the first part as the Java selector.

In practice, you should take a reasonably descriptive name, such as: "frame setSize:300 height:200" or only the Java name as first part, such as "frame setSize:300 _:200".

For a call of a method with 4 arguments, we could write:
<CODE><PRE>
frame setBounds:100 y:50 width:300 height:200.
</PRE></CODE>
or:
<CODE><PRE>
frame setBounds:100 _:50 _:300 _:200.
</PRE></CODE>

Also here the <CODE>"y: width: height:"</CODE> can be named as you want, but the first part must be "setBounds:".

=== Calling Static Methods ===

Calling a static method on an object is not different from calling non static methods. In most cases you will call a static method not on an object but directly on the class. This is done by using the class object as "receiver" of the message. For example, if we want to call the static method <CODE>"isDefaultLookAndFeelDecorated()"</CODE> of the JFrame class, write:
<CODE><PRE>
java getJavaClass:'javax.swing.JFrame' isDefaultLookAndFeelDecorated.
</PRE></CODE>

== Accessing Fields ==

As Smalltalk does not support access of an object's fields from the outside (it is fully encapsulated, and access from outside is ONLY allowed via getters/setters), an additional translation mechanism is provided for field access.

Accessing a field of a Java object or a class's static field uses the same syntax as method calls. To access a field, send a message where the message is the field name. To access the field of a class the field must be static.
For example, to get the value of the static field named <CODE>"EXIT_ON_CLOSE"</CODE> of the "JFrame" class, write
<CODE><PRE>
value := java getJavaClass:'javax.swing.JFrame' EXIT_ON_CLOSE.
</PRE></CODE>
The variable "value" now holds the integer value of the <CODE>"EXIT_ON_CLOSE"</CODE> constant.

Assuming that a "JFrame" object had a field named <CODE>"myField"</CODE>, to access this field, we'd have to write:
<CODE><PRE>
value := frame myField.
</PRE></CODE>
and "value" now holding whatever <CODE>"myField"</CODE> returns. This could be another object reference or any primitive value.

=== Setting Fields ===
To set a field, use a setter-like method call:
<CODE><PRE>
frame myField: newValue.
</PRE></CODE>

=== Name Conflicts ===

In very rare situations, a Java object may contain both a field and a method by the same name.
In this case, the Smalltalk code cannot depend on the dynamic translation mechanism (which actually looks for either a field or method name to match), but instead make it explicit, which operation is wanted:
Use:
<CODE><PRE>
frame getFieldByName:'myField'
</PRE></CODE>
to read a field, and:
<CODE><PRE>
frame setFieldByName:'myField' value:123.
</PRE></CODE>
to write the field.

If there are both fields and methods by the same name, and you use the non-explicit call,
the bridge will always assume that you want to call the getter/setter and perform a method call.
 

== Callbacks from Java ==
Sometimes you may want to execute a piece of Smalltalk code during the execution of the Java code. For example, we may want to install a Smalltalk observer to be notified when a button on a Java GUI was pressed,
or some other callback from a Java framework.

The following code registers a Smalltalk block as a callback for a mouse press event of a button:
<CODE><PRE>
listener := MouseListener new.
listener implementMethod:'mousePressed' as:[ Transcript showCR:'Hello from Java' ].
</PRE></CODE>
The above creates the callback and the listener, which can now be registered on a button:
<CODE><PRE>
button addMouseListener:listener.
</PRE></CODE>
Now, with the press of the button in the Java GUI, the Smalltalk block will be executed and writes <CODE>"Hello from Java"</CODE> to the Smalltalk console.
Of course, any other (Smalltalk-)action code can be made to run via this mechanism.

But be aware, that the callback is possibly called later (when the elementary action, which installed the code, has already finished long ago). Also, as the Java code execution is not synchronized with any of your expecco action execution, the callback may also be called at any arbutrary time, even at times when no activity at all is executed on the expecco side. If you forget to cleanup, and the Java object is still alive, it may even be called after you have finished your test run (if you keep the java bridge handle around and alive, for example in an expecoo environment variable).

So the Smalltalk callback code should not depend on any particular elementary action to be currently running, but instead in most cases write some information into a shared data container, preferably an instance of "SharedQueue", which is thread safe. Then, some other action (an elementary action) would read-wait and read events from that shared queue.

make sure that your test correctly cleans up any such callbacks afterwards. As a last resort, use the "Shutdown Bridge Connection" menu item, which closes the bridge connection, and thereby - as a side effect - removes any leftover callbacks. It does close the connection, and any remaining java proxy object handles become invalid, though.

Another example, using an observer could look like:
<CODE><PRE>
observer := java Observer new.
observer implementMethod:'update'
as:[:sourceObservable :argument|
argument notNil ifTrue:[ Transcript showCR:('I was notifyed with: ',argument toString) ]
ifFalse:[ Transcript showCR:'I was notifyed and the argument was nil' ].
].
myObservable addObserver:observer.
</PRE></CODE>
When the observable calls <CODE>"notifyObservers"</CODE>, the Smalltalk block will be executed.

== Exceptions in Java ==
Exceptions on the Java side are signalled back to the Smalltalk side and raise a corresponding exception there. However, on the Java side, the call stack which lead to the exception has already been unwound at that time (Java exceptions are not proceedable). So a proceed in the Smalltalk-side exception handler only affects the Smalltalk caller, but may leave the Java side in an undefined state.

== Remote Dynamic Code Injection ==
Sometimes we might want to execute code without the overhead of many rpc-messages being sent over the bridge, especially if we want to do something time critical, or want to make execution time measurements.
For this, it is possible to load a class at runtime into the JavaVM. The code of the class will first be sent to the JavaVM, which will compile and load the generated byte code. Then, the class can be accessed via the bridge just like any other preloaded class.

The following example specifies the class code in a smalltalk string and inject the code into the JavaVM. Then an instance of that new class will be instantiated and finally a method of the object instance will be invoked:
<CODE><PRE>
classCode := '
package myPackage.test;

import java.awt.BorderLayout;
import java.awt.event.MouseAdapter;
import java.awt.event.MouseEvent;
import java.util.Calendar;

import javax.swing.JButton;
import javax.swing.JFrame;
import javax.swing.JLabel;;

public class MyInjectedClass {
public void createSampleApp(){
JFrame frame=new JFrame("Hello im injected");
frame.setLayout(new BorderLayout());
JButton button=new JButton("click me");
final JLabel label=new JLabel("Text");
button.addMouseListener(new MouseAdapter() {

@Override
public void mouseClicked(MouseEvent e) {
label.setText(Calendar.getInstance().getTime().toString());
}
});
frame.add(label,BorderLayout.NORTH);
frame.add(button,BorderLayout.SOUTH);
frame.setSize(300, 300);
frame.setVisible(true);
}
}
'.
classObject := java getJavaClass:'myPackage.test.MyInjectedClass' fromSource:classCode.
classObject new createSampleApp.
</PRE></CODE>
After the code has been injected, a new instance of <CODE>"MyInjectedClass"</CODE> is created and the <CODE>"createSampleApp"</CODE> method is called. Because the example implements a GUI, a Java window will open, containing a label and a button. Clicking the button displays the current time in the label.



=== Code Sources for Class injection ===
There are 3 possible types of class code sources which we can use to inject the code. In the examples before we directly used a simple <CODE>"String"</CODE> in the smalltalk code as a code source. We also can use a <CODE>"*.java"</CODE> file as source. Just read the content of the file into a string and use it as in the previous examples.

To inject a <CODE>"*.class"</CODE> file use the following code:
<pre>
java getJavaClass:'the.class.name' fromByteCode:classCode.
</pre>

== Examples ==

This example creates a JFrame with one button inside. Then a Mouselistener is created and registered on the button. When the button is pressed, the title of the window changes to <CODE>"onPressed"</CODE> and the Transcript shows the message <CODE>"onPressed"</CODE>. When the button is released, the title of the window is changed to <CODE>"onReleased"</CODE> and the Transcript shows <CODE>"onReleased"</CODE>. If the button lost the mouse focus, the bridge will exit (disconnect), and the Java side is terminated.
<CODE><PRE>
|java frame button listener|

"/getting a bridge
java := JAVA::JavaBridge newWithServer.

"/creating a new frame and button object
frame := java getJavaClass:'javax.swing.JFrame' new.
button := java JButton new:'Click'.

"/creating a new mouse listener and adding callback blocks
listener := java MouseListener new.

listener implementMethod:'mousePressed' as:[ Transcript showCR:'onPress'. frame setTitle:'onPressed' ].
listener implementMethod:'mouseReleased' as:[ Transcript showCR:'onReleased'. frame setTitle:'onReleased' ].
listener implementMethod:'mouseExited' as:[ Transcript showCR:'onExited'. java closeBridge. ].

"/register the mouse listener on the button and make the frame with button visible
button addMouseListener:listener.
frame add:button.
frame setSize:300 y:100.
frame setVisible: true.
</PRE></CODE>



== API ==
===JAVA::Java===
====class protocol====
=====newWithServer=====
* This will start a local JavaVM, running the JavaBridge, and establishes a connection on a random free port.
: A new connected instance of JAVA::Java class is returned.

=====newWithServerForJavaPath:aJavaPathFilename=====
* This is the same as newWithServer but the path to the java executable can be specified. The JavaVM version must be 1.6 or higher to run the JavaBridge.
:: '''aJavaPathFilename''' - must be a instance of Filename
Smalltalk: JAVA::Java newWithServerForJavaPath:('my\path\to\java.executable'asFilename).
JavaScript: JAVA::Java.newWithServerForJavaPath("my\path\to\java.executable".asFilename());

=====newConnectedTo:aHhostString port:aPortNumber withTimeout:aTimeoutSeconds=====
* This is used to connect to a running JavaBridge on the network. The JavaBridge must be started in server mode on the remote host. After connecting a new connected instance of JAVA::Java is returned.
:: '''aHostString''' - the hostname or IP of the remote machine as String
:: '''aPortNumber ''' - the port on which the remote machine is listening as Number
:: '''aTimeoutSeconds''' - a connect timeout in seconds as Number
Smalltalk: JAVA::Java newConnectedTo:'myHostName' port:4567 withTimeout:30.
JavaScript: JAVA::Java.newConnectedTo_port_withTimeout("myHostName",4567,30);

=====newWaitingForConnectOnHost:aListeningAddressString port:aListeningPortNumber withTimeout:aTimeoutSeconds=====
* This is used to wait for incomming connecions of a running JavaBridge on the network. The JavaBridge must be started in client mode on the remote host. After connecting a new connected instance of JAVA::Java is returned.
:: '''deprecated: aListeningAddressString''' - no longer used. Can be nil.
:: '''aListeningPortNumber ''' - the port on which to listen for incomming connections as Number
:: '''aTimeoutSeconds''' - a connect timeout in seconds as Number, If nil it will wait endless.

=====singletonInstance=====
* This will call newWithServer for the first time and then always returns the same connected JAVA::Java instance until the connection was closed, then a new connected instance is returned.

=====exitAllInstances=====
* This will close all instances of JAVA::Java.

====instance protocol====
=====loadJarByPath:aPath=====
* Adds a jar to the running JavaVM. If the jar depends on other jars or libraries you have to add them too.
:: '''aPath''' - the path to the jar file as String.

=====loadJar:aByteArray=====
* Adds a jar to the running JavaVM. If the jar depends on other jars or libraries you have to add them too.
:: '''aByteArrays''' - a ByteArray containing the JAR file.

=====loadExtension:aPath=====
* Adds a jar to the running JavaVM and caches it for subsequent usages. If the jar depends on other jars you have to add them too.
:: '''aPath''' - the path to the jar file as String.

=====boxedDo:aBlock=====
* Any autoboxed values in aBlock returned from the JavaVM are preserved as such. By default autoboxed values are automatically unboxed. This way, the identity of such objects is preserved.

=====isConnected=====
* Tests if a connection is still established.
:: '''return:''' - true if the connection is still established, else false.

=====isAlive=====
* Tests if a connection is still responding.
:: '''return:''' - true if the connection is still alive, else false. Does a message round trip.

=====closeBridge=====
* This will close the bridge connection. Depending on in which mode the JavaBridge was started, the JavaVM is also closed (-keepAlive startparameter not set).

=====exit=====
* Same as closeBridge.

== See Also==
The [[DOT NET Interface Library| DOTNET Interface Plugin & Library]], which implements a likewise interface for .NET applications/libraries.

<hr>
Back to [[Plugins]] 
Back to [[OnlineDocumentation#Library and Plugin Overview|Online Documentation]].