This chapter shows the APIs for connecting to a PGX server instance (both embedded and remote) and how to start/stop the PGX engine.
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.
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.
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.
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.
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).