oracle.pgx.api

Class PgxSession

java.lang.Object

oracle.pgx.api.Destroyable

oracle.pgx.api.PgxManagedObject

oracle.pgx.api.PgxSession

All Implemented Interfaces:

AutoCloseable

public class PgxSession
extends PgxManagedObject

A PGX session represents an active user connected to a ServerInstance. Every session gets a workspace assigned on the server, which can be used to read graph data, create transient data or custom algorithms for the sake of graph analysis. Once a session gets destroyed, all data in the session workspace gets freed.

Method Summary

Methods

Modifier and Type	Method and Description
Analyst	createAnalyst() Creates a new Analyst.
Deque<GraphMetaData>	getAvailableSnapshots(GraphConfig config) Blocking version of getAvailableSnapshotsAsync(GraphConfig).
Deque<GraphMetaData>	getAvailableSnapshots(PgxGraph snapshot) Blocking version of getAvailableSnapshotsAsync(PgxGraph).
PgxFuture<Deque<GraphMetaData>>	getAvailableSnapshotsAsync(GraphConfig config) Gets a list of available in-memory snapshots of a graph described by a graph configuration.
PgxFuture<Deque<GraphMetaData>>	getAvailableSnapshotsAsync(PgxGraph snapshot) Gets a list of available in-memory snapshots of a given snapshot.
String	getId()
Long	getIdleTimeout() Gets the idle timeout of this session.
String	getName() alias for getId()
ServerInstance	getServerInstance()
String	getSource() Gets the source.
Long	getTaskTimeout() Gets the task timeout of this session.
PgxGraph	readGraphWithProperties(GraphConfig config) Blocking version of readGraphWithPropertiesAsync(GraphConfig).
PgxGraph	readGraphWithProperties(GraphConfig config, boolean forceUpdateIfNotFresh) Blocking version of readGraphWithPropertiesAsync(GraphConfig, boolean).
PgxGraph	readGraphWithProperties(GraphConfig config, boolean forceUpdateIfNotFresh, String newGraphName) Blocking version of readGraphWithPropertiesAsync(GraphConfig, boolean, String).
PgxGraph	readGraphWithProperties(GraphConfig config, long maxAge, TimeUnit maxAgeTimeUnit) Blocking version of readGraphWithPropertiesAsync(GraphConfig, long, TimeUnit).
PgxGraph	readGraphWithProperties(GraphConfig config, long maxAge, TimeUnit maxAgeTimeUnit, boolean blockIfFull, String newGraphName) Blocking version of readGraphWithPropertiesAsync(GraphConfig, long, TimeUnit, boolean, String).
PgxGraph	readGraphWithProperties(GraphConfig config, String newGraphName) Blocking version of readGraphWithPropertiesAsync(GraphConfig, String).
PgxGraph	readGraphWithProperties(String path) Blocking version of readGraphWithPropertiesAsync(String).
PgxGraph	readGraphWithProperties(String path, String newGraphName) Blocking version of readGraphWithPropertiesAsync(String, String).
PgxFuture<PgxGraph>	readGraphWithPropertiesAsync(GraphConfig config) Reads a graph and its properties, specified a graph config, into memory.
PgxFuture<PgxGraph>	readGraphWithPropertiesAsync(GraphConfig config, boolean forceUpdateIfNotFresh) Reads a graph and its properties, specified a graph config, into memory.
PgxFuture<PgxGraph>	readGraphWithPropertiesAsync(GraphConfig config, boolean forceUpdateIfNotFresh, String newGraphName) Reads a graph and its properties, specified a graph config, into memory.
PgxFuture<PgxGraph>	readGraphWithPropertiesAsync(GraphConfig config, long maxAge, TimeUnit maxAgeTimeUnit) Reads a graph and its properties, specified a graph config, into memory.
PgxFuture<PgxGraph>	readGraphWithPropertiesAsync(GraphConfig config, long maxAge, TimeUnit maxAgeTimeUnit, boolean blockIfFull, String newGraphName) Reads a graph and its properties, specified a graph config, into memory.
PgxFuture<PgxGraph>	readGraphWithPropertiesAsync(GraphConfig config, String newGraphName) Reads a graph and its properties, specified a graph config, into memory.
PgxFuture<PgxGraph>	readGraphWithPropertiesAsync(String path) Reads a graph and its properties, specified by a path to a graph config, into memory.
PgxFuture<PgxGraph>	readGraphWithPropertiesAsync(String path, String newGraphName) Reads a graph and its properties, specified by a path to a graph config, into memory.
void	setSnapshot(PgxGraph graph, GraphMetaData metaData) Blocking version of setSnapshotAsync(PgxGraph, GraphMetaData).
void	setSnapshot(PgxGraph graph, GraphMetaData metaData, boolean forceDeleteProperties) Blocking version of setSnapshotAsync(PgxGraph, GraphMetaData, boolean).
void	setSnapshot(PgxGraph graph, long creationTimestamp) Blocking version of setSnapshotAsync(PgxGraph, long).
void	setSnapshot(PgxGraph graph, long creationTimestamp, boolean forceDeleteProperties) Blocking version of setSnapshotAsync(PgxGraph, long, boolean).
PgxFuture<Void>	setSnapshotAsync(PgxGraph graph, GraphMetaData metaData) Sets a graph to a specific snapshot.
PgxFuture<Void>	setSnapshotAsync(PgxGraph graph, GraphMetaData metaData, boolean forceDeleteTransientProperties) Sets a graph to a specific snapshot.
PgxFuture<Void>	setSnapshotAsync(PgxGraph graph, long creationTimestamp) Sets a graph to a specific snapshot.
PgxFuture<Void>	setSnapshotAsync(PgxGraph graph, long creationTimestamp, boolean forceDeleteTransientProperties) Sets a graph to a specific snapshot.
String	toString()

