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);

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");

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).