Skip to main content

Sample Code

You can find sample Java Gateway code in Ensemble installations in the EnsLib.JavaGateway.Test class. These samples demonstrate how to generate and use Ensemble proxy classes. They are presented in the following example sections:

For each method described in this chapter, the port argument is the port number over which the proxy classes communicate with the Java classes, and host identifies the machine on which the Java Gateway server is running. The port argument is required; host is optional and defaults to "" (the local machine) if not provided.

Setting Up Java Gateway Examples

To prepare to run sample code, in each of the examples described in this chapter, you must complete the following steps:

  1. Start the Java Gateway server.

  2. Start a Terminal session and change to an Ensemble namespace.

  3. Make sure to run Import code if this is the first time you are running the sample code or if you have modified or recompiled your Java classes.

To prepare to run any of the sample code located under EnsLib.JavaGateway.Test — either for the first time, or after you update or recompile your Java code — you must run the corresponding Import methods found under EnsLib.JavaGateway.InterfaceEnablerOpens in a new tab. This imports the necessary Java classes. The specific sample Import method depends on the type of example you are running. For example:

  • To import the sample Java classes provided with Ensemble:

     Do ##class(EnsLib.JavaGateway.InterfaceEnabler).ImportJGSamples(port,host)
  • To import the JDBC interface:

     Do ##class(EnsLib.JavaGateway.InterfaceEnabler).ImportJDBC(port,host)
  • To import the InterSystems JBoss Person EJBs, enter the following command (all on one line):

     Do ##class(EnsLib.JavaGateway.InterfaceEnabler).ImportPersonJBoss(PersonEJBJar,

    Where PersonEJBJar points to the PersonEJB.jar file (as generated by the InterSystems EJB Boss projection) and j2eeJarFile points to the J2EE jar file on your system, for example:


  • To import all J2EE interfaces (EJB, JCA, JTA, Java XML, JTA, etc.), enter the following command (all on one line):

     Do ##class(EnsLib.JavaGateway.InterfaceEnabler).ImportJ2EE(j2eeJarFile,

    Where j2eeJarFile points to the J2EE jar file on your system, for example:


In addition to these Import methods, the EnsLib.JavaGateway.InterfaceEnablerOpens in a new tab class provides a convenience method that, given a jar file or a directory name, displays all available classes in that jar file or directory:

 Do ##class(EnsLib.JavaGateway.InterfaceEnabler).Browse(jarName,port,host)

Running Plain Java Examples

The Test() method shows how to use the sample basic classes delivered with Ensemble. To run it, first set up the example, using ImportJGSamples() if you need to import. Then enter:

 Do ##class(EnsLib.JavaGateway.Test).Test(port,host)

The TestArrays() method shows how to use arrays. To run it, first set up the example, using ImportJGSamples() if you need to import. Then enter:

 Do ##class(EnsLib.JavaGateway.Test).TestArrays(port,host)

Running JDBC Examples

The following example establishes a connection with Caché JDBC driver, then executes some standard JDBC code. To run it, first set up the example, using ImportJDBC() if you need to import. Then enter:

 Do ##class(EnsLib.JavaGateway.Test).JDBC(port,host,jdbcPort,jdbcHost)

This sample code should work against any database that has a compliant JDBC driver. Simply replace the connection parameters (JDBC driver class name, URL, username, and password) with appropriate values. See the Class Reference entry for the JDBCOpens in a new tab method for details.


The value of jdbcPort defaults to 1972; in many cases, this is not correct for your Ensemble instance.

Running EJB Gateway Examples

The following example shows how Caché Basic or ObjectScript code can access a sample Entity Bean (generated by Caché EJB projections) using JBoss version 4.0.1. To run it, first set up the example, using ImportPersonJBoss() if you need to import. Then enter:

 Do ##class(EnsLib.JavaGateway.Test).PersonJBoss(JBossRoot,port, host)

Where JBossRoot points to your JBoss root, for example:


You can easily modify this example to work against any application server. Simply set the CLASSPATH accordingly and use appropriate connection and context parameters.

Stateless Service Mode Example

Here is a simple implementation using GSON which gets the Google directions between two cities and sends them back to Caché in JSON format. For more info on GSON go to: in a new tab.

Java code:

package jsonservice;


public class Directions implements com.intersys.gateway.Service {

    public byte[] execute(byte[] args) throws Throwable {
        JsonElement inputJSON = new JsonParser().parse(new
                BufferedReader(new InputStreamReader(new ByteArrayInputStream(args), "UTF-8")));
        JsonObject jsonObject = inputJSON.getAsJsonObject();
        String origin = jsonObject.get("origin").toString();
        String destination = jsonObject.get("destination").toString();

        URL URLsource = new URL("
        BufferedReader in = new BufferedReader(new  InputStreamReader(URLsource.openStream(),"UTF-8"));
        JsonElement outputJSON = new JsonParser().parse(in);
        jsonObject = outputJSON.getAsJsonObject();
        String response = jsonObject.toString();
        return response.getBytes();

To invoke the above service from Caché/Ensemble, simply do:

Set classPath=##class(%ListOfDataTypes).%New()
// add GSON to the classpath
Do classPath.Insert("c:/service/gson-1.4.jar")
// add the location of the above Service to the classpath
Do classPath.Insert("c:/service/")
// invoke the service
Write  ##class(%Net.Remote.Gateway).%RemoteService("",55555,"jsonservice.Directions","{""origin"" : 
            ""philadelphia"", ""destination"" : ""boston""}",classPath) 


The JSON parsing tool (GSON) is not strictly necessary in this simple example.

FeedbackOpens in a new tab