Methods inherited from class oracle.pgx.api.PgxManagedObject

equals, hashCode

Methods inherited from class oracle.pgx.api.Destroyable

close, destroy, destroyAsync

Methods inherited from class java.lang.Object

getClass, notify, notifyAll, wait, wait, wait

Method Detail

createAnalyst

public Analyst createAnalyst()

Creates a new Analyst. See Analyst

Returns:

the analyst

getAvailableSnapshots

@Generated(value="src/python/synchronize.py")
public Deque<GraphMetaData> getAvailableSnapshots(GraphConfig config)
                                           throws InterruptedException,
                                                  ExecutionException

Blocking version of getAvailableSnapshotsAsync(GraphConfig). Calls getAvailableSnapshotsAsync(GraphConfig) and waits for returned PgxFuture to complete.

Throws:

InterruptedException - if the caller thread gets interrupted while waiting for completion.

ExecutionException - if any exception occurred during asynchronous execution. The actual exception will be nested.

getAvailableSnapshots

@Generated(value="src/python/synchronize.py")
public Deque<GraphMetaData> getAvailableSnapshots(PgxGraph snapshot)
                                           throws InterruptedException,
                                                  ExecutionException

Blocking version of getAvailableSnapshotsAsync(PgxGraph). Calls getAvailableSnapshotsAsync(PgxGraph) and waits for returned PgxFuture to complete.

Throws:

InterruptedException - if the caller thread gets interrupted while waiting for completion.

ExecutionException - if any exception occurred during asynchronous execution. The actual exception will be nested.

getAvailableSnapshotsAsync

public PgxFuture<Deque<GraphMetaData>> getAvailableSnapshotsAsync(GraphConfig config)

Gets a list of available in-memory snapshots of a graph described by a graph configuration. Note that only persistent graphs (graphs with a graph config pointing to a data source) might have more than one in-memory snapshot. If the given graph name is a transient (private, session-bound) graph, this method will return a list with the given graph as only element. See #isTransient().

Returns:

A list of graph meta data objects, each belonging to a snapshot of the given graph currently loaded into memory. The list is descending ordered by the PgxGraph#getCreationTimestamp(TimeUnit) value (milliseconds since Jan 1st 1970) - the timestamp when the snapshot was created.

