IBM WebSphere Extended Deployment (XD)TM
Release 6.0

com.ibm.websphere.objectgrid
ObjectGrid



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


Method Summary
public  SessiongetSession()
          

Gets a Session object that can be used by a single thread at a time. It's not allowed.

public  SessiongetSession(javax.security.auth.Subject)
           Allows the use of a specific Subject rather than the one configured on the ObjectGrid to get a Session.
public  voidsetTransactionCallback(com.ibm.websphere.objectgrid.plugins.TransactionCallback)
           A single cache is a single domain. All CacheLoaders defined for BackingMaps will normally.
public  TransactionCallbackgetTransactionCallback()
           Retrieves the TransactionCallback object for the current ObjectGrid..
public  BackingMapdefineMap(java.lang.String)
           Defines a BackingMap that will be used by the application. This method.
public  BackingMapcreateMap(java.lang.String)
           Creates a BackingMap, but does not cache it for use by this ObjectGrid. This method is.
public  voidsetMaps(java.util.List)
           Clears any BackingMaps that have been previously defined on this ObjectGrid and replaces them with the List of BackingMaps provided.
public  ListgetListOfMapNames()
           Gets the list of map names currently defined for this ObjectGrid instance. .
public  BackingMapgetMap(java.lang.String)
           Returns a BackingMap previously defined by calling #defineMap(String).
public  voidinitialize()
           This method begins the bootstrapping of the ObjectGrid and Session instances..
public  voidaddEventListener(com.ibm.websphere.objectgrid.plugins.ObjectGridEventListener)
           Add an EventListener to the Session. Significant events will be communicated.
public  voidremoveEventListener(com.ibm.websphere.objectgrid.plugins.ObjectGridEventListener)
           Removes an EventListener from the Session. If the desired EventListener is.
public  voidsetEventListeners(java.util.List)
           This overwrites the current list of callbacks and replaces it with the supplied list of callbacks.
public  ListgetEventListeners()
           This returns the current list of ObjectGridEventListeners.
public  voidassociateKeyword(java.io.Serializable, java.io.Serializable)
           This links the two keywords together in a directional relationship. If parent is invalidated.
public  StringgetName()
           Gets the name of this ObjectGrid. This method is useful for authorization as.
public  voidsetName(java.lang.String)
           Sets the name of this ObjectGrid.
public  intreserveSlot(java.lang.String)
           Allows plugins on this ObjectGrid to reserve slots for use in object instances that have slots like TxID.
public  voidsetSubjectValidation(com.ibm.websphere.objectgrid.security.plugins.SubjectValidation)
           Sets the SubjectValidation plugin for this ObjectGrid instance. .
public  voidsetMapAuthorization(com.ibm.websphere.objectgrid.security.plugins.MapAuthorization)
           Sets the MapAuthorization plugin for this ObjectGrid instance. .
public  voidsetAuthorizationMechanism(int)
           Sets the authorization mechanism. .
public  voidsetSecurityEnabled()
           Enables the ObjectGrid security. .
public  booleanisSecurityEnabled()
          

Checks whether security is enabled on this ObjectGrid or not..

public  voidsetPermissionCheckPeriod(int)
           Sets permission check period..
public  voidsetSubjectSource(com.ibm.websphere.objectgrid.security.plugins.SubjectSource)
           Sets the SubjectSource plugin. .
public  voidsetTxTimeout(int)
          
public  intgetTxTimeout()
          
public  voiddestroy()
           This method should be invoked when the ObjectGrid is no longer being used.
public  SessiongetSession(com.ibm.websphere.objectgrid.security.plugins.CredentialGenerator)
           Get a session with a CredentialGenerator. This method can only be called .

Method Detail

getSession

public Session getSession()

Gets a Session object that can be used by a single thread at a time. It's 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 security is enabled, this method will use the SubjectSource to get a Subject object.

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


See Also:
    initialize()


Returns:
     An instance of Session


Throws:
    com.ibm.websphere.objectgrid.ObjectGridExceptioncom.ibm.websphere.objectgrid.plugins.TransactionCallbackExceptionjava.lang.IllegalStateException


getSession

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

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

Parameters:


Returns:
     An instance of Session


Throws:
    com.ibm.websphere.objectgrid.ObjectGridExceptioncom.ibm.websphere.objectgrid.plugins.TransactionCallbackExceptioncom.ibm.websphere.objectgrid.security.plugins.InvalidSubjectExceptionjava.lang.IllegalStateException


setTransactionCallback

public void setTransactionCallback(TransactionCallback callback)
A single cache is a single domain. All CacheLoaders defined for BackingMaps will normally cooperate, thus a corresponding TransactionCallback object needs to be set on the ObjectGrid.
Parameters:
    callback - An instance of a TransactionCallback object


getTransactionCallback

public TransactionCallback getTransactionCallback()
Retrieves the TransactionCallback object for the current ObjectGrid.

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



Returns:
     TransactionCallback


defineMap

public BackingMap defineMap(String name)
Defines a BackingMap that will be used by the application. This method would only be used to supplement or override the xml configuration of the cache.

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

Parameters:
    name - is the name of the map being defined.


Returns:
     BackingMap reference


Throws:
    java.lang.IllegalStateException


createMap

