com.ibm.websphere.objectgrid
Interface ObjectGrid

public interface ObjectGrid

This object is used for creating sessions to the ObjectGrid. It is the central core of the ObjectGrid framework. Besides creating Sessions, it is also responsible for defining BackingMaps, setting a TransactionCallback, adding event listeners, and managing the security settings.

Since:

WAS XD 6.0, XC10

Field Summary

static int	CLIENT Indicates the ObjectGrid is a client-side distributed ObjectGrid.
static int	DEFAULT_TX_TIMEOUT_VALUE The default transaction time out value of 10 minutes if no transaction time out value is set.
static int	LOCAL Indicates the ObjectGrid is a local ObjectGrid.
static int	SERVER Indicates the ObjectGrid is a server-side distributed ObjectGrid.

Method Summary

void	addEventListener(EventListener listener) Adds an EventListener.
void	addEventListener(ObjectGridEventListener listener) Deprecated. This method is deprecated in version 7.1.1, use the addEventListener(EventListener) method.
BackingMap	createMap(String name) Creates a BackingMap, but does not associate it with this ObjectGrid.
BackingMap	defineMap(String name) Defines a BackingMap that will be used by the application.
void	destroy() Destroys this instance.
CollisionArbiter	getCollisionArbiter() Retrieves the CollisionArbiter that this grid is using to resolve revision collisions.
List	getEventListeners() Returns the current list of EventListeners.
List	getListOfMapNames() Gets the list of map names currently defined for this ObjectGrid instance.
BackingMap	getMap(String name) Returns a BackingMap previously configured by calling the defineMap(String) or setMaps(List) method.
String	getName() Gets the name of this ObjectGrid.
int	getObjectGridType() Returns the type of ObjectGrid.
Session	getSession() Gets a Session object that can be used by a single thread at a time.
Session	getSession(CredentialGenerator credGen) Get a session using a CredentialGenerator.
Session	getSession(Subject subject) Allows the use of a specific Subject rather than use the SubjectSource configured on the ObjectGrid to get a Session.
ObjectGridLifecycleListener.State	getState() Retrieve the current life cycle state of this ObjectGrid.
TransactionCallback	getTransactionCallback() Retrieves the TransactionCallback object.
int	getTxIsolation() Retrieves the default transaction isolation level.
int	getTxTimeout() Gets transaction timeout setting for this ObjectGrid instance.
void	initialize() Begins the bootstrapping of the ObjectGrid and Session instances.
boolean	isSecurityEnabled() Checks whether security is enabled on this ObjectGrid or not.
void	registerEntities(Class[] entities) Register one or more entities based on the class metadata.
void	registerEntities(URL entityXML) Registers one ore more entities from an entity XML file.
void	removeEventListener(EventListener listener) Removes an EventListener.
void	removeEventListener(ObjectGridEventListener listener) Deprecated. This method is deprecated in version 7.1.1, use the removeEventListener(EventListener) method.
int	reserveSlot(String containerName) Allows plugins on this ObjectGrid to reserve slots for use to store context data.
void	setAccessByCreatorOnlyMode(int accessByCreatorOnlyMode) Set the "access by creator only" mode.
void	setAuthorizationMechanism(int authMechanism) Sets the authorization mechanism.
void	setCollisionArbiter(CollisionArbiter arbiter) Sets the CollisionArbiter that is responsible for arbitration of revision conflicts.
void	setEventListeners(List listeners) Deprecated. This method is deprecated in version 7.1.1. Use the addEventListener(EventListener) or removeEventListener(EventListener) methods. Plug-ins that implement the ObjectGridLifecycleListener interface are automatically registered with the grid. Using this method will remove those automatically added listeners.
void	setMaps(List mapList) Clears any BackingMaps that have been previously defined on this ObjectGrid and replaces them with the List of BackingMaps provided.
void	setName(String gridName) Sets the name of this ObjectGrid.
void	setObjectGridAuthorization(ObjectGridAuthorization ogAuthorization) Sets the ObjectGridAuthorization for this ObjectGrid instance.
void	setPermissionCheckPeriod(int period) Sets the permission check period.
void	setQueryConfig(QueryConfig queryConfig) Set the QueryConfig object for this ObjectGrid.
void	setSecurityEnabled() Enables the ObjectGrid security.
void	setSubjectSource(SubjectSource source) Sets the SubjectSource plugin.
void	setSubjectValidation(SubjectValidation subjectValidation) Sets the SubjectValidation for this ObjectGrid instance.
void	setTransactionCallback(TransactionCallback callback) Sets the TransactionCallback object.
void	setTxIsolation(int level) Sets the default transaction isolation level for all sessions created by the ObjectGrid.
void	setTxTimeout(int timeout) Sets the transaction timeout value to a specified number of seconds.

