Package com.tangosol.net

Class Coherence

java.lang.Object

com.tangosol.net.Coherence

All Implemented Interfaces:

AutoCloseable

public class Coherence
extends Object
implements AutoCloseable

A Coherence instance encapsulates and controls one or more Session instances.

A Coherence instance is typically created from a CoherenceConfiguration which contains one or more SessionConfiguration instances. The Coherence instance is then started which in turn creates and starts the configured Sessions. When the Coherence instance is closed all of the Session instances being managed are also closed.

An example of creating and starting a Coherence instance is shown below:

    SessionConfiguration session = SessionConfiguration.builder()
            .named("Prod")
            .withConfigUri("cache-config.xml")
            .build();

    CoherenceConfiguration cfg = CoherenceConfiguration.builder()
            .withSession(SessionConfiguration.defaultSession())
            .withSession(session)
            .build();

    Coherence coherence = Coherence.create(cfg);

    coherence.start();
 

Since:

20.12

Author:

Jonathan Knight 2020.10.26

See Also:

• CoherenceConfiguration
• SessionConfiguration

Nested Class Summary

Nested Classes

Modifier and Type	Class	Description
static class	Coherence.Builder	A builder to build Coherence instances.
static interface	Coherence.LifecycleListener	An interface implemented by listeners of CoherenceLifecycleEvents.
static enum	Coherence.Mode	An enum representing the different modes that a Coherence instance can run in.

Field Summary

Fields

Modifier and Type	Field	Description
static final String	DEFAULT_NAME	The default session name.
static final String	DEFAULT_SCOPE	The default scope name.
static final com.oracle.coherence.common.util.Duration	DEFAULT_START_TIMEOUT	The default start up timeout.
static final String	PROP_START_TIMEOUT	The system property to use to set the default timeout to wait for Coherence instances to start.
static final String	SYS_CCF_URI	The name of the System configuration uri.
static final String	SYSTEM_SCOPE	The System scope name.
static final String	SYSTEM_SESSION	The System session name.

Method Summary