getAvailableSnapshotsAsync

public PgxFuture<Deque<GraphMetaData>> getAvailableSnapshotsAsync(PgxGraph snapshot)

Gets a list of available in-memory snapshots of a given snapshot. Note that only persistent graphs (graphs with a graph config pointing to a data source) might have more than one in-memory snapshot. If the given graph name is a transient (private, session-bound) graph, this method will return a list with the given graph as only element. See PgxGraph.isTransient().

Returns:

A list of graph meta data objects, each belonging to a snapshot of the given graph currently loaded into memory. The list is descending ordered by the PgxGraph#getCreationTimestamp(TimeUnit) value (milliseconds since Jan 1st 1970) - the timestamp when the snapshot was created.

getId

public String getId()

Returns:

the Session ID

getIdleTimeout

public Long getIdleTimeout()

Gets the idle timeout of this session. A value of null indicates this session uses the default session idle timeout as specified by the PGX instance.

Returns:

the idle timeout in seconds. May be null.

getName

public String getName()

alias for getId()

Specified by:

getName in class PgxManagedObject

Returns:

name of this session

getServerInstance

public ServerInstance getServerInstance()

Returns:

returns the current instance of PGX

getSource

public String getSource()

Gets the source.

Returns:

the source

getTaskTimeout

public Long getTaskTimeout()

Gets the task timeout of this session. A value of null indicates this session uses the default session task timeout as specified by the PGX instance.

Returns:

the task timeout in seconds. May be null.

readGraphWithProperties

@Generated(value="src/python/synchronize.py")
public PgxGraph readGraphWithProperties(GraphConfig config)
                                 throws ExecutionException,
                                        InterruptedException

Blocking version of readGraphWithPropertiesAsync(GraphConfig). Calls readGraphWithPropertiesAsync(GraphConfig) and waits for returned PgxFuture to complete.

Throws:

InterruptedException - if the caller thread gets interrupted while waiting for completion.

ExecutionException - if any exception occurred during asynchronous execution. The actual exception will be nested.

readGraphWithProperties

@Generated(value="src/python/synchronize.py")
public PgxGraph readGraphWithProperties(GraphConfig config,
                                              boolean forceUpdateIfNotFresh)
                                 throws InterruptedException,
                                        ExecutionException

Blocking version of readGraphWithPropertiesAsync(GraphConfig, boolean). Calls readGraphWithPropertiesAsync(GraphConfig, boolean) and waits for returned PgxFuture to complete.

Throws:

InterruptedException - if the caller thread gets interrupted while waiting for completion.

ExecutionException - if any exception occurred during asynchronous execution. The actual exception will be nested.

readGraphWithProperties

@Generated(value="src/python/synchronize.py")
public PgxGraph readGraphWithProperties(GraphConfig config,
                                              boolean forceUpdateIfNotFresh,
                                              String newGraphName)
                                 throws InterruptedException,
                                        ExecutionException

Blocking version of readGraphWithPropertiesAsync(GraphConfig, boolean, String). Calls readGraphWithPropertiesAsync(GraphConfig, boolean, String) and waits for returned PgxFuture to complete.

Throws:

InterruptedException - if the caller thread gets interrupted while waiting for completion.

ExecutionException - if any exception occurred during asynchronous execution. The actual exception will be nested.

readGraphWithProperties

@Generated(value="src/python/synchronize.py")
public PgxGraph readGraphWithProperties(GraphConfig config,
                                              long maxAge,
                                              TimeUnit maxAgeTimeUnit)
                                 throws InterruptedException,
                                        ExecutionException

Blocking version of readGraphWithPropertiesAsync(GraphConfig, long, TimeUnit). Calls readGraphWithPropertiesAsync(GraphConfig, long, TimeUnit) and waits for returned PgxFuture to complete.

Throws:

InterruptedException - if the caller thread gets interrupted while waiting for completion.