Field Detail

DEFAULT_TX_TIMEOUT_VALUE

static final int DEFAULT_TX_TIMEOUT_VALUE

The default transaction time out value of 10 minutes if no transaction time out value is set.

Since:

WXS 7.1.0.0 FIX1

See Also:

Constant Field Values

LOCAL

static final int LOCAL

Indicates the ObjectGrid is a local ObjectGrid.

See Also:

Constant Field Values

SERVER

static final int SERVER

Indicates the ObjectGrid is a server-side distributed ObjectGrid.

See Also:

Constant Field Values

CLIENT

static final int CLIENT

Indicates the ObjectGrid is a client-side distributed ObjectGrid.

See Also:

Constant Field Values

Method Detail

getSession

Session getSession()
                   throws ObjectGridException,
                          TransactionCallbackException

Gets a Session object that can be used by a single thread at a time.

It is not allowed to share this Session object between threads without placing a critical section around it. While the core framework allows the object to move between threads, the TransactionCallback and Loader may prevent this usage, especially in J2EE environments.

When the ObjectGrid is a local ObjectGrid, and its security is enabled, this method will use the SubjectSource to get a Subject object and then associate the Subject object with this session .

When the ObjectGrid is a distributed ObjectGrid (client server mode), and its security is enabled, this method will utilize the client server security infrastructure to get a secure session.

If the initialize() method has not been invoked prior to the first getSession invocation, an implicit initialization will occur. This ensures that all of the configuration is complete before any runtime usage is required.

Returns:

An instance of Session

Throws:

ObjectGridException - if an error occurs during processing

TransactionCallbackException - if the TransactionCallback throws an exception

IllegalStateException - if this method is called after the destroy() method is called.

See Also:

destroy(), initialize(), Session, SubjectSource

getSession

Session getSession(Subject subject)
                   throws ObjectGridException,
                          TransactionCallbackException,
                          InvalidSubjectException

Allows the use of a specific Subject rather than use the SubjectSource configured on the ObjectGrid to get a Session.

This method should only be used when ObjectGrid security is enabled. If the ObjectGrid security is disabled, the provided Subject object will not be used.

If the initialize() method has not been invoked prior to the first getSession invocation, an implicit initialization will occur. This ensures that all of the configuration is complete before any runtime usage is required.

Parameters:

subject - Subject to associate with the returned Session

Returns:

An instance of Session

Throws:

ObjectGridException - if an error occurs during processing

TransactionCallbackException - if the TransactionCallback throws an exception

InvalidSubjectException - the subject passed in is invalid based on the SubjectValidation mechanism.

IllegalStateException - if this method is called after the destroy() method is called.

See Also:

destroy(), initialize(), Session, SubjectValidation

setTransactionCallback

void setTransactionCallback(TransactionCallback callback)

Sets the TransactionCallback object.

A single cache is a single domain. All Loaders defined for BackingMaps in an ObjectGrid will normally cooperate, thus a corresponding TransactionCallback object needs to be set on the ObjectGrid.

A TransactionCallback that implements the ObjectGridLifecycleListener interface is automatically added as if the addEventListener(EventListener) method was called. Any previous callback which implements ObjectGridLifecycleListener interface is removed as if the removeEventListener(EventListener) method was called.

A TransactionCallback may implement the ObjectGridPlugin interface in order to receive enhanced ObjectGrid plug-in lifecycle method calls. The plug-in is also required to correctly implement each of the bean methods related to introspection of its state (for example isInitialized(), isDestroyed(), etc).

Parameters:

callback - An instance of a TransactionCallback

Throws:

IllegalArgumentException - if callback is null

IllegalStateException - if this method is called after the initialize() method is called.

See Also:

initialize(), TransactionCallback

getTransactionCallback

TransactionCallback getTransactionCallback()

Retrieves the TransactionCallback object.

