ObjectGrid interface

WebSphere eXtreme Scale Administration Guide > Configure WebSphere eXtreme Scale > Configuring a local eXtreme Scale configuration

ObjectGrid interface

The following methods allow you to interact with an ObjectGrid instance.

Introduction

Create and initialize

See the ObjectGridManager interface topic for the required steps for creating an ObjectGrid instance. Two distinct methods exist to create an ObjectGrid instance: programmatically or with XML configuration files. See ObjectGridManager interface for more information.

Get or set and factory methods

Any set methods must be called before you initialize the ObjectGrid instance. If you call a set method after the initialize method is called, a java.lang.IllegalStateException exception results. Each of the getSession methods of the ObjectGrid interface also implicitly call the initialize method. Therefore, you must call the set methods before calling any of the getSession methods. The only exception to this rule is with the setting, adding, and removing of ObjectGridEventListener objects. These objects are allowed to be processed after the initialization processing has completed.
The ObjectGrid interface contains the following major methods.
Table 1. ObjectGrid interface methods
Method Description

BackMap defineMap(String name);

defineMap: is a factory method to define a uniquely named BackingMap. For more information about backing maps, see BackingMap interface.

BackMap getMap(String name);

getMap: Returns a BackingMap previously defined by calling defineMap. By using this method, you can configure the BackingMap, if it is not already configured through XML configuration.

BackMap createMap(String name);

createMap: Creates a BackingMap, but does not cache it for use by this ObjectGrid. Use this method with the setMaps(List) method of the ObjectGrid interface, which caches BackingMaps for use with this ObjectGrid. Use these methods when you are configuring an ObjectGrid with the Spring Framework.

void setMaps(List mapList);

setMaps: Clears any BackingMaps that have been previously defined on this ObjectGrid and replaces them with the list of BackingMaps that is provided.

public Session getSession() throws ObjectGridException, TransactionCallbackException;

getSession: Returns a Session, which provides begin, commit, rollback functionality for a Unit of Work. For more information about Session objects, see Session interface.

Session getSession(CredentialGenerator cg);

getSession(CredentialGenerator cg): Get a session with a CredentialGenerator object. This method can only be called by the ObjectGrid client in a client server environment.

Session getSession(Subject subject);

getSession(Subject subject): Allows the use of a specific Subject object rather than the one configured on the ObjectGrid to get a Session.

void initialize() throws ObjectGridException;

initialize: ObjectGrid is initialized and available for general use. This method is called implicitly when the getSession method is called, if the ObjectGrid is not in an initialized state.

void destroy();

destroy: The framework is disassembled and cannot be used after this method is called.

void setTxTimeout(int timeout);

setTxTimeout: Use this method to set the amount of time, in seconds, that a transaction that is started by a session that this ObjectGrid instance created is allowed for completion. If a transaction does not complete within the specified amount of time, the Session that started the transaction is marked as being "timed out". Marking a Session as timed out causes the next ObjectMap method that is invoked by the timed out Session to result in a com.ibm.websphere.objectgrid.TransactionTimeoutException exception. The Session is marked as rollback only, which causes the transaction to be rolled back even if the application calls the commit method instead of the rollback method after the TransactionTimeoutException exception is caught by the application. A timeout value of 0 indicates that the transaction is allowed unlimited amount of time to complete. The transaction does not time out if a time out value of 0 is used. If this method is not called, then any Session that is returned by the getSession method of this interface has a transaction timeout value set to 0 by default. An application can override the transaction timeout setting on a per Session basis by using the setTransactionTimeout method of the com.ibm.websphere.objectgrid.Session interface.
You can also configure transaction timeout with the objectGrid.xml file in the distributed case.

int getTxTimeout();

getTxTimeout: Returns the transaction timeout value in seconds. This method returns the same value that is passed as the timeout parameter on the setTxTimeout method. If the setTxTimeout method was not called, then the method returns 0 to indicate that the transaction is allowed an unlimited amount of time to complete.

public 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.

public 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.

public 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.

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.

//Keywords

void associateKeyword(Serializable parent, Serializable child);

Deprecated: Use Index or query function to get Objects with specific attributes. The associateKeyword method provides a flexible invalidation mechanism based on keywords. This method links the two keywords together in a directional relationship. If parent is invalidated, then the child is also invalidated. Invalidating the child has no impact on the parent.

//Security

void setSecurityEnabled()

setSecurityEnabled: Enables security. Security is disabled by default.

void setPermissionCheckPeriod(long period);

setPermissionCheckPeriod: This method takes a single parameter that indicates how often to check the permission that is used to allow a client access. If the parameter is 0, all methods ask the authorization mechanism, either JAAS authorization or custom authorization, to check if the current subject has permission. This strategy might cause performance issues depending on the authorization implementation. However, this type of authorization is available if it is required. Alternatively, if the parameter is less than 0, it indicates the number of milliseconds to cache a set of permissions before returning to the authorization mechanism to refresh them. This parameter provides much better performance, but if the backend permissions are changed during this time the ObjectGrid might allow or prevent access even though the backend security provider has been modified.