ExecutionException - if any exception occurred during asynchronous execution. The actual exception will be nested.

readGraphWithProperties

@Generated(value="src/python/synchronize.py")
public PgxGraph readGraphWithProperties(GraphConfig config,
                                              long maxAge,
                                              TimeUnit maxAgeTimeUnit,
                                              boolean blockIfFull,
                                              String newGraphName)
                                 throws InterruptedException,
                                        ExecutionException

Blocking version of readGraphWithPropertiesAsync(GraphConfig, long, TimeUnit, boolean, String). Calls readGraphWithPropertiesAsync(GraphConfig, long, TimeUnit, boolean, String) and waits for returned PgxFuture to complete.

Throws:

InterruptedException - if the caller thread gets interrupted while waiting for completion.

ExecutionException - if any exception occurred during asynchronous execution. The actual exception will be nested.

readGraphWithProperties

@Generated(value="src/python/synchronize.py")
public PgxGraph readGraphWithProperties(GraphConfig config,
                                              String newGraphName)
                                 throws ExecutionException,
                                        InterruptedException

Blocking version of readGraphWithPropertiesAsync(GraphConfig, String). Calls readGraphWithPropertiesAsync(GraphConfig, String) and waits for returned PgxFuture to complete.

Throws:

InterruptedException - if the caller thread gets interrupted while waiting for completion.

ExecutionException - if any exception occurred during asynchronous execution. The actual exception will be nested.

readGraphWithProperties

public PgxGraph readGraphWithProperties(String path)
                                 throws ExecutionException,
                                        InterruptedException

Blocking version of readGraphWithPropertiesAsync(String). Calls readGraphWithPropertiesAsync(String) and waits for returned PgxFuture to complete.

Throws:

InterruptedException - if the caller thread gets interrupted while waiting for completion.

ExecutionException - if any exception occurred during asynchronous execution. The actual exception will be nested.

readGraphWithProperties

public PgxGraph readGraphWithProperties(String path,
                               String newGraphName)
                                 throws ExecutionException,
                                        InterruptedException

Blocking version of readGraphWithPropertiesAsync(String, String). Calls readGraphWithPropertiesAsync(String, String) and waits for returned PgxFuture to complete.

Throws:

InterruptedException - if the caller thread gets interrupted while waiting for completion.

ExecutionException - if any exception occurred during asynchronous execution. The actual exception will be nested.

readGraphWithPropertiesAsync

public PgxFuture<PgxGraph> readGraphWithPropertiesAsync(GraphConfig config)

Reads a graph and its properties, specified a graph config, into memory.

Parameters:

config - the graph config

readGraphWithPropertiesAsync

public PgxFuture<PgxGraph> readGraphWithPropertiesAsync(GraphConfig config,
                                               boolean forceUpdateIfNotFresh)

Reads a graph and its properties, specified a graph config, into memory.

Parameters:

config - the graph config

forceUpdateIfNotFresh - if another snapshot of the given graph already exists and this flag is true, a new snapshot will be loaded into memory in case that existing snapshot is not fresh (according to PgxGraph.isFresh()). If no other snapshot of that graph exists, this flag has no effect.

readGraphWithPropertiesAsync

public PgxFuture<PgxGraph> readGraphWithPropertiesAsync(GraphConfig config,
                                               boolean forceUpdateIfNotFresh,
                                               String newGraphName)

Reads a graph and its properties, specified a graph config, into memory.

Parameters:

config - the graph config

forceUpdateIfNotFresh - if another snapshot of the given graph already exists and this flag is true, a new snapshot will be loaded into memory in case that existing snapshot is not fresh (according to PgxGraph.isFresh()). If no other snapshot of that graph exists, this flag has no effect.

newGraphName - how the graph should be named. If null, a name will be generated. If a graph with that name already exists, the returned future will complete exceptionally.

readGraphWithPropertiesAsync

public PgxFuture<PgxGraph> readGraphWithPropertiesAsync(GraphConfig config,
                                               long maxAge,
                                               TimeUnit maxAgeTimeUnit)