The TransactionCallback can be used in conjunction with the TxID to house transaction-specific context data, such as the connection to the database.

Returns:

the argument that was passed to the setTransactionCallback(TransactionCallback) method of this interface or a default TransactionCallback object if setTransactionCallback was not previously called for this ObjectGrid.

See Also:

setTransactionCallback(TransactionCallback), TransactionCallback

setCollisionArbiter

void setCollisionArbiter(CollisionArbiter arbiter)

Sets the CollisionArbiter that is responsible for arbitration of revision conflicts.

A CollistionArbiter that implements the ObjectGridLifecycleListener interface is automatically added as if the addEventListener(EventListener) method was called. Any previous arbiter which implements ObjectGridLifecycleListener interface is removed as if the removeEventListener(EventListener) method was called.

A CollisionArbiter may implement the ObjectGridPlugin interface in order to receive enhanced ObjectGrid plug-in lifecycle method calls. The plug-in is also required to correctly implement each of the bean methods related to introspection of its state (for example isInitialized(), isDestroyed(), etc).

Parameters:

arbiter - The arbitration logic that will be used to resolve collisions.

Since:

7.1

getCollisionArbiter

CollisionArbiter getCollisionArbiter()

Retrieves the CollisionArbiter that this grid is using to resolve revision collisions.

Returns:

The arbitration logic that is responsible for resolving revision collisions.

Since:

7.1

defineMap

BackingMap defineMap(String name)

Defines a BackingMap that will be used by the application.

Note, to avoid an IllegalStateException, this method must be called prior to the initialize() method. Also, keep in mind that the getSession methods implicitly call the initialize() method if it has yet to be called by the application.

Parameters:

name - the name of the map being defined.

Returns:

a BackingMap reference

Throws:

IllegalArgumentException - if name is null

IllegalStateException - if this method is called after the initialize() method is called.

See Also:

initialize(), BackingMap

createMap

BackingMap createMap(String name)

Creates a BackingMap, but does not associate it with this ObjectGrid.

This method is to be used in tandem with the setMaps(List) method, which will associate BackingMaps with this ObjectGrid. These methods are for use when configuring an ObjectGrid with the Spring Framework.

Note, to avoid an IllegalStateException, this method must be called prior to the initialize() method. Also, keep in mind that the getSession methods implicitly call the initialize() method if it has yet to be called by the application.

Parameters:

name - the name of the map being defined.

Returns:

a BackingMap reference

Throws:

IllegalArgumentException - if name is null

IllegalStateException - if this method is called after the initialize() method is called.

Since:

WAS XD 6.0.1

See Also:

initialize(), setMaps(List)

setMaps

void setMaps(List mapList)

Clears any BackingMaps that have been previously defined on this ObjectGrid and replaces them with the List of BackingMaps provided.

Note, to avoid an IllegalStateException, this method must be called prior to the initialize() method. Also, keep in mind that the getSession methods implicitly call the initialize() method if it has yet to be called by the application.

Parameters:

mapList - a list of BackingMaps to set on this ObjectGrid.

Throws:

IllegalStateException - if this method is called after the initialize() method is called.

Since:

WAS XD 6.0.1

See Also:

createMap(String), initialize()

getListOfMapNames

List getListOfMapNames()

Gets the list of map names currently defined for this ObjectGrid instance.

Note, once the initialize() method is called, the List returned will not change. However, it could change if called prior to initialization. Also, keep in mind that the getSession methods implicitly call the initialize() method if it has yet to be called by the application.

Returns:

a List of String objects, one String per map that was previously configured by the defineMap(String) or setMaps(List) method. An empty List is returned if no maps are currently defined.

See Also:

defineMap(String), initialize(), setMaps(List)

getMap

BackingMap getMap(String name)

Returns a BackingMap previously configured by calling the defineMap(String) or setMaps(List) method.

Parameters:

name - the same name that was used as an argument to the defineMap(String) or createMap(String) method. A null reference is returned if a map is not associated with this ObjectGrid for the specified map name.

Returns:

the BackingMap instance

See Also:

createMap(String), defineMap(String), setMaps(List)

initialize

void initialize()
                throws ObjectGridException

Begins the bootstrapping of the ObjectGrid and Session instances.

