IBM WebSphere Extended Deployment (XD)TM
Release 6.0.1

com.ibm.websphere.objectgrid.plugins.builtins
TranPropListener

java.lang.Object
  |
  +--com.ibm.websphere.objectgrid.plugins.builtins.TranPropListener
All Implemented Interfaces
ObjectGridEventListener


This listener allows customers to propagate successfully ObjectGrid transaction commits to other WebSphere Application Servers hosting the same ObjectGrid instance (based upon the ObjectGrid name). The sole attribute to distinguish each ObjectGrid is the name. If the names are the same, and both are configured with this listener on separate WebSphere Application Server coregroup members (can span a WebSphere cluster) non-readonly changes will be propagated depending on the options the user selects.

Four options for distribution are provided. They include: push, push with versioning (the default), invalidate and invalidate with versioning. The various options are described in the DistributionMode class.

In addition to the distribution mode, the user can configure if the listener should only propagate transactions to other clusters members, only receive transaction commits from other similarly configured ObjectGrid instances, or do both in each application server instance (the default). This support provides for optimistic, asynchronous distributed transaction commit support only.

Finally, the customer can configure if compression should be enabled. Generally for typical transaction commit streams, the compression support will use some local JVM cpu and memory footprint to create a compressed stream for transmission to other instances of the map enabled with this listener support located in other WebSphere core group members. However, users should be aware of a common compression concern. For the scenarios when there are usually very short messages, the overhead maybe more than the computing resources saved by doing the compression (this is anticipated to be a rare case). If that scenario is a problem, compression can be disabled.

This class will only initialize correctly within a WebSphere runtime environment and requires the High Availability Manager to successful function.

Users must have each ObjectGrid instance configured with this listener (see the programming guide) that they wish to send and receive distributed transactions. This support has worker thread support to ensure all transaction content is processed in the background (asynchronous support). The thread that processes this work is normally started during the initial ObjectGrid instance initialization (ObjectGridManager will cache this for a single JVM. Users are encouraged to use the ObjectGridManager interface to consistently manage a single ObjectGrid instance within a single JVM). Server shutdown will cause the worker thread to exit. If a single JVM has multiple instances of a specific ObjectGrid instance with this listener support configured, each instance will need to work independently in the same JVM, and cause the performance overhead because each will duplicate the same processing.

For users who wish to control the worker thread support themselves methods are provided for this, but this should be done carefully. The anticipated use of this support is to start the server, use the ObjectGridManager to create the initial instance, have all in JVM users lookup the existing instance of the ObjectGrid from the ObjectGridManager and finally at server shutdown the threads handling the distribution transaction support will be cleaned up properly and in an orderly manner without programmer or administrator intervention.

Each application using the ObjectGrid in a WebSphere Application Server that is sharing commit information must be in the same HA Manager coregroup.

The following example illustrates how this class can be configured for a specific ObjectGrid:

 
           <bean id="ObjectGridEventListener" className="com.ibm.websphere.objectgrid.plugins.builtins.TranPropListener" >
            
               <property name="propagateService" type="java.lang.String" value="all" 
                    description="Option all includes propagating and receiving transaction commits.
                    (propagate) and (receive) other options." />
            
               <property name="propagateMode" type="java.lang.String" value="update" 
                    description="Propagate value (update), or just convert all
                    updates to invalidates in remote cache (invalidate)." />
               
               <property name="propagateVersionOption" type="java.lang.String" value="enable" 
                    description="Enable the use of versioning (enable) or disable (disable)." />               
      
               <property name="compressionMode" type="java.lang.String" value="enable" 
                    description="Enable the use of stream compression for transmission (enable) or disable (disable)." />         
 
            </bean>
  
 

The example above simply can be achieved by setting no properties, as the defaults are illustrated. For settings other than the defaults, see the description text above for each property.



Constructor Summary
TranPropListener()
          


Method Summary
public  StringgetPropagateMode()
          
public  voidsetPropagateMode(java.lang.String)
           This method allows a user to programatically or via the XML support to set the propagateMode for this listener.
public  StringgetPropagateVersionOption()
          
public  voidsetPropagateVersionOption(java.lang.String)
           This method allows a user to programatically or via the XML support to set the propagateVersionOption for this listener.
public  StringgetPropagateService()
          
public  voidsetPropagateService(java.lang.String)
           This method allows a user to programatically or via the XML support to set the propagateService option for this listener.
public  voidinitialize(com.ibm.websphere.objectgrid.Session)
          
public  voidtransactionEnd(java.lang.String, boolean, boolean, java.util.Collection)
          
public  voidtransactionBegin(java.lang.String, boolean)
          
public  voidstopTransactionReceiver(boolean)
           stopTransactionReceiver(boolean) method is used control the background thread processing transactions receieved from other ObjectGrid instances with same "name" and configured with the builtin distributed transaction propgation support.
