Package com.tangosol.net

Interface Session

All Superinterfaces:

AutoCloseable

All Known Implementing Classes:

CoherenceSession

public interface Session
extends AutoCloseable

A thread-safe mechanism to request Coherence-based resources, like NamedCaches, from a deployed module.

Resources provided by a Session are scoped to the Session. When a Session is closed, all resources are closed. Once closed, references to resources are no longer valid. Any attempt to use a closed Session or closed resource may throw an IllegalStateException.

The effect of closing a resource is specific to the type of resource. For example, resources provided by a Session may represent shared (ie: clustered) data-structures and services. In such circumstances, closing these resources only closes the Session-based representation, not the underlying shared infrastructure, which may remain active for other Sessions. Future requests of a Session for previously closed resources of this kind will likely yield a new reference to logically the same underlying resource. To destroy such resources, instead of close, resource-specific methods should be used.

Applications making use of Sessions are expected to maintain their own references to Sessions. Coherence provides no mechanism to identify and obtain previously created Sessions. Furthermore, applications are expected to correctly close Sessions when they are no longer required.

Author:

bo 2015.07.27

See Also:

• SessionProvider

Nested Class Summary

Nested Classes

Modifier and Type	Interface	Description
static interface	Session.Option	Deprecated. since 20.12 Session.Option has been replaced by SessionConfiguration

Method Summary

Modifier and Type	Method	Description
void	activate()	Activate this Session.
void	close(NamedCollection col)	Close and release the a NamedCollection.
static Session	create()	Obtain the default Session.
static Session	create(Session.Option... options)	Deprecated. since 20.12 use create(SessionConfiguration)
static Optional<Session>	create(SessionConfiguration configuration)	Possibly obtain a Session based on the specified configuration.
static Optional<Session>	create(SessionConfiguration configuration, Coherence.Mode mode)	Possibly obtain a Session based on the specified configuration.
static Optional<Session>	create(SessionConfiguration configuration, Coherence.Mode mode, Iterable<? extends EventInterceptor<?>> interceptors)	Possibly obtain a Session based on the specified configuration.
default <V> Publisher<V>	createPublisher(String sName)	Create a Publisher that can publish values into a NamedTopic.
default <V> Publisher<V>	createPublisher(String sName, Publisher.Option... options)	Create a Publisher that can publish values into a NamedTopic.
default <V> Subscriber<V>	createSubscriber(String sName)	Create a Subscriber that can subscribe to a NamedTopic.
default <V> Subscriber<V>	createSubscriber(String sName, Subscriber.Option... options)	Create a Subscriber that can subscribe to a NamedTopic.
void	destroy(NamedCollection col)	Destroy a NamedCollection.
static Session	ensure(SessionConfiguration configuration)	Obtain a Session based on the specified configuration or throw an IllegalStateException if a session could not be obtained.
static Session	ensure(SessionConfiguration configuration, Coherence.Mode mode)	Obtain a Session based on the specified configuration or throw an IllegalStateException if a session could not be obtained.
<K, V> NamedCache<K,V>	getCache(String sName, NamedMap.Option... options)	Acquire a NamedCache using the specified NamedMap.Options, for example a TypeAssertion.
default <E> NamedDeque<E>	getDeque(String sName)	Acquire a NamedDeque.
<E> NamedDeque<E>	getDeque(String sName, NamedCollection.Option... options)	Acquire a NamedDeque.
InterceptorRegistry	getInterceptorRegistry()	Return the InterceptorRegistry for this session.
<K, V> NamedMap<K,V>	getMap(String sName, NamedMap.Option... options)	Acquire a NamedMap using the specified NamedMap.Options, for example a TypeAssertion.
String	getName()	Return the name of this session, if available.
default <E> NamedQueue<E>	getQueue(String sName)	Acquire a NamedQueue.
<E> NamedQueue<E>	getQueue(String sName, NamedCollection.Option... options)	Acquire a NamedQueue.
ResourceRegistry	getResourceRegistry()	Return the ResourceRegistry for this session.
String	getScopeName()	Return the scope name of this cache factory, if available.
Service	getService(String sServiceName)	Returns a service for the given name or null if no service exists in this session with the specified name.
default <V> NamedTopic<V>	getTopic(String sName)	Acquire a NamedTopic using the specified ValueTypeAssertion.
<V> NamedTopic<V>	getTopic(String sName, NamedCollection.Option... options)	Acquire a NamedTopic using the specified ValueTypeAssertion.
boolean	isActive()	Return true if this Session is active and has not been closed.
boolean	isCacheActive(String sCacheName, ClassLoader loader)	Validate whether a cache with the given name is active in the context of the given ClassLoader.
boolean	isMapActive(String sMapName, ClassLoader loader)	Validate whether a map with the given name is active in the context of the given ClassLoader.
boolean	isTopicActive(String sTopicName, ClassLoader loader)	Validate whether a topic with the given name is active in the context of the given ClassLoader.

