docs.intersystems.com
InterSystems IRIS Data Platform 2019.2

First Look: The Java Gateway and InterSystems Products
InterSystems: The power behind what matters   
Search:  


This First Look explains how to use the Java Gateway to interoperate with Java components in InterSystems IRIS™. In this exploration, you will first create a sample JAR file. You will then create and start a Java Gateway in the InterSystems IRIS Management Portal. You will programmatically import the sample JAR file that you created. Finally, you will create and manipulate some proxy classes and objects in ObjectScript.
To give you a taste of the Java Gateway without bogging you down in details, we’ve kept this exploration simple. These activities are designed to only use the default settings and features, so that you can acquaint yourself with the fundamentals of the feature without having to deal with details that are off-topic or overly complicated. When you bring the Java Gateway to your production systems, there may be things you will need to do differently. Be sure not to confuse this exploration of the Java Gateway with the real thing! The sources provided at the end of this document will give you a good idea of what is involved in using the Java Gateway in production.
To browse all of the First Looks, including those that can be performed on a free Community Edition instance as described below, see InterSystems First Looks.
Why the Java Gateway is Important
The Java Gateway provides an easy way for InterSystems IRIS to interoperate with Java components. After importing a JAR file using the Java Gateway, you can instantiate an external Java object and manipulate it as if it were a native object within InterSystems IRIS. You will have access to your Java classes and methods from within InterSystems IRIS and ObjectScript!
Internally, the Java Gateway generates one-to-one ObjectScript proxies for each and every Java class. In general, the best approach to using the Java Gateway is to build a small Java wrapper class that exposes just the functionality you want, and then to create a proxy for this wrapper.
Exploring the Java Gateway
We have developed a brief demo that shows you how to work with the Java Gateway and InterSystems IRIS. (Want to try an online video-based demo of InterSystems IRIS Java development and interoperability features? Check out the Java QuickStart!)
Before you Begin
To use the procedure, you will need a system to work on, with version 1.7 or 1.8 of the JDK and a Java IDE of your choice installed, and a running InterSystems IRIS instance to connect to. Your choices for InterSystems IRIS include several types of licensed and free evaluation instances; the instance need not be hosted by the system you are working on (although they must have network access to each other). For information on how to deploy each type of instance if you do not already have one to work with, see Deploying InterSystems IRIS in InterSystems IRIS Basics: Connecting an IDE. Connect your IDE to your InterSystems IRIS instance using the information in InterSystems IRIS Connection Information and Java IDEs in the same document.
Creating a JAR File
Create a Person class in Java using an IDE of your choice. Use the following sample code:
public class Person {

    public int age;
    public String name;

    //constructor
    public Person (int startAge, String Name) {

        age = startAge;
        name = Name;

    }
    
    public void setAge(int newAge) {

        age = newAge;
    }

    public String getName() {

        return name;
    }

    public int getAge() {

        return age;
    }

    public static void main(String []args) {

        Person myPerson = new Person (5, "Tom");
        System.out.println(myPerson.getName());
        System.out.println(myPerson.getAge());

    }

}
Compile the Person class. Then, open a Command Prompt window and navigate to the directory containing your Person.class file. Use the following command to generate a Person.jar file:
jar cf Person.jar Person.class
Note the location of the file.
Starting a Java Gateway
In order to start a Java Gateway, follow these steps:
  1. Open the Management Portal for your instance in your browser, using the URL described for your instance in InterSystems IRIS Basics: Connecting an IDE.
  2. Navigate to the Object Gateways page. (System Administration > Configuration > Connectivity > Object Gateways)
  3. Select Create New Gateway.
  4. Select the Java radio button.
  5. Enter JavaGatewayTest for Gateway Name and 55555 for Port.
  6. Click Save.
  7. In the row for your new Java Gateway, click Start.
