Working with External Languages

There are specific gateway creation methods for the Java, .NET, and Python External Servers: getJavaGateway(), getDotNetGateway(), and getPythonGateway(). Each of these methods starts its external server in the default configuration and returns a Gateway object to manage the connection:

  set javaGate = $system.external.getJavaGateway()
  set netGate = $system.external.getDotNetGateway()
  set pyGate = $system.external.getPythonGateway()

There is also a generic getGateway() method for use with customized external server configurations (see “Customizing External Server Definitions” for details) but the defaults should be sufficient for most purposes.

Each gateway object has a new() method for creating target and proxy objects. Each call to new() specifies a class name and any required arguments. When the call is made, the external server creates a target instance of the class, and the gateway creates a corresponding proxy object that has the same set of methods and properties as the target. Each call to the proxy is echoed by the target, which returns the result to the proxy.

This example creates three proxy objects connected through three different external servers (since each language requires its own server):

  set dateJava = javaGate.new("java.util.Date")
  set dateNet = newGate.new("System.DateTime",0)
  set datePy = pyGate.new("datetime.datetime",1,1,1).now()

Each proxy can be treated like any other ObjectScript object. All three can be used in the same ObjectScript application.

You can use method and property calls from all three proxy objects in the same statement:

  write !,"  Java: "_dateJava.toString(),!,"  .NET: "_dateNet.Now,!, "Python: "_datePy.strftime("%c")

       Java: Sun May 02 15:18:15 EDT 2021
       .NET: 2021-05-02 16:38:36.9512565
     Python: Sun May 02 15:23:55 2021

The Java and Python examples are method calls, and the .NET example uses a property.

  do javaGate.addToPath("/home/myhome/someclasses.jar")
  do netGate.addToPath("C:\Dev\myApp\somedll.dll")
  do pyGate.addToPath("/rootpath/person.py")

The Java and .NET gateways also accept paths to folders containing one or more shared libraries. See “Specifying Python Package and Class Paths” for more advanced Python options

The %DynamicArrayOpens in a new tab class is an ObjectScript wrapper that provides a simple way to create a JSON array structure. Use the dynamic array %Push() method to add path strings to the array (see Using %Push and %Pop with Dynamic Arrays in Using JSON). The following example adds two paths to array pathlist and then passes it to the addToPath() method of a Java Gateway object:

  set pathlist = []
  do pathlist.%Push("/home/myhome/firstpath.jar")
  do pathlist.%Push("/home/myhome/another.jar")
  do javaGate.addToPath(pathlist)

For Java, the path can be a folder or a jar. The following example adds a path to someclasses.jar and then creates a proxy for an instance of someclasses.classname.

  set javaGate = getJavaGateway()
  do javaGate.addToPath("/home/myhome/someclasses.jar")
  set someProxy = javaGate.new("someclasses.classname")

For .NET, the path can be a folder or an assembly. The following example adds a path to someassembly.dll and then creates a proxy for an instance of someassembly.classname

  set netGate = getDotNetGateway()
  do netGate.addToPath("C:\Dev\myApp\somedll.dll")
  set someProxy = netGate.new("someassembly.classname")

For Python, the path can be a module or a package. When a module is part of a package, the module path must be specified with dot notation starting at the top level package directory. For example, the path to module Foo.py could be specified in either of two ways:

• Standard path notation if treated as a module: C:\Dev\demo\Foo.py

• Dot notation if treated as part of package demo: C:\Dev\demo.Foo.py

The following example uses a dynamic array to add paths for two different files, both in folder C:\Dev\demo\. File Foo.py contains unpackaged class personOne, and file Bar.py contains class personTwo, which is part of package demo. Calls to new() create proxies for both classes:

  set pyPaths = []
  do pyPaths.%Push("C:\Dev\demo\Foo.py")
  do pyPaths.%Push("C:\Dev\demo.Bar.py")

  set pyGate = getPythonGateway()
  do pyGate.addToPath(pyPaths)
  set fooProxy = pyGate.new("Foo.personOne")
  set barProxy = pyGate.new("demo.Bar.personTwo")

It is also possible to assign targets for modules or packages that do not have classes, as described in Specifying Python Package and Class Paths.

The process of getting a Gateway object with an active server connection involved several calls to methods of two different ObjectScript classes:

  set status = ##class(%Net.Remote.Service).OpenGateway("JavaGate",.GatewayInfo)
  set name = GatewayInfo.Name
  set port = GatewayInfo.Port
  set server = GatewayInfo.Server
  if ('##class(%Net.Remote.Service).IsGatewayRunning(server,port,,.status)) {
    set status = ##class(%Net.Remote.Service).StartGateway(name)
  }
set gateway = ##class(%Net.Remote.Gateway).%New()
set status = gateway.%Connect(server, port, "USER")

With external servers, it’s much simpler:

set gateway = $system.external.getJavaGateway()

One call creates a Gateway object with all the appropriate settings, and automatically starts the connection to the external server. You can still access the external server manually (see “Starting and Stopping External Servers”), but this is unnecessary for most applications.

Object Gateway code required references to several different ObjectScript classes and a significant amount of server-specific information before a proxy could be created:

set path = ##class(%ListOfDataTypes).%New()
do path.Insert("C:\Dev\SomeClasses.jar")
do ##class(%Net.Remote.Service).OpenGateway("JavaGate",.GatewayInfo)
set gateway = ##class(%Net.Remote.Gateway).%New()
do gateway.%Connect(GatewayInfo.Server, GatewayInfo.Port, "USER",,path)
set proxy = ##class(%Net.Remote.Object).%New(gateway,"SomeClasses.ClassOne")

Once again, external server code is considerably simpler:

set gateway = getJavaGateway()
do gateway.addToPath("C:\Dev\SomeClasses.jar")
set proxy = gateway.new("SomeClasses.ClassOne")

The addToPath() method also provides a simpler way to add multiple class paths.

Instead of the old %ClassMethod(), external servers use the new Gateway invoke() method.

// Object Gateway
set num = ##class(%Net.Remote.Object).%ClassMethod(gateway,"Demo.ReverseGateway","factorial",num-1)

// external server
set num = gateway.invoke("Demo.ReverseGateway","factorial",num-1)