Methods inherited from interface java.lang.AutoCloseable

close

Method Details

getMap

<K,
V> NamedMap<K,V> getMap(String sName,
 NamedMap.Option... options)

Acquire a NamedMap using the specified NamedMap.Options, for example a TypeAssertion.

Type Parameters:

K - the type of keys for the NamedMap

V - the type of values for the NamedMap

Parameters:

sName - the name of the NamedMap

options - the NamedMap.Options

Returns:

a NamedMap

getCache

<K,
V> NamedCache<K,V> getCache(String sName,
 NamedMap.Option... options)

Acquire a NamedCache using the specified NamedMap.Options, for example a TypeAssertion.

Type Parameters:

K - the type of keys for the NamedCache

V - the type of values for the NamedCache

Parameters:

sName - the name of the NamedCache

options - the NamedMap.Options

Returns:

a NamedCache

getTopic

default <V> NamedTopic<V> getTopic(String sName)

Acquire a NamedTopic using the specified ValueTypeAssertion.

Type Parameters:

V - the type of elements for the NamedTopic

Parameters:

sName - the name of the NamedTopic

Returns:

a NamedCache

Since:

Coherence 14.1.2

getTopic

<V> NamedTopic<V> getTopic(String sName,
 NamedCollection.Option... options)

Acquire a NamedTopic using the specified ValueTypeAssertion.

Type Parameters:

V - the type of elements for the NamedTopic

Parameters:

sName - the name of the NamedTopic

Returns:

a NamedCache

Since:

Coherence 14.1.1

createPublisher

default <V> Publisher<V> createPublisher(String sName)

Create a Publisher that can publish values into a NamedTopic.

Parameters:

sName - the name of the NamedTopic the Publisher will publish to

Returns:

a Publisher that can publish values a NamedTopic

createPublisher

default <V> Publisher<V> createPublisher(String sName,
 Publisher.Option... options)

Create a Publisher that can publish values into a NamedTopic.

Parameters:

sName - the name of the NamedTopic the Publisher will publish to

options - the Publisher.Options controlling the Publisher

Returns:

a Publisher that can publish values a NamedTopic

createSubscriber

default <V> Subscriber<V> createSubscriber(String sName)

Create a Subscriber that can subscribe to a NamedTopic.

Parameters:

sName - the name of the NamedTopic the Subscriber will subscribe to

Returns:

a Subscriber that can publish values a NamedTopic

createSubscriber

default <V> Subscriber<V> createSubscriber(String sName,
 Subscriber.Option... options)

Create a Subscriber that can subscribe to a NamedTopic.

Parameters:

sName - the name of the NamedTopic the Subscriber will subscribe to

options - the Subscriber.Options controlling the Subscriber

Returns:

a Subscriber that can publish values a NamedTopic

getQueue

default <E> NamedQueue<E> getQueue(String sName)

Acquire a NamedQueue.

Type Parameters:

E - the type of elements in the NamedQueue

Parameters:

sName - the name of the NamedQueue

Returns:

a NamedQueue

getQueue

<E> NamedQueue<E> getQueue(String sName,
 NamedCollection.Option... options)

Acquire a NamedQueue.

Type Parameters:

E - the type of elements in the NamedQueue

Parameters:

sName - the name of the NamedQueue

Returns:

a NamedQueue

getDeque

default <E> NamedDeque<E> getDeque(String sName)

Acquire a NamedDeque.

Type Parameters:

E - the type of elements in the NamedDeque

Parameters:

sName - the name of the NamedDeque

Returns:

a NamedQueue

getDeque

<E> NamedDeque<E> getDeque(String sName,
 NamedCollection.Option... options)

Acquire a NamedDeque.

Type Parameters:

E - the type of elements in the NamedDeque

Parameters:

sName - the name of the NamedDeque

Returns:

a NamedQueue

close

void close(NamedCollection col)

Close and release the a NamedCollection.

Parameters:

col - the NamedCollection to close

destroy

void destroy(NamedCollection col)

Destroy a NamedCollection.

Warning: This method is used to completely destroy the specified collection across the cluster. All references in the entire cluster to this collection will be invalidated, the collection data will be cleared, and all internal resources will be released.

Parameters:

col - the NamedCollection to destroy

getResourceRegistry

ResourceRegistry getResourceRegistry()

Return the ResourceRegistry for this session.

Returns:

the ResourceRegistry for this session

getInterceptorRegistry

InterceptorRegistry getInterceptorRegistry()

Return the InterceptorRegistry for this session. EventInterceptors registered with this session will be scoped to services and caches created by this session.

Returns:

the InterceptorRegistry for this session

isMapActive

boolean isMapActive(String sMapName,
 ClassLoader loader)

Validate whether a map with the given name is active in the context of the given ClassLoader. The ClassLoader should be the same as provided to a previous call to getMap(String, NamedMap.Option...).