After this method has been invoked, the configuration of the ObjectGrid is considered complete and is ready for runtime usage. Any additional configuration method invocations, such as defineMap(String), will result in an exception. This method is considered optional since the first call to one of the getSession methods will perform an implicit initialization.

Throws:

ObjectGridException - if an error occurs during processing

addEventListener

void addEventListener(EventListener listener)

Adds an EventListener.

Significant events will be communicated to interested listeners through the ObjectGridEventListener and ObjectGridLifecycleListener callback interface. Multiple event listeners are allowed to be registered, with no implied ordering of event notifications.

Note, this method is allowed to be invoked before and after the initialize() method.

Object grid plug-ins (TransactionCallback, CollisionArbiter) that implement the ObjectGridLifecycleListener are automatically added as lifecycle listeners when added to the ObjectGrid.

Parameters:

listener - An instance of ObjectGridEventListener or ObjectGridLifecycleListener

Throws:

IllegalArgumentException - if listener is null or not an instance of ObjectGridEventListener, ObjectGridLifecycleListener.

IllegalStateException - if this method is called during initialization by one of the configured plugins and the ObjectGrid runtime is not in a usable state to initialize the ObjectGridEventListener.

See Also:

ObjectGridEventListener, ObjectGridLifecycleListener, EventListener

addEventListener

void addEventListener(ObjectGridEventListener listener)

Deprecated. This method is deprecated in version 7.1.1, use the addEventListener(EventListener) method.

Provided for compatibility with old releases, use the addEventListener(EventListener) method.

Parameters:

listener -

removeEventListener

void removeEventListener(EventListener listener)

Removes an EventListener.

This method removes an ObjectGridEventListener or ObjectGridLifecycleListener that was previously added to this object using the addEventListener(ObjectGridEventListener) or setEventListeners(List) method. If the desired ObjectGridEventListener is not found, no error will be returned.

Note, this method is allowed to be invoked before and after the initialize() method. Object grid plug-ins (TransactionCallback, CollisionArbiter) that implement the ObjectGridLifecycleListener are automatically removed as lifecycle listeners when removed from the ObjectGrid.

Parameters:

listener - An instance of ObjectGridEventListener or ObjectGridLifecycleListener

Throws:

IllegalArgumentException - if listener is null or not an instance of ObjectGridEventListener, ObjectGridLifecycleListener

See Also:

addEventListener(EventListener), ObjectGridEventListener, EventListener

removeEventListener

void removeEventListener(ObjectGridEventListener listener)

Deprecated. This method is deprecated in version 7.1.1, use the removeEventListener(EventListener) method.

Provided for compatibility with old releases, use the removeEventListener(EventListener) method.

Parameters:

listener -

setEventListeners

@Deprecated
void setEventListeners(List listeners)

Deprecated. This method is deprecated in version 7.1.1. Use the addEventListener(EventListener) or removeEventListener(EventListener) methods. Plug-ins that implement the ObjectGridLifecycleListener interface are automatically registered with the grid. Using this method will remove those automatically added listeners.

This overwrites the current list of EventListeners and replaces it with the supplied List of EventListeners

Note, this method is allowed to be invoked before and after the initialize() method.

Parameters:

listeners - List of ObjectGridEventListeners and ObjectGridLifecycleListener instances

Throws:

ClassCastException - if one of the elements in the provided list is not an instance of ObjectGridEventListener

IllegalArgumentException - if listeners is null, contains a null reference, or contains an instance of a type other than ObjectGridEventListener and ObjectGridLifecycleListener

IllegalStateException - if this method is called during initialization by one of the configured plugins and the ObjectGrid runtime is not in a usable state to initialize the ObjectGridEventListener objects.

See Also:

EventListener, addEventListener(EventListener), removeEventListener(EventListener)

getEventListeners

List getEventListeners()

Returns the current list of EventListeners.

Returns:

The current list of EventListeners.

See Also:

addEventListener(EventListener), EventListener, ObjectGridEventListener, ObjectGridLifecycleListener

getName

String getName()

Gets the name of this ObjectGrid.

This method is useful for authorization as all Maps are prefixed with the ObjectGrid name.

Returns:

The name of the ObjectGrid.

See Also:

setName(String)

setName

void setName(String gridName)

Sets the name of this ObjectGrid. Note, to avoid an IllegalStateException, this method must be called prior to the initialize() method. Also, keep in mind that the getSession methods implicitly call the initialize() method if it has yet to be called by the application.