void setAuthorizationMechanism(int authMechanism);

setAuthorizationMechanism: Set the authorization mechanism. The default is SecurityConstants.JAAS_AUTHORIZATION.

setMapAuthorization(MapAuthorization ma);

Deprecated: Use the setObjectGridAuthorization (ObjectGridAuthorization) method instead to plug in custom authorizations. setMapAuthorization: Sets the MapAuthorization plug-in for this ObjectGrid instance. This plug-in can be used to authorize ObjectMap or JavaMap accesses to the principals that are contained in the Subject object. A typical implementation of this plug-in is to retrieve the principals from the Subject object, and then check if the specified permissions are granted to the principals.

setSubjectSource(SubjectSource ss);

setSubjectSource: Sets the SubjectSource plugin. This plug-in can be used to get a Subject object that represents the ObjectGrid client. This subject is used for ObjectGrid authorization. The SubjectSource.getSubject method is called by the ObjectGrid runtime when the ObjectGrid.getSession method is used to get a session and the security is enabled. This plug-in is useful for an already authenticated client: it can retrieve the authenticated Subject object and then pass to the ObjectGrid instance. Another authentication is not necessary.

setSubjectValidation(SubjectValidation sv);

setSubjectValidation: Sets the SubjectValidation plugin for this ObjectGrid instance. This plug-in can be used to validate that a javax.security.auth.Subject subject that is passed to the ObjectGrid is a valid subject that has not been tampered with. An implementation of this plug-in needs support from the Subject object creator, because only the creator knows if the Subject object has been tampered with. However, a subject creator might not know if the Subject has been tampered with. In this case, this plug-in should not be used.

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 <code>ObjectGrid</code> 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. As of XD 6.1, the setMapAuthorization is deprecated and setObjectGridAuthorization is recommended for use. However, if both MapAuthorization plugin and ObjectGridAuthorization plugin are used, ObjectGrid will use the provided MapAuthorization to authorize map accesses, even though it is deprecated.

ObjectGrid interface: plug-ins

The ObjectGrid interface has several optional plug-in points for more extensible interactions.
void addEventListener(ObjectGridEventListener cb);
void setEventListeners(List cbList);
void removeEventListener(ObjectGridEventListener cb);
void setTransactionCallback(TransactionCallback callback);
int reserveSlot(String);
// Security related plug-ins
void setSubjectValidation(SubjectValidation subjectValidation);
void setSubjectSource(SubjectSource source);
void setMapAuthorization(MapAuthorization mapAuthorization);
ObjectGridEventListener: An ObjectGridEventListener interface is used to receive notifications when significant events occur on the ObjectGrid. These events include ObjectGrid initialization, beginning of a transaction, ending a transaction, and destroying an ObjectGrid. To listen for these events, create a class that implements the ObjectGridEventListener interface and add it to the ObjectGrid. These listeners are associated with each Session. See Listeners and Session interface for more information.
TransactionCallback: A TransactionCallback listener interface allows transactional events such as begin, commit and rollback signals to send to this interface. Typically, a TransactionCallback listener interface is used with a Loader. For more information, see TransactionCallback plug-in and Loaders. These events can then be used to coordinate transactions with an external resource or within multiple loaders.
reserveSlot: Allows plug-ins on this ObjectGrid to reserve slots for use in object instances that have slots like TxID.
SubjectValidation. If security is enabled, this plug-in can be used to validate a javax.security.auth.Subject class that is passed to the ObjectGrid.
MapAuthorization. If security is enabled, this plug-in can be used to authorize ObjectMap accesses to the principals that are represented by the Subject object.
SubjectSource: If security is enabled, this plug-in can be used to get a Subject object that represents the ObjectGrid client. This subject is then used for ObjectGrid authorization.

For more information about plug-ins, see Introduction to plug-ins.

Parent topic
Configure a local eXtreme Scale configuration

+
Search Tips | Advanced Search