Reads a graph and its properties, specified a graph config, into memory.

Parameters:

config - the graph config

maxAge - if another snapshot of the given graph already exists, the age of the latest existing snapshot will be compared to the given maxAge. If the latest snapshot is in the given range, it will be returned, otherwise a new snapshot will be created.

maxAgeTimeUnit - the time unit of the maxAge parameter

readGraphWithPropertiesAsync

public PgxFuture<PgxGraph> readGraphWithPropertiesAsync(GraphConfig config,
                                               long maxAge,
                                               TimeUnit maxAgeTimeUnit,
                                               boolean blockIfFull,
                                               String newGraphName)

Reads a graph and its properties, specified a graph config, into memory.

Parameters:

config - the graph config

maxAge - if another snapshot of the given graph already exists, the age of the latest existing snapshot will be compared to the given maxAge. If the latest snapshot is in the given range, it will be returned, otherwise a new snapshot will be created.

maxAgeTimeUnit - the time unit of the maxAge parameter

blockIfFull - if true and a new snapshot needs to be created but no more snapshots are allowed by the server configuration, the returned future will not complete until space becomes available. If full and this flage is false, the returned future will complete exceptionally instead.

newGraphName - how the graph should be named. If null, a name will be generated. If a graph with that name already exists, the returned future will complete exceptionally.

readGraphWithPropertiesAsync

public PgxFuture<PgxGraph> readGraphWithPropertiesAsync(GraphConfig config,
                                               String newGraphName)

Reads a graph and its properties, specified a graph config, into memory.

Parameters:

config - the graph config

newGraphName - how the graph should be named. If null, a name will be generated. If a graph with that name already exists, the returned future will complete exceptionally.

readGraphWithPropertiesAsync

public PgxFuture<PgxGraph> readGraphWithPropertiesAsync(String path)

Reads a graph and its properties, specified by a path to a graph config, into memory.

Parameters:

path - a path to a graph config. All protocols in Protocol are supported, e.g. 'hdfs:/path/to/config.json' or 'http://myserver.com/my-config.json'

readGraphWithPropertiesAsync

public PgxFuture<PgxGraph> readGraphWithPropertiesAsync(String path,
                                               String newGraphName)

Reads a graph and its properties, specified by a path to a graph config, into memory.

Parameters:

path - a path to a graph config. All protocols in Protocol are supported, e.g. 'hdfs:/path/to/config.json' or 'http://myserver.com/my-config.json'

newGraphName - how the graph should be named. If null, a name will be generated. If a graph with that name already exists, the returned future will complete exceptionally.

setSnapshot

@Generated(value="src/python/synchronize.py")
public void setSnapshot(PgxGraph graph,
                              GraphMetaData metaData)
                 throws InterruptedException,
                        ExecutionException

Blocking version of setSnapshotAsync(PgxGraph, GraphMetaData). Calls setSnapshotAsync(PgxGraph, GraphMetaData) and waits for returned PgxFuture to complete.

Throws:

InterruptedException - if the caller thread gets interrupted while waiting for completion.

ExecutionException - if any exception occurred during asynchronous execution. The actual exception will be nested.

setSnapshot

@Generated(value="src/python/synchronize.py")
public void setSnapshot(PgxGraph graph,
                              GraphMetaData metaData,
                              boolean forceDeleteProperties)
                 throws InterruptedException,
                        ExecutionException

Blocking version of setSnapshotAsync(PgxGraph, GraphMetaData, boolean). Calls setSnapshotAsync(PgxGraph, GraphMetaData, boolean) and waits for returned PgxFuture to complete.

Throws:

InterruptedException - if the caller thread gets interrupted while waiting for completion.

ExecutionException - if any exception occurred during asynchronous execution. The actual exception will be nested.

setSnapshot

@Generated(value="src/python/synchronize.py")
public void setSnapshot(PgxGraph graph,
                              long creationTimestamp)
                 throws InterruptedException,
                        ExecutionException

