docs.intersystems.com
Home  /  First Look: The Java Gateway and InterSystems IRIS


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


This First Look guide 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.
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.
Before you Begin
To run the demo, you’ll need a single Windows 10 machine with a running, licensed instance of InterSystems IRIS and version 1.8 of the JDK.
For instructions on how to install and license a development instance of InterSystems IRIS, see Quick Start: InterSystems IRIS Installation.
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 your Person.jar file.
Starting a Java Gateway
In order to start a Java Gateway, follow these steps:
  1. In the InterSystems IRIS System Management Portal, navigate to the Object Gateways page. (System Administration > Configuration > Connectivity > Object Gateways)
  2. Select the Java radio button.
  3. Enter JavaGatewayTest for Gateway Name and 55555 for Port.
  4. Click Save.
  5. In the row for your new Java Gateway, click Start.
Generating Proxy Classes
Create a new ObjectScript class in the USER namespace called CreateProxyClasses.cls with package name JavaGatewayTest. Paste in the following code:
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
	}

}

}
Replace YOUR FILEPATH HERE with the complete file path of your Person.jar file, enclosed in double quotes.
Compile and build the class.
Open the InterSystems IRIS Terminal and navigate to the USER namespace. 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 USER namespace called ManipulateObjects.cls with package name JavaGatewayTest. Paste in the following code:
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 USER namespace. 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 in Productions
Connecting Systems in InterSystems IRIS Using Java Business Hosts