Skip to main content


class EnsLib.JavaGateway.Service extends Ens.BusinessService

A service responsible for starting, monitoring and stopping the Java Gateway Server in a production.

Property Inventory

Method Inventory


parameter ADAPTER = EnsLib.JavaGateway.ServiceAdapter;
This adapter does not handle communication with external systems, it's for internal use of this class only.
parameter JAVADEBUG = -Xdebug -Xnoagent -Djava.compiler=NONE -Xrunjdwp:transport=dt_socket,address=${JavaDebugPort},suspend=${JavaDebugSuspend},server=y;
Java debugging parameters, used if JavaDebug is True:
  • -Xdebug : Enable debugging
  • -Xnoagent : Disables oldjdb support
  • -Djava.compiler=NONE : Disable JIT compiler
  • -Xrunjdwp : JDWP Options
    • transport=dt_socket, (Use TCP/IP)
    • address=8000, (Listen on port 8000)
    • suspend=y, (Suspend the Java process until the debugger connects)
    • server=y (Listen for incoming debugger connection)
parameter JAVAGATEWAYJARS = cache-gateway-2.0.0.jar,cache-jdbc-2.0.0.jar;
List of default JARs needed by the Java Gateway server including when used by the Ensemble JDBC Adapter. Note that the needed files vary with the Ensemble version.
parameter PIPEREADTIMEOUT = 10;
This timeout should work in most if not all cases.
parameter SETTINGS = Address:Basic,Port:Basic,HeartbeatInterval,HeartbeatFailureTimeout,HeartbeatFailureAction,HeartbeatFailureRetry,JavaHome,ClassPath,JVMArgs,Logfile,UsePassphrase,JavaDebug,JavaDebugPort,JavaDebugSuspend,-ArchiveIO;
Inherited description: List of properties can be set as settings in the configuration file format is a comma separated list of property names