Modifier and Type	Method	Description
Coherence	addSession(SessionConfiguration config)	Add a session to this Coherence instance.
Coherence	addSessionIfAbsent(SessionConfiguration config)	Add a session to this Coherence instance, iff a session configuration is not already present in this Coherence instance with the specified name.
Coherence	addSessionIfAbsent(String sName, Supplier<SessionConfiguration> supplier)	Add a session to this Coherence instance, iff a session configuration is not already present in this Coherence instance with the specified name.
static Coherence.Builder	builder(CoherenceConfiguration config)	Returns a Coherence.Builder instance that can build a Coherence instance using the specified CoherenceConfiguration.
static Coherence.Builder	builder(CoherenceConfiguration config, Coherence.Mode mode)	Returns a Coherence.Builder instance that can build a Coherence instance using the specified CoherenceConfiguration.
static Coherence	client()	Return the default Coherence client instance, creating it if it does not already exist.
static Coherence	client(Coherence.Mode mode)	Return the default Coherence client instance, creating it if it does not already exist.
static Coherence	client(CoherenceConfiguration config)	Create a client Coherence instance from the specified CoherenceConfiguration.
static Coherence.Builder	clientBuilder(CoherenceConfiguration config)	Returns a Coherence.Builder instance that can build a Coherence instance using the specified CoherenceConfiguration.
static Coherence.Builder	clientBuilder(CoherenceConfiguration config, Coherence.Mode mode)	Returns a Coherence.Builder instance that can build a Coherence instance using the specified CoherenceConfiguration.
void	close()	Close this Coherence instance.
static void	closeAll()	Close all Coherence instances.
static Coherence	clusterMember()	Return the default Coherence cluster member instance, creating it if it does not already exist.
static Coherence	clusterMember(CoherenceConfiguration config)	Create a Coherence instance from the specified CoherenceConfiguration.
static Coherence.Builder	clusterMemberBuilder(CoherenceConfiguration config)	Returns a Coherence.Builder instance that can build a Coherence instance using the specified CoherenceConfiguration.
static Coherence	create()	Return the default Coherence instance, creating it if it does not already exist.
static Coherence	create(CoherenceConfiguration config)	Create a default Coherence instance.
static Coherence	create(CoherenceConfiguration config, Coherence.Mode mode)	Create a default Coherence instance.
static Coherence	create(CoherenceConfiguration config, Coherence.Mode mode, ClassLoader loader)	Create a default Coherence instance.
static Optional<Session>	findSession(String sName)	Find the Session instance with the given name across all Coherence instances.
static Collection<Session>	findSessionsByScope(String sScope)	Find the Session instances with the given scope name across all Coherence instances.
static Coherence	fixedClient()	Create a default Coherence client instance, creating it if it does not already exist.
static Coherence	fixedClient(CoherenceConfiguration config)	Create a client Coherence instance from the specified CoherenceConfiguration.
static Coherence.Builder	fixedClientBuilder(CoherenceConfiguration config)	Returns a Coherence.Builder instance that can build a Coherence instance using the specified CoherenceConfiguration.
Cluster	getCluster()	Return a Cluster object for Coherence services.
CoherenceConfiguration	getConfiguration()	Returns the configuration used by this Coherence instance.
static Coherence	getInstance()	Returns a Coherence instance created or null if no Coherence instance exists.
static Coherence	getInstance(ClassLoader loader)	Returns a Coherence instance created or null if no Coherence instance exists.
static Coherence	getInstance(String sName)	Returns the named Coherence instance or null if the name is null or no Coherence instance exists with the specified name.
static Coherence	getInstance(String sName, ClassLoader loader)	Returns the named Coherence instance or null if the name is null or no Coherence instance exists with the specified name.
static Collection<Coherence>	getInstances()	Returns all of the Coherence instances.
static Collection<Coherence>	getInstances(ClassLoader loader)	Returns all of the Coherence instances.
InterceptorRegistry	getInterceptorRegistry()	Return the InterceptorRegistry for this Coherence instance.
Registry	getManagement()	Returns the current management registry.
Coherence.Mode	getMode()	Return the Coherence.Mode that this instance is running as.
String	getName()	Returns the name of this Coherence instance.
ResourceRegistry	getResourceRegistry()	Return the ResourceRegistry for this Coherence instance.
Session	getSession()	Obtain the default Session from the Coherence instance.
Session	getSession(String sName)	Obtain the Session from the Coherence instance that was configured with the specified configuration name.
Optional<Session>	getSessionIfPresent(String sName)	Obtain the Session from the Coherence instance that was configured with the specified configuration name.
Set<String>	getSessionNames()	Return a set of session names that this Coherence instance has.
Set<String>	getSessionScopeNames()	Return a set of session scope names that this Coherence instance has.
Collection<Session>	getSessionsWithScope(String sScope)	Obtain all the Sessions from the Coherence instance that are configured with the specified scope name.
boolean	hasSession(String sName)	Returns true if this Coherence instance can provide a Session with the specified name.
boolean	isActive()
boolean	isClosed()	Return true if this Coherence instance has been closed.
boolean	isStarted()	Return true if this Coherence instance has been started.
static void	main(String[] args)	Start a Coherence server.
protected static void	removeInstance(String sName)
protected static void	removeInstance(String sName, ClassLoader loader)
CompletableFuture<Coherence>	start()	Asynchronously start this Coherence instance.
Coherence	startAndWait()	Start this Coherence instance and block until Coherence has started.
Coherence	startAndWait(com.oracle.coherence.common.util.Duration timeout)	Start this Coherence instance and block until Coherence has started.
void	startOnCallingThread()	Start this Coherence instance.
String	toString()
CompletableFuture<Void>	whenClosed()	Obtain a CompletableFuture that will be completed when this Coherence instance has closed.
CompletableFuture<Coherence>	whenStarted()	Obtain a CompletableFuture that will be completed when this Coherence instance has started.

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait

Field Details

SYS_CCF_URI

public static final String SYS_CCF_URI

The name of the System configuration uri.

See Also:

• Constant Field Values

SYSTEM_SCOPE

public static final String SYSTEM_SCOPE

The System scope name.

See Also:

• Constant Field Values

SYSTEM_SESSION

public static final String SYSTEM_SESSION

The System session name.

See Also:

• Constant Field Values

DEFAULT_SCOPE

public static final String DEFAULT_SCOPE

The default scope name.

See Also:

• Constant Field Values

DEFAULT_NAME

public static final String DEFAULT_NAME

The default session name.

See Also:

• Constant Field Values

PROP_START_TIMEOUT

public static final String PROP_START_TIMEOUT

The system property to use to set the default timeout to wait for Coherence instances to start.

See Also:

• Constant Field Values

DEFAULT_START_TIMEOUT

public static final com.oracle.coherence.common.util.Duration DEFAULT_START_TIMEOUT

The default start up timeout.

Method Details

create

public static Coherence create()

Return the default Coherence instance, creating it if it does not already exist.

Returns:

a default Coherence instance

create

public static Coherence create(CoherenceConfiguration config)

Create a default Coherence instance.

Parameters:

config - the configuration to use to create the Coherence instance

Returns:

a default Coherence instance

create

public static Coherence create(CoherenceConfiguration config,
 Coherence.Mode mode)

Create a default Coherence instance.

Parameters:

config - the configuration to use to create the Coherence instance

mode - the Coherence.Mode the Coherence instance will run in

Returns:

a default Coherence instance

create

public static Coherence create(CoherenceConfiguration config,
 Coherence.Mode mode,
 ClassLoader loader)

Create a default Coherence instance.

Parameters:

config - the configuration to use to create the Coherence instance

mode - the Coherence.Mode the Coherence instance will run in

loader - the ClassLoader associated with the Coherence instance

Returns:

a default Coherence instance

builder

public static Coherence.Builder builder(CoherenceConfiguration config)

Returns a Coherence.Builder instance that can build a Coherence instance using the specified CoherenceConfiguration.

The Coherence instance built by the Builder will be a cluster member. Coherence auto-start services will be managed by a DefaultCacheServer instance for each configured session.

Parameters:

config - the CoherenceConfiguration to use to build the Coherence instance

Returns:

a Coherence.Builder instance that can build a Coherence instance using the specified CoherenceConfiguration

builder

public static Coherence.Builder builder(CoherenceConfiguration config,
 Coherence.Mode mode)

Returns a Coherence.Builder instance that can build a Coherence instance using the specified CoherenceConfiguration.

The Coherence instance built by the Builder will be a cluster member. Coherence auto-start services will be managed by a DefaultCacheServer instance for each configured session.

Parameters:

config - the CoherenceConfiguration to use to build the Coherence instance

mode - the Coherence.Mode the Coherence instance will run in

Returns:

a Coherence.Builder instance that can build a Coherence instance using the specified CoherenceConfiguration

clusterMember

public static Coherence clusterMember()

Return the default Coherence cluster member instance, creating it if it does not already exist.

The Coherence instance built by the Builder will be a cluster member.

Returns:

a default Coherence instance

clusterMember

public static Coherence clusterMember(CoherenceConfiguration config)

Create a Coherence instance from the specified CoherenceConfiguration.

The Coherence instance built by the Builder will be a cluster member.

Parameters:

config - the configuration to use to create the Coherence instance

Returns:

a Coherence instance from the specified CoherenceConfiguration

client

public static Coherence client()

Return the default Coherence client instance, creating it if it does not already exist.

If using the default Coherence cache configuration file, this will configure Coherence to be an Extend client.

If using the default Coherence Concurrent extensions, this will configure Coherence Concurrent to be an Extend client.

Returns:

a default Coherence instance

client

public static Coherence client(Coherence.Mode mode)

Return the default Coherence client instance, creating it if it does not already exist.

If using the default Coherence cache configuration file, this will configure Coherence to be an Extend client.

If using the default Coherence Concurrent extensions, this will configure Coherence Concurrent to be an Extend client.

Parameters:

mode - the default mode to run the Coherence instance

Returns:

a default Coherence instance

client

public static Coherence client(CoherenceConfiguration config)

Create a client Coherence instance from the specified CoherenceConfiguration.

If using the default Coherence cache configuration file, this will configure Coherence to be an Extend client.

If using the default Coherence Concurrent extensions, this will configure Coherence Concurrent to be an Extend client.

Parameters:

config - the configuration to use to create the Coherence instance

Returns:

a Coherence instance from the specified CoherenceConfiguration

fixedClient

public static Coherence fixedClient()

Create a default Coherence client instance, creating it if it does not already exist.

If using the default Coherence cache configuration file, this will configure Coherence to be an Extend client.

If using the default Coherence cache configuration file, this will configure Coherence to be an Extend client using a fixed address configured with the parameters coherence.extend.address and coherence.extend.port.

Returns:

a default Coherence instance

fixedClient

public static Coherence fixedClient(CoherenceConfiguration config)

Create a client Coherence instance from the specified CoherenceConfiguration.

If using the default Coherence cache configuration file, this will configure Coherence to be an Extend client.

If using the default Coherence cache configuration file, this will configure Coherence to be an Extend client using a fixed address configured with the parameters coherence.extend.address and coherence.extend.port.

Parameters:

config - the configuration to use to create the Coherence instance

Returns:

a Coherence instance from the specified CoherenceConfiguration

clusterMemberBuilder

public static Coherence.Builder clusterMemberBuilder(CoherenceConfiguration config)

Returns a Coherence.Builder instance that can build a Coherence instance using the specified CoherenceConfiguration.

The Coherence instance built by the Builder will be a cluster member. Coherence auto-start services will be managed by a DefaultCacheServer instance for each configured session.

Returns:

a Coherence.Builder instance that can build a Coherence instance using the specified CoherenceConfiguration

clientBuilder

public static Coherence.Builder clientBuilder(CoherenceConfiguration config)

Returns a Coherence.Builder instance that can build a Coherence instance using the specified CoherenceConfiguration.

The Coherence instance built by the Builder will be a client, it will not start or join a Coherence cluster.

If using the default Coherence cache configuration file, this will configure Coherence to be an Extend client.

If using the default Coherence Concurrent extensions, this will configure Coherence Concurrent to be an Extend client.

Parameters:

config - the CoherenceConfiguration to configure the Coherence instance

Returns:

a Coherence.Builder instance that can build a Coherence instance using the specified CoherenceConfiguration

clientBuilder

public static Coherence.Builder clientBuilder(CoherenceConfiguration config,
 Coherence.Mode mode)

Returns a Coherence.Builder instance that can build a Coherence instance using the specified CoherenceConfiguration.

The Coherence instance built by the Builder will be a client, it will not start or join a Coherence cluster.

If using the default Coherence cache configuration file, this will configure Coherence to be an Extend client.

If using the default Coherence Concurrent extensions, this will configure Coherence Concurrent to be an Extend client.

Parameters:

config - the CoherenceConfiguration to configure the Coherence instance

mode - the default mode to run the Coherence instance

Returns:

a Coherence.Builder instance that can build a Coherence instance using the specified CoherenceConfiguration

fixedClientBuilder

public static Coherence.Builder fixedClientBuilder(CoherenceConfiguration config)

Returns a Coherence.Builder instance that can build a Coherence instance using the specified CoherenceConfiguration.

The Coherence instance built by the Builder will be a client using a fixed Extend address, it will not start or join a Coherence cluster.

If using the default Coherence cache configuration file, this will configure Coherence to be an Extend client using a fixed address configured with the parameters coherence.extend.address and coherence.extend.port.

If using the default Coherence Concurrent extensions, this will configure Coherence Concurrent to be an Extend client.

Returns:

a Coherence.Builder instance that can build a Coherence instance using the specified CoherenceConfiguration

getInstances

public static Collection<Coherence> getInstances()

Returns all of the Coherence instances.

Returns:

all of the Coherence instances

getInstances

public static Collection<Coherence> getInstances(ClassLoader loader)

Returns all of the Coherence instances.

Parameters:

loader - the ClassLoader to obtain instances

Returns:

all of the Coherence instances

removeInstance

protected static void removeInstance(String sName)

removeInstance

protected static void removeInstance(String sName,
 ClassLoader loader)

getInstance

public static Coherence getInstance(String sName)

Returns the named Coherence instance or null if the name is null or no Coherence instance exists with the specified name.

Parameters:

sName - the name of the Coherence instance to return

Returns:

the named Coherence instance or null if no Coherence instance exists with the specified name

getInstance

public static Coherence getInstance(String sName,
 ClassLoader loader)

Returns the named Coherence instance or null if the name is null or no Coherence instance exists with the specified name.

Parameters:

sName - the name of the Coherence instance to return

loader - the ClassLoader associated with the Coherence instance

Returns:

the named Coherence instance or null if no Coherence instance exists with the specified name

getInstance

public static Coherence getInstance()

Returns a Coherence instance created or null if no Coherence instance exists.

This method is useful if only a single Coherence instance exists in an application. If multiple instances exists the actual instance returned is undetermined.

Returns:

a Coherence instance created

getInstance

public static Coherence getInstance(ClassLoader loader)

Returns a Coherence instance created or null if no Coherence instance exists.

This method is useful if only a single Coherence instance exists in an application. If multiple instances exists the actual instance returned is undetermined.

Parameters:

loader - the ClassLoader associated with the Coherence instance

Returns:

a Coherence instance created

findSession

public static Optional<Session> findSession(String sName)

Find the Session instance with the given name across all Coherence instances.

Parameters:

sName - the Session name to find

Returns:

the an Optional containing the Session with the specified name, or an empty optional if the session does not exist

findSessionsByScope

public static Collection<Session> findSessionsByScope(String sScope)

Find the Session instances with the given scope name across all Coherence instances.

Parameters:

sScope - the scope name of the Sessions to find

Returns:

the an Optional containing the Session with the specified name, or an empty optional if the session does not exist

closeAll

public static void closeAll()

Close all Coherence instances. If starting Coherence instances ensured the Coherence Cluster instance then calling this method will also fully shutdown Coherence.

getName

public String getName()

Returns the name of this Coherence instance.

Returns:

the name of this Coherence instance

getMode

public Coherence.Mode getMode()

Return the Coherence.Mode that this instance is running as.

Returns:

the Coherence.Mode that this instance is running as

getConfiguration

public CoherenceConfiguration getConfiguration()

Returns the configuration used by this Coherence instance.

Returns:

the configuration used by this Coherence instance

hasSession

public boolean hasSession(String sName)

Returns true if this Coherence instance can provide a Session with the specified name.

Parameters:

sName - the name of the Session

Returns:

true if this Coherence instance can provide a Session with the specified name

getSessionNames

public Set<String> getSessionNames()

Return a set of session names that this Coherence instance has.

Returns:

a set of session names that this Coherence instance has

getSessionScopeNames

public Set<String> getSessionScopeNames()

Return a set of session scope names that this Coherence instance has.

Returns:

a set of session scope names that this Coherence instance has

getSession

public Session getSession()

Obtain the default Session from the Coherence instance.

Returns:

the default Session

Throws:

IllegalStateException - if this instance has been closed

getSessionIfPresent

public Optional<Session> getSessionIfPresent(String sName)

Obtain the Session from the Coherence instance that was configured with the specified configuration name.

Parameters:

sName - the name of the Session to return

Returns:

an Optional containing the named Session or an empty Optional if this Coherence instance does not contain the named session

Throws:

IllegalStateException - if this instance has been closed

getSession

public Session getSession(String sName)

Obtain the Session from the Coherence instance that was configured with the specified configuration name.

Parameters:

sName - the name of the Session to return

Returns:

the named Session

Throws:

IllegalArgumentException - if no session exists for the specified name

IllegalStateException - if this instance has been closed

addSession

public Coherence addSession(SessionConfiguration config)

Add a session to this Coherence instance.

The session name must be globally unique across all Coherence instances.

If this Coherence instance is already running, then the session will be started immediately.

Parameters:

config - the configuration of the session to add

Returns:

this Coherence instance

Throws:

IllegalArgumentException - if the configuration does not have a name

IllegalStateException - if this Coherence instance is closed

addSessionIfAbsent

public Coherence addSessionIfAbsent(SessionConfiguration config)

Add a session to this Coherence instance, iff a session configuration is not already present in this Coherence instance with the specified name.

The session name must be globally unique across all Coherence instances.

If this Coherence instance is already running, then the session will be started immediately.

Parameters:

config - the configuration of the session to add

