Connecting to a PGX Instance and Starting the PGX Engine

This chapter shows the APIs for connecting to a PGX server instance (both embedded and remote) and how to start/stop the PGX engine.

Obtain a ServerInstance Object

Using the Embedded PGX Instance

Among the several PGX usage modes, let's first look at the Local Java Mode, in which PGX is utilized as a library for the user application. Here the PGX instance naturally resides in the same JVM as the Java application.

The following code gets a reference to the local PGX instance:

import oracle.pgx.api.*;

ServerInstance instance = Pgx.getInstance(Pgx.EMBEDDED_URL);

One PGX instance per class loader (per JVM)

Note that the PGX instance is a singleton - there can be one PGX instance at most per class loader (in a non-J2EE context that usually means one PGX instance per JVM). If you invoke Pgx.getInstance(Pgx.EMBEDDED_URL) twice, the same object is returned.

Note: A convenience method Pgx.getInstance() exists, which returns the PGX instance pointed by the default PGX location. By default, this method is equivalent to Pgx.getInstance(Pgx.EMBEDDED_URL) since the default location is set as the local JVM.

Connecting to a Remote PGX Instance

A connection to a remote PGX instance (Remote Java Mode) is obtained by simply passing the base URL of the remote PGX instance to the getInstance() method. By doing this, your application automatically uses the PGX client libraries to connect to a remotely-located PGX server. The following example shows a connection to a remote PGX instance located at the URL http://myhost:7007/, using HTTP Basic Auth with username scott and password tiger:

import oracle.pgx.api.*;

ServerInstance instance = Pgx.getInstance("https://scott:tiger@myhost:7007");

instance = pypgx.get_session(base_url="https://scott:tiger@myhost:7007")

Server configuration settings

The above URL argument may need to be modified depending on the server configuration options. If a context path is specified, it must be part of the base URL argument. For example, if context_path is set to /pgx, the URL argument http://scott:tiger@myhost:7007/pgx should be passed instead. Moreover, if two-way SSL/TLS is enabled with enable_tls set to true, the URL argument https://myhost:7007 should be passed instead. Furthermore, if port is set, the configured port number should replace 7007 in the URL argument.

Changing the Default PGX Location

We mentioned that Pgx.getInstance() is a convenience method which returns the PGX instance pointed by the default PGX location, which is the local JVM. However, the value of the default location can be overridden, either programmatically, using Pgx.setDefaultUrl(...), or via the Java system property pgxDefaultUrl:

java -DpgxDefaultUrl=myhost:7007/pgx ...

Note: This approach is useful for two-phase development. Initially, you may develop and debug your Java application against a local PGX instance. Once working, the same code can be run against a remote PGX instance, without changing a single line of code.

Starting the PGX Engine

As shown in the above examples, Pgx.getInstance() returns an ServerInstance object which represents a handle to a PGX instance. However, the PGX instance is not yet ready if either the underlying PGX engine or the internal PGX component for computation, has not started.

In order to start the PGX engine, the user application can make a call to instance.startEngine() which takes a JSON object as an argument for PGX configuration. Please review this document for the various configuration options for PGX engine.

PGX provides another convenience mechanism to start the PGX engine for Local Java Mode. That is, the PGX engine is automatically initialized and starts up automatically when ServerInstance#createSessionAsync(...) is called the first time — if the engine is not already running at that time.

Note: For this implicit initialization, PGX will configure itself with the PGX configuration file at the default locations. If no PGX configuration file is found, PGX will configure itself using default parameter values as in this document.

Stopping the PGX Engine

The PGX engine can be stopped by using one of the following APIs:

instance.shutdownEngineNow(); // cancels pending tasks, throws exception if engine is not running
instance.shutdownEngineNowIfRunning(); // cancels pending tasks, only tries to shut down if engine is running
if (instance.shutdownEngine(30, TimeUnit.SECONDS) == false) { 
  // doesn't accept new tasks but finishes up remaining tasks
  // pending tasks didn't finish after 30 seconds
}

Note: In the embedded case (Pgx.EMBEDDED_URL), the shutdownEngine() method will be called automatically via a JVM shutdown hook on exit. Specifically, the shutdown hook is invoked once all the non-daemon threads of the application exit.

We recommend that you do not terminate your PGX application forcibly with kill -9, as it will not clear the temp directory (see tmp_dir in the engine configuration guide).