public  voidstartTransactionReceiver()
           startTransactionReceiver() method is used control the background thread processing transactions receieved from other ObjectGrid instances with same "name" and configured with the builtin distributed transaction propgation support.
public  StringgetCompressionMode()
          
public  voidsetCompressionMode(java.lang.String)
           This method allows a user programatically or via the XML support to set the compressionMode for this listener.
public  voiddestroy()
          

Inherited Methods

Methods inherited from java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Constructor Detail

TranPropListener

public TranPropListener( )


Method Detail

getPropagateMode

public String getPropagateMode()


Returns:
     Returns the propagateMode.


setPropagateMode

public void setPropagateMode(String propagateOperation)
This method allows a user to programatically or via the XML support to set the propagateMode for this listener. By default, propagation is enabled to either propagate all changes as updates or converted updates to invalidates (See DistributionMode for more detail).

The values are either update or invalidate, with the default set to update if not specified.

Parameters:
    propagateOperation - The propagateMode to set.


getPropagateVersionOption

public String getPropagateVersionOption()


Returns:
     Returns the propagateVersionOption.


setPropagateVersionOption

public void setPropagateVersionOption(String propagateOption)
This method allows a user to programatically or via the XML support to set the propagateVersionOption for this listener. By default, propagation is enabled to either propagate version information or not. (See DistributionMode for more detail).

The values are either enable or disable, with the default set to enable if not specified.

Parameters:
    propagateOption - The propagateVersionOption to set.


getPropagateService

public String getPropagateService()


Returns:
     Returns the propagateService.


setPropagateService

public void setPropagateService(String propagateService)
This method allows a user to programatically or via the XML support to set the propagateService option for this listener. By default, propagation is enabled to propagate and receive transaction commit information to other WebSphere AppServer cluster members in the same core group and initializing a specific ObjectGrid instance of a certain name and configuring this built in ObjectGrid listener. In some cases, users may want a second cluster or specific application server to only listen to the changes for reading purposes, and the propagating and changes back to the other members offering fully read-write distributed asychronous synchronization.

The values are either all, propagate or receive, with the default set to all if not specified.

Parameters:
    propagateService - The propagateService to set.


initialize

public void initialize(Session session)

See Also:
    Users do not call this method directly, the ObjectGrid instances initalize will call this this method at the appropriate time.
Parameters:


transactionEnd

public void transactionEnd(String txid,boolean isWriteThroughEnabled, boolean committed, Collection changes)

See Also:
    transactionEnd(String, boolean, boolean, java.util.Collection)
Parameters:


transactionBegin

public void transactionBegin(String txid,boolean isWriteThroughEnabled)

See Also:
    transactionBegin(java.lang.String, boolean)
Parameters:


stopTransactionReceiver

public void stopTransactionReceiver(boolean queueTransactionCommitRequests)
stopTransactionReceiver(boolean) method is used control the background thread processing transactions receieved from other ObjectGrid instances with same "name" and configured with the builtin distributed transaction propgation support. See the description above, this is generally not a method most developers should require to use.

Generally, the work thread lifecycle for each ObjectGrid instance is managed automatically at ObjectGrid initialization and server instance shutdown.

This method stops the distributed listener thread which handles all transaction commits propagated to this JVM's ObjectGrid instances. Users should be advised, stopping this thread is something to be done only for a short amount of time (the server shutdown will handle server stop scenarios). If the queueRemoteCommits is set to false, the safest approach, transaction commits on other ObjectGrid instance of the same name will be received be the listener, but the request will be thrown away. For optimistic updates this maybe acceptable, but one users should consider. If queueRemoteCommits is set to true, the programmer should ensure the worker thread is restarted quickly, as a busy system may queue many commits very quickly, and each take memory in the server. Without the work thread processing these, the queue will grow unbounded.

Parameters:
    queueTransactionCommitRequests - Should remote requests be queued up while receiving commit worker thread is disabled.


startTransactionReceiver

public void startTransactionReceiver()
startTransactionReceiver() method is used control the background thread processing transactions receieved from other ObjectGrid instances with same "name" and configured with the builtin distributed transaction propgation support. See the description above, this is generally not a method most developers will require.

Generally, the work thread lifecycle for each ObjectGrid instance is managed automatically at ObjectGrid initialization and server instance shutdown.



getCompressionMode

public String getCompressionMode()


Returns:
     Returns the compressionMode.


setCompressionMode

public void setCompressionMode(String compressionEnabledOption)
This method allows a user programatically or via the XML support to set the compressionMode for this listener. By default, compression is enabled as it reduces the overall network traffice within the cluster, at a cost in the local JVM to compress/uncompress. The acceptable values are either enable or disable, with enable the default if not specified.
Parameters:
    compressionEnabledOption - The compressionMode to set.


destroy

public void destroy()

See Also:
    This is called when the ObjectGrid Instance itself is being destroyed. At this point, the reciever can not be restarted as the object grid instance is going away permanently.


IBM WebSphere Extended Deployment (XD)TM
Release 6.0.1