Returns:

this Coherence instance

Throws:

IllegalArgumentException - if the configuration does not have a name

IllegalStateException - if this Coherence instance is closed

addSessionIfAbsent

public Coherence addSessionIfAbsent(String sName,
 Supplier<SessionConfiguration> supplier)

Add a session to this Coherence instance, iff a session configuration is not already present in this Coherence instance with the specified name.

The session name must be globally unique across all Coherence instances.

If this Coherence instance is already running, then the session will be started immediately.

Parameters:

sName - the name of the session to add

supplier - a Supplier used to provide the configuration of the session to add, if the session is not present

Returns:

this Coherence instance

Throws:

IllegalArgumentException - if the configuration name does not match the name argument

IllegalArgumentException - if the configuration does not have a name

IllegalStateException - if this Coherence instance is closed

getSessionsWithScope

public Collection<Session> getSessionsWithScope(String sScope)

Obtain all the Sessions from the Coherence instance that are configured with the specified scope name.

Parameters:

sScope - the scope name of the Sessions to return

Returns:

the Session instances with the specified scope or an empty Collection if no Sessions have the required scope name

Throws:

IllegalStateException - if this instance has been closed

whenStarted

public CompletableFuture<Coherence> whenStarted()

Obtain a CompletableFuture that will be completed when this Coherence instance has started.

Returns:

a CompletableFuture that will be completed when this Coherence instance has started

whenClosed

public CompletableFuture<Void> whenClosed()

Obtain a CompletableFuture that will be completed when this Coherence instance has closed.

Returns:

a CompletableFuture that will be completed when this Coherence instance has closed

isStarted

public boolean isStarted()

Return true if this Coherence instance has been started.

Returns:

true if this Coherence instance has been started

isClosed

public boolean isClosed()

Return true if this Coherence instance has been closed.

Returns:

true if this Coherence instance has been closed

startAndWait

public Coherence startAndWait()
                       throws InterruptedException

Start this Coherence instance and block until Coherence has started.

This method will wait for the specified timeout.

If this instance already been started and has not been closed this method call is a no-op.

Returns:

the running Coherence instance

Throws:

InterruptedException - if Coherence does not start within the timeout

startAndWait

public Coherence startAndWait(com.oracle.coherence.common.util.Duration timeout)
                       throws InterruptedException

Start this Coherence instance and block until Coherence has started.

This method will wait for the specified timeout.

If this instance already been started and has not been closed this method call is a no-op.

Parameters:

timeout - the timeout duration to wait for Coherence to start

Returns:

the running Coherence instance

Throws:

InterruptedException - if Coherence does not start within the timeout

start

public CompletableFuture<Coherence> start()

Asynchronously start this Coherence instance.

If this instance already been started and has not been closed this method call is a no-op.

Returns:

a CompletableFuture that will be completed when this Coherence instance has started

startOnCallingThread

public void startOnCallingThread()

Start this Coherence instance.

If this instance already been started and has not been closed this method call is a no-op.

isActive

public boolean isActive()

close

public void close()

Close this Coherence instance.

Specified by:

close in interface AutoCloseable

getResourceRegistry

public ResourceRegistry getResourceRegistry()

Return the ResourceRegistry for this Coherence instance.

Returns:

the ResourceRegistry for this Coherence instance

getInterceptorRegistry

public InterceptorRegistry getInterceptorRegistry()

Return the InterceptorRegistry for this Coherence instance.

Returns:

the InterceptorRegistry for this Coherence instance

getCluster

public Cluster getCluster()

Return a Cluster object for Coherence services.

Returns:

a Cluster object, which may or may not be running

getManagement

public Registry getManagement()

Returns the current management registry.

Returns:

the current management registry or null if the management is disabled on this node

Since:

22.06

main

public static void main(String[] args)

Start a Coherence server.

This method will start Coherence configured with a single session that uses the default cache configuration file. This is effectively the same as running DefaultCacheServer.main(String[]) without any arguments but will additionally bootstrap a Coherence instance with the default name DEFAULT_NAME and an unscoped Session with the same default name.

Parameters:

args - the program arguments.

toString

public String toString()

Overrides:

toString in class Object