Previous section   Next section

Using Java Reverse Proxy Objects

The Native API works together with the Object Gateway. Reverse proxy objects are Java objects that allow you to manipulate ObjectScript objects via the Object Gateway. You can use a reverse proxy object to call the target’s instance methods and get or set property values, manipulating the ObjectScript target object as easily as if it were a native Java object.
This chapter covers the following topics:

Introducing the Object Gateway

The Object Gateway allows InterSystems IRIS objects and Java objects to interact freely, using the same connection and working together in the same context (database, session, and transaction). Object Gateway architecture is described in detail in Using the Object Gateway, but for the purposes of this discussion you can think of it as a simple black box connecting proxy objects on one side to target objects on the other:
Object Gateway System
images/bjavnat_gateway_system.png
The connection is via TCP/IP if InterSystems IRIS and the host VM are on two different machines. If they are on the same machine, the connection can be either TCP/IP or shared memory.
As the diagram shows, a forward proxy object is an ObjectScript proxy for a Java target object (see “Using Dynamic Object Proxies” in Using the Object Gateway for details). Forward proxies will be mentioned again later, but the focus of this chapter is how to use a Java reverse proxy to manipulate an ObjectScript target object.

Creating Reverse Proxy Objects

You can create a reverse proxy object by obtaining the OREF of an ObjectScript class instance (for example, by calling the %New() method of the class) and casting it to IRISObject. The following methods can be used to call ObjectScript class methods and functions:
In either case, if the returned object is a valid OREF, it will be used to generate and return a proxy for the referenced object.
See “Class Method Calls” in the previous chapter for more information on how to call ObjectScript class methods. The following example uses classMethodObject() to create a reverse proxy object:
Creating an instance of IRISObject
  • classMethodObject() is used to call the %New() method of an ObjectScript class named Demo.Test.
  • Since the return value of %New() is a valid OREF, classMethodObject() creates and returns a proxy for the instance.
  • In Java, the proxy is cast to IRISObject, creating reverse proxy object test:
       IRISObject test = (IRISObject)iris.classMethodObject("Demo.Test","%New");
Variable test is a Java reverse proxy object for the new instance of Demo.Test. In the following section, test will be used to access methods and properties of the ObjectScript Demo.Test instance.

Using IRISObject Methods

IRISObject provides four methods to control the ObjectScript target object: invoke() and invokeVoid() call an instance method with or without a return value, and accessors get() and set() get and set a property value.
Assume that we have created an ObjectScript class named Demo.Test, which includes declarations for methods initialize() and add(), and property name (we won’t need the actual method code for this example):
   Class Demo.Test Extends %Persistent
      Method initialize(initialVal As %String)
      Method add(val1 As %Integer, val2 As %Integer) As %Integer
      Property name As %String
In the following example, the first line creates a reverse proxy object named test for an instance of Demo.Test. The rest of the code uses the proxy to access the target object.
Using reverse proxy object methods
// Create an instance of Demo.Test and return a proxy object for it
  IRISObject test = (IRISObject)iris.classMethodObject("Demo.Test","%New");

// instance method test.initialize() is called with one argument, returning nothing.
  test.invokeVoid("initialize", 42);  // sets a mysterious internal variable to 42

// instance method test.add() is called with two arguments, returning an int value.
  int sum = test.invoke("add",2,3);  // adds 2 plus 3, returning 5

// The value of property test.name is set and then returned.
  test.set("name", "Einstein, Albert");  // sets the property to "Einstein, Albert"
  String name = test.get("name");   // returns the new property value

In this example, IRISObject proxy methods are used to access methods and properties of the Demo.Test instance:
  • invokeVoid() invokes the initialize() instance method, which initializes an internal variable but does not return a value.
  • invoke() invokes the add() instance method, which accepts two integer arguments and returns the sum as an integer.
  • set() sets the name property to a new value.
  • get() returns the value of property name.
The IRIS.classMethodObject() call was discussed previously in “Creating Reverse Proxy Objects”.

IRIS Methods for Working with Reverse Proxies

The IRIS class includes four methods that allow you to manipulate IRISObject instances by reference. Each method corresponds to one of the IRISObject methods, as shown below:
jdbc.IRISObject Methods jdbc.IRIS Methods
test.invoke("add", 2, 2); iris.instanceMethodObject(test,"add",2,2);
test.invoke("init", 0); iris.instanceMethodObject(test,"init",0);
test.set("name", "Albert"); iris.setInstanceProperty(test,"name", "Albert");
String name = test.get("name"); String name = iris.getInstanceProperty(test,"name");
Previous section   Next section