Method	Description
BackMap defineMap(String name);	defineMap: is a factory method to define a uniquely named BackingMap. For more information about backing maps, see BackingMap interface.
BackMap getMap(String name);	getMap: Returns a BackingMap previously defined by calling defineMap. By using this method, you can configure the BackingMap, if it is not already configured through XML configuration.
BackMap createMap(String name);	createMap: Creates a BackingMap, but does not cache it for use by this ObjectGrid. Use this method with the setMaps(List) method of the ObjectGrid interface, which caches BackingMaps for use with this ObjectGrid. Use these methods when you are configuring an ObjectGrid with the Spring Framework.
void setMaps(List mapList);	setMaps: Clears any BackingMaps that have been previously defined on this ObjectGrid and replaces them with the list of BackingMaps that is provided.
public Session getSession() throws ObjectGridException, TransactionCallbackException;	getSession: Returns a Session, which provides begin, commit, rollback functionality for a Unit of Work. For more information about Session objects, see Session interface.
Session getSession(CredentialGenerator cg);	getSession(CredentialGenerator cg): Get a session with a CredentialGenerator object. This method can only be called by the ObjectGrid client in a client server environment.
Session getSession(Subject subject);	getSession(Subject subject): Allows the use of a specific Subject object rather than the one configured on the ObjectGrid to get a Session.
void initialize() throws ObjectGridException;	initialize: ObjectGrid is initialized and available for general use. This method is called implicitly when the getSession method is called, if the ObjectGrid is not in an initialized state.
void destroy();	destroy: The framework is disassembled and cannot be used after this method is called.
void setTxTimeout(int timeout);	setTxTimeout: Use this method to set the amount of time, in seconds, that a transaction that is started by a session that this ObjectGrid instance created is allowed for completion. If a transaction does not complete within the specified amount of time, the Session that started the transaction is marked as being "timed out". Marking a Session as timed out causes the next ObjectMap method that is invoked by the timed out Session to result in a com.ibm.websphere.objectgrid.TransactionTimeoutException exception. The Session is marked as rollback only, which causes the transaction to be rolled back even if the application calls the commit method instead of the rollback method after the TransactionTimeoutException exception is caught by the application. A timeout value of 0 indicates that the transaction is allowed unlimited amount of time to complete. The transaction does not time out if a time out value of 0 is used. If this method is not called, then any Session that is returned by the getSession method of this interface has a transaction timeout value set to 0 by default. An application can override the transaction timeout setting on a per Session basis by using the setTransactionTimeout method of the com.ibm.websphere.objectgrid.Session interface. You can also configure transaction timeout with the objectGrid.xml file in the distributed case.
int getTxTimeout();	getTxTimeout: Returns the transaction timeout value in seconds. This method returns the same value that is passed as the timeout parameter on the setTxTimeout method. If the setTxTimeout method was not called, then the method returns 0 to indicate that the transaction is allowed an unlimited amount of time to complete.
public 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.
public 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.
public 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.
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.
//Keywords
void associateKeyword(Serializable parent, Serializable child);	Deprecated: Use Index or query function to get Objects with specific attributes. The associateKeyword method provides a flexible invalidation mechanism based on keywords. This method links the two keywords together in a directional relationship. If parent is invalidated, then the child is also invalidated. Invalidating the child has no impact on the parent.
//Security
void setSecurityEnabled()	setSecurityEnabled: Enables security. Security is disabled by default.
void setPermissionCheckPeriod(long period);	setPermissionCheckPeriod: This method takes a single parameter that indicates how often to check the permission that is used to allow a client access. If the parameter is 0, all methods ask the authorization mechanism, either JAAS authorization or custom authorization, to check if the current subject has permission. This strategy might cause performance issues depending on the authorization implementation. However, this type of authorization is available if it is required. Alternatively, if the parameter is less than 0, it indicates the number of milliseconds to cache a set of permissions before returning to the authorization mechanism to refresh them. This parameter provides much better performance, but if the backend permissions are changed during this time the ObjectGrid might allow or prevent access even though the backend security provider has been modified.
void setAuthorizationMechanism(int authMechanism);	setAuthorizationMechanism: Set the authorization mechanism. The default is SecurityConstants.JAAS_AUTHORIZATION.
setMapAuthorization(MapAuthorization ma);	Deprecated: Use the setObjectGridAuthorization (ObjectGridAuthorization) method instead to plug in custom authorizations. setMapAuthorization: Sets the MapAuthorization plug-in for this ObjectGrid instance. This plug-in can be used to authorize ObjectMap or JavaMap accesses to the principals that are contained in the Subject object. A typical implementation of this plug-in is to retrieve the principals from the Subject object, and then check if the specified permissions are granted to the principals.
setSubjectSource(SubjectSource ss);	setSubjectSource: Sets the SubjectSource plugin. This plug-in can be used to get a Subject object that represents the ObjectGrid client. This subject is used for ObjectGrid authorization. The SubjectSource.getSubject method is called by the ObjectGrid runtime when the ObjectGrid.getSession method is used to get a session and the security is enabled. This plug-in is useful for an already authenticated client: it can retrieve the authenticated Subject object and then pass to the ObjectGrid instance. Another authentication is not necessary.
setSubjectValidation(SubjectValidation sv);	setSubjectValidation: Sets the SubjectValidation plugin for this ObjectGrid instance. This plug-in can be used to validate that a javax.security.auth.Subject subject that is passed to the ObjectGrid is a valid subject that has not been tampered with. An implementation of this plug-in needs support from the Subject object creator, because only the creator knows if the Subject object has been tampered with. However, a subject creator might not know if the Subject has been tampered with. In this case, this plug-in should not be used.
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 <code>ObjectGrid</code> 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. As of XD 6.1, the setMapAuthorization is deprecated and setObjectGridAuthorization is recommended for use. However, if both MapAuthorization plugin and ObjectGridAuthorization plugin are used, ObjectGrid will use the provided MapAuthorization to authorize map accesses, even though it is deprecated.