Parameters:

sMapName - the map name

loader - the ClassLoader used to originally obtain the map

Returns:

true if map is active in context of the provided ClassLoader

isCacheActive

boolean isCacheActive(String sCacheName,
 ClassLoader loader)

Validate whether a cache with the given name is active in the context of the given ClassLoader. The ClassLoader should be the same as provided to a previous call to getCache(String, NamedCache.Option...).

Parameters:

sCacheName - the cache name

loader - the ClassLoader used to originally obtain the cache

Returns:

true if cache is active in context of the provided ClassLoader

isTopicActive

boolean isTopicActive(String sTopicName,
 ClassLoader loader)

Validate whether a topic with the given name is active in the context of the given ClassLoader. The ClassLoader should be the same as provided to a previous call to getTopic(String, NamedTopic.Option...).

Parameters:

sTopicName - the cache name

loader - the ClassLoader used to originally obtain the topic

Returns:

true if topic is active in context of the provided ClassLoader

getName

String getName()

Return the name of this session, if available.

Returns:

the name of this session, if available; null otherwise

getScopeName

String getScopeName()

Return the scope name of this cache factory, if available.

Returns:

the scope name of this cache factory, if available; null otherwise

isActive

boolean isActive()

Return true if this Session is active and has not been closed.

Returns:

true if this Session is active

activate

void activate()

Activate this Session.

Calling this method on an already active Session is a no-op.

getService

Service getService(String sServiceName)

Returns a service for the given name or null if no service exists in this session with the specified name.

Parameters:

sServiceName - the service name

Returns:

the requested Service or null if no service exists in this session with the specified name

create

@Deprecated
static Session create(Session.Option... options)
               throws IllegalArgumentException,
IllegalStateException

Deprecated.

since 20.12 use create(SessionConfiguration)

Create a Session based on the current calling context and provided Session.Options, using the default (auto-detected) SessionProvider,

Parameters:

options - the Session.Options for the Session

Returns:

a Session

Throws:

IllegalArgumentException - when a Session or SessionProvider can't be acquired using the specified Session.Options

IllegalStateException - when a SessionProvider can't be auto-detected

See Also:

• SessionProvider.createSession(Option...)

create

static Session create()

Obtain the default Session.

This method calls ensure(SessionConfiguration, Coherence.Mode) with a configuration of SessionConfiguration.defaultSession() and a mode of Coherence.Mode.ClusterMember. This will return an activated cluster member default Session.

Returns:

an Optional containing the Session or an empty Option if the default session could not be created.

Throws:

IllegalStateException - if the default session cannot be created

ensure

static Session ensure(SessionConfiguration configuration)

Obtain a Session based on the specified configuration or throw an IllegalStateException if a session could not be obtained.

This method calls ensure(SessionConfiguration, Coherence.Mode) with a mode of Coherence.Mode.ClusterMember.

Parameters:

configuration - the configuration for the Session

Returns:

an Optional containing the Session or an empty Option if no session could be created from the specified configuration

Throws:

NullPointerException - if the configuration is null

IllegalStateException - if the default session cannot be created

ensure

static Session ensure(SessionConfiguration configuration,
 Coherence.Mode mode)

Obtain a Session based on the specified configuration or throw an IllegalStateException if a session could not be obtained.

Parameters:

configuration - the configuration for the Session

mode - the mode that Coherence is running in

Returns:

an Optional containing the Session or an empty Option if no session could be created from the specified configuration

Throws:

NullPointerException - if the configuration or mode are null

IllegalStateException - if the default session cannot be created

create

static Optional<Session> create(SessionConfiguration configuration)

Possibly obtain a Session based on the specified configuration.

This method calls create(SessionConfiguration, Coherence.Mode) with a mode of Coherence.Mode.ClusterMember.

Parameters:

configuration - the configuration for the Session

Returns:

an Optional containing the Session or an empty Option if no session could be created from the specified configuration

Throws:

NullPointerException - if the configuration is null

create

static Optional<Session> create(SessionConfiguration configuration,
 Coherence.Mode mode)

Possibly obtain a Session based on the specified configuration.

Parameters:

configuration - the configuration for the Session

mode - the mode that Coherence is running in

Returns:

an Optional containing the Session or an empty Option if no session could be created from the specified configuration

Throws:

NullPointerException - if the configuration or mode are null

create

static Optional<Session> create(SessionConfiguration configuration,
 Coherence.Mode mode,
 Iterable<? extends EventInterceptor<?>> interceptors)

Possibly obtain a Session based on the specified configuration.

Parameters:

configuration - the configuration for the Session

mode - the mode that Coherence is running in

interceptors - optional interceptors to add to the session in addition to any in the configuration

Returns:

an Optional containing the Session or an empty Option if no session could be created from the specified configuration

Throws:

NullPointerException - if the configuration or mode are null