14.1 Design of the Graph Server (PGX) API

This guide focuses on the design of the graph server (PGX) API.

The design of the PGX API reflects consideration of the following situations:

• Multiple clients may concurrently be accessing a single running instance of PGX, sharing its resources. Each client needs to maintain its own isolated workspace (session).
• Graph and property data can be large in size and therefore that data only resides on the server side.
• Some graph analysis may take a significant amount of time.
• Clients may not reside in the same address space (JVM) as PGX. Actually, clients may not even be Java applications.

Client Sessions

In PGX, each client maintains its own session, an isolated, private workspace. Therefore, clients first have to obtain a PgxSession object from a PGX ServerInstance before they can perform any analysis.

Asynchronous Execution

The PGX API is designed for asynchronous execution. That means that each computationally intensive method in the PGX API immediately returns a PgxFuture object without waiting for the request to finish. The PgxFuture class implements the Future interface, which can be used to retrieve the result of a computation at some point in the future.

Note:

The asynchronous execution aspect of this design facilitates multiple (remote) clients submitting requests to a single server. A request from one client may be queued up to wait until PGX resources become available. The asynchronous API allows the client (or calling thread) to work on other tasks until PGX completes the request.

No Direct References

The PGX API does not return objects with direct reference to PGX internal objects (such as the graph or its properties) to the client. This is because:

• The client might not be in the same JVM as the server
• The graph instance might be shared by multiple clients

Instead, the PGX API only returns lightweight, stateless pointer objects to those objects. These pointer objects only holds the ID(name) of the server-side object to which they are pointing.

Resource Management Considerations

The graph server (PGX), being an in-memory analytic engine, might allocate large amounts of memory to hold the graph data of clients. Therefore, it is important that client sessions clean up their resources once they have ended. The PGX API supports several features to make this easier:

• Every object returned by the PGX API pointing to a server-side resource implements the Destroyable interface, which means all memory-consuming client-side objects can be destroyed the same way. For example:

  PgxGraph myGraph = ...
  myGraph.destroyAsync(); // request destruction of myGraph, don't wait for response
  try {
    myGraph.destroy();   // blocks caller thread until destruction was done
  } catch (ExecutionException e) {
    // destruction failed
  }

• Destroyable extends AutoClosable, so users can leverage Java's built-in resource management syntax:

  try (PgxGraph myGraph = session.readGraphWithProperties(config)) {
    // do something with myGraph
  }
  // myGraph is destroyed

• Session time out. In some cases, the PGX server will remove the session and all its data automatically. This can occur when a client fails to destroy either the data or its session, or if it does not hear from the session after a configurable timeout. See Configuration Parameters for the Graph Server (PGX) Engine for more information to configure timeout parameters.