Generating Proxy Classes
Create a new ObjectScript class in the USER namespace (or another that you have created in your installed instance) called CreateProxyClasses.cls with package name JavaGatewayTest. Paste in the following code, substituting the connection information for your InterSystems IRIS instance (as described in InterSystems IRIS Basics: Connecting an IDE) for the arguments to gwyConn.&Connect. You can specify the USER namespace as shown, or you can choose another that you have created on your instance. Replace YOUR FILEPATH HERE with the complete file path of your Person.jar file, enclosed in double quotes.
Class JavaGatewayTest.CreateProxyClasses Extends %Persistent
{

ClassMethod run()
{
   // get a connection to the Java Gateway
   set gwyConn = ##class(%Net.Remote.Gateway).%New()
   set status = gwyConn.%Connect("127.0.0.1", 55555, "USER")
   if $$$ISERR(status) {
                write !,"error: "_$system.OBJ.DisplayError(status)
                quit
   }

   // add the jar to the classpath
   set classpath = ##class(%ListOfDataTypes).%New()
   do classpath.Insert("YOUR FILEPATH HERE")
   set status = gwyConn.%AddToCurrentClassPath(classpath)
   if $$$ISERR(status) {
                write !,"error: "_$system.OBJ.DisplayError(status)
                quit
   }

   // create the proxy ObjectScript classes that correspond to the Java classes in the jar file
   set status = gwyConn.%Import("Person",,,,1)
   if $$$ISERR(status) {
                write !,"error: "_$system.OBJ.DisplayError(status)
                quit
   }

   // close the connection to the Java gateway
   set status = gwyConn.%Disconnect()
   if $$$ISERR(status) {
                write !,"error: "_$system.OBJ.DisplayError(status)
                quit
   }

}
Compile and build the class.
Open the InterSystems IRIS Terminal using the procedure described for your instance in InterSystems IRIS Basics: Connecting an IDE, and switch to the namespace you specified in the code if necessary. Execute the run() method with the following command:
do ##class(JavaGatewayTest.CreateProxyClasses).run()
Manipulating Java Objects in ObjectScript
Create a new ObjectScript class in the namespace you are using called ManipulateObjects.cls with package name JavaGatewayTest. Paste in the following code, being sure to substitute the connection information for your InterSystems IRIS instance for the arguments to gwyConn.&Connect and update the namespace field if you are not using USER.
Class JavaGatewayTest.ManipulateObjects Extends %Persistent
{

ClassMethod run()
{
   // get a connection to the Java Gateway
   set gwyConn = ##class(%Net.Remote.Gateway).%New()
   set status = gwyConn.%Connect("127.0.0.1", 55555, "USER")
   if $$$ISERR(status) {
                write !,"error: "_$system.OBJ.DisplayError(status)
                quit
   }

   // manipulate some proxy objects
   set person = ##class(User.Person).%New(gwyConn,5,"Tom")
   write !,"Name: "_person.getName()
   write !,"Age: "_person.getAge()
   write !,"setting age to 100"
   do person.setAge(100)
   write !,"Age: "_person.getAge()

   // close the connection to the Java Gateway
   set status = gwyConn.%Disconnect()
   if $$$ISERR(status) {
                write !,"error:"_$system.OBJ.DisplayError(status)
                quit
   }
}

}
Compile and build the class.
Open the InterSystems IRIS Terminal and navigate to the namespace you specified. Execute the run() method with the following command:
do ##class(JavaGatewayTest.ManipulateObjects).run()
You should see the following output:
Name: Tom
Age: 5
setting age to 100
Age: 100
Now that you have successfully completed the exercise, stop the Java Gateway that you created. Return to the Object Gateways page in the Management Portal, locate your JavaGatewayTest gateway, and select Stop.
Learn More About the Java Gateway
To learn more about the Java Gateway and InterSystems IRIS, see:
Using the Java Gateway
Connecting Systems Using Java Business Hosts


Send us comments on this page
View this article as PDF   |  Download all PDFs
Copyright © 1997-2019 InterSystems Corporation, Cambridge, MA
Content Date/Time: 2019-08-22 06:48:58