Blocking version of setSnapshotAsync(PgxGraph, long). Calls setSnapshotAsync(PgxGraph, long) and waits for returned PgxFuture to complete.

Throws:

InterruptedException - if the caller thread gets interrupted while waiting for completion.

ExecutionException - if any exception occurred during asynchronous execution. The actual exception will be nested.

setSnapshot

@Generated(value="src/python/synchronize.py")
public void setSnapshot(PgxGraph graph,
                              long creationTimestamp,
                              boolean forceDeleteProperties)
                 throws InterruptedException,
                        ExecutionException

Blocking version of setSnapshotAsync(PgxGraph, long, boolean). Calls setSnapshotAsync(PgxGraph, long, boolean) and waits for returned PgxFuture to complete.

Throws:

InterruptedException - if the caller thread gets interrupted while waiting for completion.

ExecutionException - if any exception occurred during asynchronous execution. The actual exception will be nested.

setSnapshotAsync

public PgxFuture<Void> setSnapshotAsync(PgxGraph graph,
                               GraphMetaData metaData)

Sets a graph to a specific snapshot. You can use this method to jump back and forth in time between various snapshots of the same graph. If successful, the given graph will point to the requested snapshot after the returned future completes.

Parameters:

graph - the graph to be checked out to a different version. Note that transient properties cannot be checked out to a different graph version. If the given graph contains any transient properties, the returned future will complete exceptionally with an UnsupportedOperationException set as cause. You can use setSnapshotAsync(PgxGraph, long, boolean) to force a checkout on a graph with transient properties.

metaData - the metaData object returned by getAvailableSnapshotsAsync(GraphConfig) identifying the version to be checked out

setSnapshotAsync

public PgxFuture<Void> setSnapshotAsync(PgxGraph graph,
                               GraphMetaData metaData,
                               boolean forceDeleteTransientProperties)

Sets a graph to a specific snapshot. You can use this method to jump back and forth in time between various snapshots of the same graph. If successful, the given graph will point to the requested snapshot after the returned future completes.

Parameters:

graph - the graph to be checked out to a different snapshot version

metaData - the metaData object returned by getAvailableSnapshotsAsync(GraphConfig) identifying the version to be checked out

forceDeleteTransientProperties - Graphs with transient properties cannot be checked out to a different version. If this flag is set to true, the checked out graph will no longer contain any transient properties. If false, the returned future will complete exceptionally with an UnsupportedOperationException as its cause.

setSnapshotAsync

public PgxFuture<Void> setSnapshotAsync(PgxGraph graph,
                               long creationTimestamp)

Sets a graph to a specific snapshot. You can use this method to jump back and forth in time between various snapshots of the same graph. If successful, the given graph will point to the requested snapshot after the returned future completes.

Parameters:

graph - the graph to be checked out to a different version. Note that transient properties cannot be checked out to a different graph version. If the given graph contains any transient properties, the returned future will complete exceptionally with an UnsupportedOperationException set as cause. You can use setSnapshotAsync(PgxGraph, long, boolean) to force a checkout on a graph with transient properties.

creationTimestamp - the creation timestamp (milliseconds since Jan 1st 1970) identifying the version to be checked out

setSnapshotAsync

public PgxFuture<Void> setSnapshotAsync(PgxGraph graph,
                               long creationTimestamp,
                               boolean forceDeleteTransientProperties)

Sets a graph to a specific snapshot. You can use this method to jump back and forth in time between various snapshots of the same graph. If successful, the given graph will point to the requested snapshot after the returned future completes.

Parameters:

graph - the graph to be checked out to a different snapshot version

creationTimestamp - the creation timestamp (milliseconds since Jan 1st 1970) identifying the version to be checked out

forceDeleteTransientProperties - Graphs with transient properties cannot be checked out to a different version. If this flag is set to true, the checked out graph will no longer contain any transient properties. If false, the returned future will complete exceptionally with an UnsupportedOperationException as its cause.

toString

public String toString()

Overrides:

toString in class PgxManagedObject