Parameters:

gridName - The ObjectGrid name to use.

Throws:

IllegalArgumentException - if gridName is null

IllegalStateException - if this method is called after the initialize() method is called.

reserveSlot

int reserveSlot(String containerName)

Allows plugins on this ObjectGrid to reserve slots for use to store context data.

Currently the TxID object is the only object that uses slots for storing context data. TxID slots are used for storing transactional context data.

Once a slot is reserved, the slot assignment is permanent and cannot be given back. Note, this method is allowed to be invoked before and after the initialize() method.

Parameters:

containerName - The name of the Object with the slots. Currently TxID.SLOT_NAME is the only supported value for this argument.

Returns:

The slot index to use.

Throws:

IllegalArgumentException - if containerName is not TxID.SLOT_NAME.

See Also:

TxID.SLOT_NAME, TxID.getSlot(int), TxID.putSlot(int, Object)

setSubjectValidation

void setSubjectValidation(SubjectValidation subjectValidation)

Sets the SubjectValidation for this ObjectGrid instance.

Passing null to this method removes a previously set SubjectValidation object from an earlier invocation of this method and indicates that this ObjectGrid is not associated with a SubjectValidation object.

This method should only be used when ObjectGrid security is enabled. If the ObjectGrid security is disabled, the provided SubjectValidation object will not be used.

A SubjectValidation plugin can be used to validate the Subject object passed in is a valid Subject. Please refer to SubjectValidation for more details.

Note, to avoid an IllegalStateException, this method must be called prior to the initialize() method. Also, keep in mind that the getSession methods implicitly call the initialize() method if it has yet to be called by the application.

Parameters:

subjectValidation - the SubjectValidation plugin

Throws:

IllegalStateException - if this method is called after the initialize() method is called.

See Also:

getSession(Subject), initialize(), SubjectValidation

setAuthorizationMechanism

void setAuthorizationMechanism(int authMechanism)

Sets the authorization mechanism.

If this method is not invoked, the default authorization mechanism is SecurityConstants.AUTHORIZATION_MECHANISM_JAAS.

This method should only be used when ObjectGrid security is enabled. If the ObjectGrid security is disabled, the provide authorization mechanism will not be used.

Note, to avoid an IllegalStateException, this method must be called prior to the initialize() method. Also, keep in mind that the getSession methods implicitly call the initialize() method if it has yet to be called by the application.

Parameters:

authMechanism - the authorization mechanism, must be one of the final static variable on the SecurityConstants class.

Throws:

IllegalStateException - if this method is called after the initialize() method is called.

See Also:

initialize(), SecurityConstants.AUTHORIZATION_MECHANISM_CUSTOM, SecurityConstants.AUTHORIZATION_MECHANISM_JAAS

setSecurityEnabled

void setSecurityEnabled()

Enables the ObjectGrid security.

Security on the ObjectGrid level refers to ObjectGrid authorizations.

Note, to avoid an IllegalStateException, this method must be called prior to the initialize() method. Also, keep in mind that the getSession methods implicitly call the initialize() method if it has yet to be called by the application.

Throws:

IllegalStateException - if this method is called after the initialize() method is called.

See Also:

initialize()

isSecurityEnabled

boolean isSecurityEnabled()

Checks whether security is enabled on this ObjectGrid or not.

Security on the ObjectGrid level refers to ObjectGrid authorizations. Security is disabled by default.

Returns:

true if security is enabled on this ObjectGrid; false otherwise.

See Also:

setSecurityEnabled()

setPermissionCheckPeriod

void setPermissionCheckPeriod(int period)

Sets the permission check period.

This method takes a single parameter indicating how often the customer wants to check the permission used to allow a client access. If the parameter is 0 then every single authorized operation call will ask the authorization mechanism, either JAAS authorization or custom authorization to check if the current Subject has permission. This approach may be prohibitively expensive from a performance point of view depending on the authorization implementation, but if it is required then you can do it. Alternatively, if the parameter is > 0 then it indicates the number of seconds to cache a set of permissions before returning to the authorization mechanism to refresh them. This mechanism provides much better performance, but you run the risk that if the back-end permissions are changed during this time, the ObjectGrid will possibly allow or prevent access even though the back-end security provider has been modified.