property Address as %String [ InitialExpression = "" ];
IP address or name of the machine where the JVM to be used by the Java Gateway Server is located.
Property methods: AddressDisplayToLogical(), AddressGet(), AddressIsValid(), AddressLogicalToDisplay(), AddressLogicalToOdbc(), AddressNormalize(), AddressSet()
property ClassPath as %String (MAXLEN = 32000);
CLASSPATH containing the files required to be passed as an argument when starting the JVM. The user should typically provide here the files containing the classes used via the Java Gateway. We assume that the user has properly quoted the classpath and supplied the correct separators for the platform in case of multiple files.
Note that additional classpath can be specified in business operations derived from EnsLib.JavaGateway.AbstractOperation. See property AdditionalPaths in that class.
Property methods: ClassPathDisplayToLogical(), ClassPathGet(), ClassPathIsValid(), ClassPathLogicalToDisplay(), ClassPathLogicalToOdbc(), ClassPathNormalize(), ClassPathSet()
property HeartbeatFailureAction as %String (DISPLAYLIST = ",None,Restart,Alert,Restart and Alert", VALUELIST = ",N,R,A,RA") [ InitialExpression = "R" , Required ];
What action(s) to take if the Java Gateway Server goes into failure state. Setting it to Restart (default) will cause the Java Gateway to be restarted. Setting it to Alert will generate an alert entry in the Event Log.
Note 1: This is independent of the Alert on Error setting.
Note 2: If Address points to a remote system, this feature must not restart the server; only alerts may be generated.
See also properties HeartbeatInterval, HeartbeatFailureTimeout and HeartbeatFailureRetry.
Property methods: HeartbeatFailureActionDisplayToLogical(), HeartbeatFailureActionGet(), HeartbeatFailureActionIsValid(), HeartbeatFailureActionLogicalToDisplay(), HeartbeatFailureActionLogicalToOdbc(), HeartbeatFailureActionNormalize(), HeartbeatFailureActionSet()
property HeartbeatFailureRetry as %Integer (MAXVAL = 86400, MINVAL = 0) [ InitialExpression = 300 ];
In case the Java Gateway Server goes into failure state, and stays in failure state, how much time to wait before retrying the HeartbeatFailureAction. The default value is 300 seconds (5 minutes). A value of 0 disables this retry, meaning that once there is a failure that can't be immediately recovered, there won't be automatic attempts to recovery.
See also properties HeartbeatInterval, HeartbeatFailureTimeout and HeartbeatFailureAction.
Property methods: HeartbeatFailureRetryDisplayToLogical(), HeartbeatFailureRetryGet(), HeartbeatFailureRetryIsValid(), HeartbeatFailureRetryLogicalToDisplay(), HeartbeatFailureRetryNormalize(), HeartbeatFailureRetrySet()
property HeartbeatFailureTimeout as %Integer (MAXVAL = 86400, MINVAL = 0) [ InitialExpression = 30 ];
Number of seconds without responding to the heartbeat, to consider that the Java Gateway Server is in failure state. If this value is smaller than property HeartbeatInterval, it will be considered in failure state every time the Java Gateway communication check fails. The default is 30 seconds. The maximum value is 86400 seconds (1 day).
See also properties HeartbeatInterval, HeartbeatFailureAction and HeartbeatFailureRetry.
Property methods: HeartbeatFailureTimeoutDisplayToLogical(), HeartbeatFailureTimeoutGet(), HeartbeatFailureTimeoutIsValid(), HeartbeatFailureTimeoutLogicalToDisplay(), HeartbeatFailureTimeoutNormalize(), HeartbeatFailureTimeoutSet()
property HeartbeatInterval as %Integer (MAXVAL = 3600, MINVAL = 0) [ InitialExpression = 10 ];
Number of seconds between each communication with the Java Gateway Server to check if it is active. The default is 10 seconds. When enabled, the minimum value is 5 seconds and the maximum value is 3600 seconds (1 hour).
A value of 0 disables the monitoring feature; in this case, if the Gateway goes down, the status indicator color in the Production Configuration page will not be automatically updated.
See also properties HeartbeatFailureTimeout, HeartbeatFailureAction and HeartbeatFailureRetry, which only apply if monitoring is enabled.
Property methods: HeartbeatIntervalDisplayToLogical(), HeartbeatIntervalGet(), HeartbeatIntervalIsValid(), HeartbeatIntervalLogicalToDisplay(), HeartbeatIntervalNormalize(), HeartbeatIntervalSet()
deprecated property JDKVersion as %String (DISPLAYLIST = ",Java 1.7,Java 1.8", VALUELIST = ",JDK17,JDK18") [ InitialExpression = "JDK18" ];
DEPRECATED : We now check the version of the java executable before starting the gateway. There is no need fo the user to tell which version of the JARs to use anymore. Version of JDK used to select the intended version of the InterSystems .jar files. It is used to assemble the command to start the Java Gateway.
Property methods: JDKVersionDisplayToLogical(), JDKVersionGet(), JDKVersionIsValid(), JDKVersionLogicalToDisplay(), JDKVersionLogicalToOdbc(), JDKVersionNormalize(), JDKVersionSet()
property JVMArgs as %String (MAXLEN = 32000);
Optional arguments to be passed to the Java Virtual Machine (JVM) to include when assembling the command to start the Java Gateway.
For example, you can specify system properties: Dsystemvar=value
or set the maximum heap size: Xmx256m
and so on, as needed.
Property methods: JVMArgsDisplayToLogical(), JVMArgsGet(), JVMArgsIsValid(), JVMArgsLogicalToDisplay(), JVMArgsLogicalToOdbc(), JVMArgsNormalize(), JVMArgsSet()
property JavaDebug as %Boolean [ InitialExpression = "0" ];
If set to True, enables Java debugging via TCP, allowing a Java debugger (such as Eclipse or Jswat) to attach. The default is False.
The following arguments can be set: JavaDebug, JavaDebugSuspend and JAVADEBUG.
Property methods: JavaDebugDisplayToLogical(), JavaDebugGet(), JavaDebugIsValid(), JavaDebugLogicalToDisplay(), JavaDebugNormalize(), JavaDebugSet()
property JavaDebugPort as %String [ InitialExpression = "8000" ];
Specifies the port to listen on if JavaDebug is True. The default is 8000.
Property methods: JavaDebugPortDisplayToLogical(), JavaDebugPortGet(), JavaDebugPortIsValid(), JavaDebugPortLogicalToDisplay(), JavaDebugPortLogicalToOdbc(), JavaDebugPortNormalize(), JavaDebugPortSet()
property JavaDebugSuspend as %String (DISPLAYLIST = ",Yes,No", VALUELIST = ",y,n") [ InitialExpression = "n" ];
If JavaDebug is True, this setting indicates whether the JVM is suspended on start in order to wait for the debugger to attach. The default is No.
Property methods: JavaDebugSuspendDisplayToLogical(), JavaDebugSuspendGet(), JavaDebugSuspendIsValid(), JavaDebugSuspendLogicalToDisplay(), JavaDebugSuspendLogicalToOdbc(), JavaDebugSuspendNormalize(), JavaDebugSuspendSet()
property JavaHome as %String (MAXLEN = 1023);
Location of the JVM (similar to JAVA_HOME environment variable). It is used to find the target JVM and assemble the command to start the Java Gateway.
Note: If there is a default JVM on the machine that is usable without the need to specify its location, this setting may be left blank.
Property methods: JavaHomeDisplayToLogical(), JavaHomeGet(), JavaHomeIsValid(), JavaHomeLogicalToDisplay(), JavaHomeLogicalToOdbc(), JavaHomeNormalize(), JavaHomeSet()
property Logfile as %String (MAXLEN = 1023);
Fully qualified name of a file to log all communication between the Ensemble server and the Java Gateway. Usually this setting should be left blank, and used only for trouble-shooting.
Property methods: LogfileDisplayToLogical(), LogfileGet(), LogfileIsValid(), LogfileLogicalToDisplay(), LogfileLogicalToOdbc(), LogfileNormalize(), LogfileSet()
property Port as %String [ InitialExpression = "55555" ];
TCP port number for communication between the Java Gateway Server and the proxy classes in Ensemble.
Property methods: PortDisplayToLogical(), PortGet(), PortIsValid(), PortLogicalToDisplay(), PortLogicalToOdbc(), PortNormalize(), PortSet()
property UsePassphrase as %Boolean [ InitialExpression = 0 ];
If Gateway is to be started requiring a passphrase for connection
Property methods: UsePassphraseDisplayToLogical(), UsePassphraseGet(), UsePassphraseIsValid(), UsePassphraseLogicalToDisplay(), UsePassphraseNormalize(), UsePassphraseSet()