public BackingMap createMap(String name)
Creates a BackingMap, but does not cache it for use by this ObjectGrid. This method is to be used in tandem with the ObjectGrid#setMaps(List) method, which will cache BackingMaps for use 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 ObjectGrid#initialize() method. Also, keep in mind that the ObjectGrid#getSession() method implicitly calls the ObjectGrid.initialize() method if it has yet to be called by the application.
See Also:

    setMaps(List)
Parameters:


Returns:
    


setMaps

public 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 ObjectGrid#initialize() method. Also, keep in mind that the ObjectGrid#getSession() method implicitly calls the ObjectGrid.initialize() method if it has yet to be called by the application.

Parameters:
    mapList - a list of BackingMaps to set on this ObjectGrid


getListOfMapNames

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


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


getMap

public BackingMap getMap(String name)
Returns a BackingMap previously defined by calling #defineMap(String).
Parameters:
    name - is the same name that was used as an argument to the #defineMap(String) method. A null reference is returned if defineMap was not previously called for the specified map name.


Returns:
     the BackingMap instance


initialize

public void initialize()
This method 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 (for now) since the first call to #getSession() will perform an implicit initialization.


Throws:
    com.ibm.websphere.objectgrid.ObjectGridException


addEventListener

public void addEventListener(ObjectGridEventListener cb)
Add an EventListener to the Session. Significant events will be communicated to interested listeners via this callback. 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 ObjectGrid#initialize() method.

Parameters:
    cb - An instance of ObjectGridEventListener


removeEventListener

public void removeEventListener(ObjectGridEventListener cb)
Removes an EventListener from the Session. If the desired EventListener is not found on the Session, no error will be returned.

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

Parameters:
    cb - An instance of ObjectGridEventListener


setEventListeners

public void setEventListeners(List callbacks)
This overwrites the current list of callbacks and replaces it with the supplied list of callbacks.

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

Parameters:


getEventListeners

public List getEventListeners()
This returns the current list of ObjectGridEventListeners.


Returns:
     The current list of ObjectGridEventListeners.


associateKeyword

public void associateKeyword(Serializable parent,Serializable child)
This links the two keywords together in a directional relationship. If parent is invalidated then child is also invalidated. Invalidating the child has no impact on the parent. For example, this can be used to add "New York" as a child of "USA" so that if USA is invalidated then all New York entries will also be invalidated.
Parameters:
    child - All entries associated with this keyword will also be associated with the parent keyword


getName

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


setName

public void setName(String gridName)
Sets the name of this ObjectGrid. Once this is set then it cannot be changed.
Parameters:
    gridName - The ObjectGrid name to used.


reserveSlot

public int reserveSlot(String containerName)
Allows plugins on this ObjectGrid to reserve slots for use in object instances that have slots like TxID.
See Also:
    SLOT_NAME
Parameters:
    containerName - The name of the Object with the slots.


Returns:
     The slot index to use.


setSubjectValidation

public void setSubjectValidation(SubjectValidation subjectValidation)
Sets the SubjectValidation plugin for this ObjectGrid instance.

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

    getSession(Subject)
Parameters:
    subjectValidation - the SubjectValidation plugin


setMapAuthorization

public void setMapAuthorization(MapAuthorization mapAuthorization)
Sets the MapAuthorization plugin for this ObjectGrid instance.

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

Parameters:
    mapAuthorization - the MapAuthorization plugin


setAuthorizationMechanism

public void setAuthorizationMechanism(int authMechanism)
Sets the authorization mechanism.

The default authorization mechanism is com.ibm.websphere.objectgrid.security.SecurityConstants#AUTHORIZATION_MECHANISM_JAAS.
See Also:

    AUTHORIZATION_MECHANISM_JAASAUTHORIZATION_MECHANISM_CUSTOM
Parameters:
    authMechanism - the map authorization mechanism


setSecurityEnabled

public void setSecurityEnabled()
Enables the ObjectGrid security. Security on the ObjectGrid level refers to authorizations on the ObjectMap access.


isSecurityEnabled

public boolean isSecurityEnabled()

Checks whether security is enabled on this ObjectGrid or not. Security on the ObjectGrid level refers to authorizations on the ObjectMap access.



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


setPermissionCheckPeriod

public void setPermissionCheckPeriod(int period)
Sets 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 get/put/update/remove/evict call will ask the authorization mechanism, either JAAS authorization or custom authorization to check if the current Subject has permission. This may be prohibitively expensive from a performance point of view depending on the authorization implementation but if this 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 provides much better performance but you run the risk that if the backend permissions are changed during this time then the ObjectGrid will possibly allow or prevent access even though the backend security provider has been modified.

Parameters:
    period - the permission check period in seconds.


setSubjectSource

public void setSubjectSource(SubjectSource source)
Sets the SubjectSource plugin.

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

Parameters:
    source - the SubjectSource plugin


setTxTimeout

public void setTxTimeout(int seconds)
Parameters:


getTxTimeout

public int getTxTimeout()


destroy

public void destroy()
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 inflight Sessions will be allowed to continue, if the resources are still available to complete processing.


getSession

public Session getSession(CredentialGenerator credGen)
Get a session with a CredentialGenerator. This method can only be called by the ObjectGrid client in a client server environment. If ObjectGrid is used in a core model, that is, within the same JVM with no client or server existing, getSession(Subject) should be used to secure the ObjectGrid.
Parameters:


IBM WebSphere Extended Deployment (XD)TM
Release 6.0