Note, to avoid an IllegalStateException, this method must be called prior to the initialize() method. Also, keep in mind that the getSession methods implicitly call the initialize() method if it has yet to be called by the application.

Parameters:

period - the permission check period in seconds.

Throws:

IllegalStateException - if this method is called after the initialize() method is called.

See Also:

initialize()

setSubjectSource

void setSubjectSource(SubjectSource source)

Sets the SubjectSource plugin.

Passing null to this method removes a previously set SubjectSource object from an earlier invocation of this method and indicates that this ObjectGrid is not associated with a SubjectSource object.

A SubjectSource plugin can be used to get a Subject object from the environment to represent the ObjectGrid client.

This method should only be used when ObjectGrid security is enabled. If the ObjectGrid security is disabled, the provided SubjectSource object will not be used.

Note, to avoid an IllegalStateException, this method must be called prior to the initialize() method. Also, keep in mind that the getSession methods implicitly call the initialize() method if it has yet to be called by the application.

Parameters:

source - the SubjectSource plugin

Throws:

IllegalStateException - if this method is called after the initialize() method is called.

See Also:

initialize(), SubjectSource

setTxTimeout

void setTxTimeout(int timeout)

Sets the transaction timeout value to a specified number of seconds.

Any transaction that is started by use of a Session returned by one of the getSession methods on this interface must complete within the number of seconds specified by the transaction timeout parameter of this method. The timeout value is the maximum number of seconds the transaction is allowed to execute. If a transaction executes longer than this amount, a TransactionTimeoutException is thrown and the transaction is rolled back even if commit is requested.

Note, to avoid an IllegalStateException, this method must be called prior to the initialize() method. Also, keep in mind that the getSession methods implicitly call the initialize() method if it has yet to be called by the application.

The transaction timeout is used by any transaction started by a Session that is returned by the getSession methods of this interface. Since this method must be called prior to getSession method to avoid IllegalStateException, this method only affects transactions that are started after this method is called. If this method is never called, the transaction is allowed unlimited amount of time to complete.

Parameters:

timeout - is the transaction timeout value in seconds. Use a value of 0 to indicate a transaction is allowed unlimited amount of time so that no TransactionTimeoutException ever occurs.

Throws:

IllegalStateException - if this method is called after the initialize() method is called.

Since:

WAS XD 6.0.1

See Also:

initialize(), Session.TRANSACTION_NO_TIMEOUT, Session.setTransactionTimeout(int), TransactionTimeoutException

getTxTimeout

int getTxTimeout()

Gets transaction timeout setting for this ObjectGrid instance.

Returns:

timeout value that was passed to the setTxTimeout(int) method or 0 if setTxTimeout was never called.

Since:

WAS XD 6.0.1

See Also:

setTxTimeout(int)

setTxIsolation

void setTxIsolation(int level)

Sets the default transaction isolation level for all sessions created by the ObjectGrid. The constants defined in the Session interface are the possible transaction isolation levels. The default is Session.TRANSACTION_REPEATABLE_READ.

Parameters:

level - one of the following Session constants: Session.TRANSACTION_READ_UNCOMMITTED, Session.TRANSACTION_READ_COMMITTED or Session.TRANSACTION_REPEATABLE_READ

Throws:

IllegalStateException - if this method is called after the initialize() method is called.

IllegalArgumentException - if this method is includes and invalid transaction isolation level.

Since:

7.1.1

getTxIsolation

int getTxIsolation()

Retrieves the default transaction isolation level.

Returns:

the current transaction isolation level.

Since:

7.1.1

See Also:

setTxIsolation(int)

destroy

void destroy()

Destroys this instance.

This method should be invoked when the ObjectGrid is no longer being used. When this method is called, the ObjectGrid can free up any resources it is using. No new Sessions can be created or used after the destroy() has been invoked. Any in-flight Sessions will be allowed to continue, if the resources are still available to complete processing.

getSession

Session getSession(CredentialGenerator credGen)
                   throws ObjectGridException,
                          TransactionCallbackException

Get a session using a CredentialGenerator.

This method can only be called by the ObjectGrid client in an ObjectGrid client server environment. If ObjectGrid is used in a local model, that is, within the same JVM with no client or server existing, getSession(Subject) or the SubjectSource plugin should be used to secure the ObjectGrid.