classmethod ConnectGateway(pEndpoint As %String, ByRef pGateway As EnsLib.JavaGateway.JavaGateway, pDebug As %Boolean = 0, pTimeout As %Numeric = 5, pAdditionalPaths As %String = "") as %Status
Connect to a running Java Gateway Server.
classmethod JavaDebugParams(pDebugPort As %String, pDebugSuspend As %String) as %String
method OnInit() as %Status
Upon instantiating this service, adjust some properties and start the Java Gateway Server.
method OnProcessInput(pInput As %Library.RegisteredObject, pOutput As %Library.RegisteredObject, ByRef pHint As %Library.String) as %Status
This service does not actually handle input data. The call interval is used as the heartbeat interval if enabled.
method OnTearDown() as %Status
Shutdown the Java Gateway Server.
classmethod PingJavaGateway(pPort As %String, pAddress As %String = "") as %Status
"Ping" the Java Gateway server to check if it's alive.
classmethod RunCommandViaCPIPE(pCmd As %String, Output pDevice, Output pOutput, pTimeout As %Numeric = 10, Output pRetCode As %String, ByRef pCmdArgs) as %Status
Execute OS command asynchronously.
classmethod RunJava(pJavaHome As %String = "", pClassPath As %String = "", pJVMArgs As %String = "", pDebug As %Boolean = 0, pPort As %String = "", pLogfile As %String = "", ByRef pDevice As %String, pDebugPort As %String = "", pDebugSuspend As %String = "", pUsePassphrase As %Boolean = 0, ByRef pPassphraseList As %String = "") as %Status
Assemble the command to start the Java Gateway Server based on the settings, and execute the command.
classmethod StartGateway(pJavaHome As %String, pClassPath As %String, pJVMArgs As %String, pPort As %String, pLogfile As %String = "", pDebug As %Boolean = 0, ByRef pDevice As %String = "", pAddress As %String = "", pDebugPort As %String = "", pDebugSuspend As %String = "", pUsePassphrase As %Boolean = 0) as %Status
Start up the Java Gateway Server.
classmethod StopGateway(pPort As %String, pAddress As %String = "", pTimeout As %Numeric = 5) as %Status
Shutdown the Gateway.

Inherited Members

Inherited Properties

Inherited Methods

FeedbackOpens in a new tab