If the initialize() method has not been invoked prior to the first getSession invocation, an implicit initialization will occur. This ensures that all of the configuration is complete before any runtime usage is required.

Parameters:

credGen - A CredentialGenerator for generating a credential for the session returned.

Returns:

An instance of Session

Throws:

ObjectGridException - if an error occurs during processing

TransactionCallbackException - if the TransactionCallback throws an exception

IllegalStateException - if this method is called after the destroy() method is called.

Since:

WAS XD 6.0.1

See Also:

destroy(), initialize(), CredentialGenerator, Session

setQueryConfig

void setQueryConfig(QueryConfig queryConfig)

Set the QueryConfig object for this ObjectGrid. A QueryConfig object provides query configurations for executing object queries over the maps in this ObjectGrid.

Parameters:

queryConfig - The QueryConfig to associate with this ObjectGrid instance.

Throws:

IllegalArgumentException - if queryConfig is null.

IllegalStateException - if this method is called after the initialize() method is called.

Since:

WAS XD 6.1

See Also:

QueryConfig

registerEntities

void registerEntities(URL entityXML)

Registers one ore more entities from an entity XML file.

Entity registration is required prior to ObjectGrid initialization to bind an Entity with a BackingMap and any defined indices.

This method may be called multiple times.

Parameters:

entityXML - the URL of the entity XML that defines the entities.

Throws:

IllegalStateException - if this method is called after the initialize() method is called.

Since:

WAS XD 6.1

registerEntities

void registerEntities(Class[] entities)

Register one or more entities based on the class metadata.

Entity registration is required prior to ObjectGrid initialization to bind an Entity with a BackingMap and any defined indices.

This method may be called multiple times.

Parameters:

entities - one or more annotated entity classes to register as entities.

Throws:

IllegalStateException - if this method is called after the initialize() method is called.

Since:

WAS XD 6.1

getObjectGridType

int getObjectGridType()

Returns the type of ObjectGrid.

The return value is equivalent to one of the constants declared on this interface, LOCAL, SERVER, or CLIENT.

Returns:

the ObjectGrid type

Since:

WAS XD 6.1

setObjectGridAuthorization

void setObjectGridAuthorization(ObjectGridAuthorization ogAuthorization)

Sets the ObjectGridAuthorization for this ObjectGrid instance.

Passing null to this method removes a previously set ObjectGridAuthorization object from an earlier invocation of this method and indicates that this ObjectGrid is not associated with a ObjectGridAuthorization object.

This method should only be used when ObjectGrid security is enabled. If the ObjectGrid security is disabled, the provided ObjectGridAuthorization object will not be used.

A ObjectGridAuthorization plugin can be used to authorize access to the ObjectGrid and maps. Please refer to ObjectGridAuthorization for more details.

Note, to avoid an IllegalStateException, this method must be called prior to the initialize() method. Also, keep in mind that the getSession methods implicitly call the initialize() method if it has yet to be called by the application.

Parameters:

ogAuthorization - the ObjectGridAuthorization plugin

Throws:

IllegalStateException - if this method is called after the initialize() method is called.

Since:

WAS XD 6.1

See Also:

initialize(), ObjectGridAuthorization

setAccessByCreatorOnlyMode

void setAccessByCreatorOnlyMode(int accessByCreatorOnlyMode)

Set the "access by creator only" mode.

Enabling "access by creator only" mode ensures that only the user (represented by the Principals associated with it), who inserts the record into the map, can access (read, update, invalidate, and remove) the record.

The "access by creator only" mode can be disabled, or can complement the ObjectGrid authorization model, or it can supersede the ObjectGrid authorization model. The default value is disabled: SecurityConstants.ACCESS_BY_CREATOR_ONLY_DISABLED.

Parameters:

accessByCreatorOnlyMode - the access by creator mode.

Since:

WAS XD 6.1 FIX3

See Also:

SecurityConstants.ACCESS_BY_CREATOR_ONLY_DISABLED, SecurityConstants.ACCESS_BY_CREATOR_ONLY_COMPLEMENT, SecurityConstants.ACCESS_BY_CREATOR_ONLY_SUPERSEDE

getState

ObjectGridLifecycleListener.State getState()

Retrieve the current life cycle state of this ObjectGrid.

Returns:

the current state.

Since:

7.1.1