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

java.lang.Object
  com.ibm.websphere.objectgrid.plugins.builtins.TranPropListener

All Implemented Interfaces:

EventListener, ObjectGridEventListener

Deprecated. This plug-in has been deprecated in version 7.1.1. See the JMSObjectGridEventListener plug-in for equivalent function.

@Deprecated
public class TranPropListener
extends Object
implements ObjectGridEventListener

This implementation of the ObjectGridEventListener interface allows users to propagate successful 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 its 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 ObjectGrid 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. If that scenario is a problem, compression can be disabled (the default value).

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 work independently in the same JVM, and cause 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 option, 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="disable"
                    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.

Since:

WAS XD 6.0

See Also:

ObjectGridManager, DistributionMode

Constructor Summary

TranPropListener()
Deprecated. Creates a new TranPropListener.

Method Summary

void	destroy() Deprecated. Called when the ObjectGrid instance itself is being destroyed.
String	getCompressionMode() Deprecated. Gets the compression mode.
String	getPropagateMode() Deprecated. Gets the propagate mode.
String	getPropagateService() Deprecated. Gets the propagate service
String	getPropagateVersionOption() Deprecated. Gets the propagate version option.
void	initialize(Session session) Deprecated. Users do not call this method directly, an ObjectGrid instance's initalize() methods will call this method at the appropriate time.
void	setCompressionMode(String compressionEnabledOption) Deprecated. Sets the compression mode.
void	setPropagateMode(String propagateOperation) Deprecated. Sets the propagate mode.
void	setPropagateService(String propagateService) Deprecated. Sets the propagate service.
void	setPropagateVersionOption(String propagateOption) Deprecated. Sets the propagate version option.
void	startTransactionReceiver() Deprecated. Stops the transaction receiver background thread.
void	stopTransactionReceiver(boolean queueTransactionCommitRequests) Deprecated. Stops the transaction receiver background thread.
void	transactionBegin(String txid, boolean isWriteThroughEnabled) Deprecated. Signals the beginning of a Session transaction.
void	transactionEnd(String txid, boolean isWriteThroughEnabled, boolean committed, Collection changes) Deprecated. Signals the ending of a Session transaction.

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Constructor Detail

TranPropListener

public TranPropListener()

Deprecated.

Creates a new TranPropListener.

Throws:

UnsupportedOperationException - if this listener is added to an ObjectGrid instance in a non WebSphere environment or using it in the WebSphere z/OS environment

Method Detail

getPropagateMode

public String getPropagateMode()

Deprecated.

Gets the propagate mode.

Returns:

the propagate mode

See Also:

setPropagateMode(String)

setPropagateMode

public void setPropagateMode(String propagateOperation)

Deprecated.

Sets the propagate mode.

This method allows a user to set the propagate mode for this listener either programatically or using the XML support. Propagation is enabled to either propagate all changes as updates or converts updates to invalidates (See DistributionMode for more details).

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

Parameters:

propagateOperation - the propagateMode to set.

Throws:

IllegalArgumentException - if propagateOperation is null or is not one of the valid propagate modes

getPropagateVersionOption

public String getPropagateVersionOption()

Deprecated.

Gets the propagate version option.

Returns:

the propagate version option.

See Also:

setPropagateVersionOption(String)

setPropagateVersionOption

public void setPropagateVersionOption(String propagateOption)

Deprecated.

Sets the propagate version option.

This method allows a user to set the propagate version option for this listener either programatically or using the XML support Propagation is enabled to either propagate version information or not. (See DistributionMode for more detail).

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

Parameters:

propagateOption - the propagate version option to set.

Throws:

IllegalArgumentException - if propagateOption is null or is not one of the valid propagate version options

getPropagateService

public String getPropagateService()

Deprecated.

Gets the propagate service

Returns:

the propagate service.

See Also:

setPropagateService(String)

setPropagateService

public void setPropagateService(String propagateService)

Deprecated.

Sets the propagate service.

This method allows a user to set the propagate service option for this listener either programatically or using the XML support. By default, propagation is enabled to propagate to and receive transaction commit information from 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.

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

Parameters:

propagateService - the propagate service to set

Throws:

IllegalArgumentException - if propagateService is null or is not one of the valid propagate service options

initialize

public void initialize(Session session)

Deprecated.

Users do not call this method directly, an ObjectGrid instance's initalize() methods will call this method at the appropriate time.

Specified by:

initialize in interface ObjectGridEventListener

Parameters:

session - a Session instance that this listener is associated with.

See Also:

ObjectGrid.initialize(), ObjectGridEventListener.initialize(Session)

transactionEnd

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

Deprecated.

Description copied from interface: ObjectGridEventListener

Signals the ending of a Session transaction.

A string version of the TxID is provided for correlating with the begin of the transaction, if so desired. Map changes are also reported with the collection of LogSequences passed to this method. Typical uses of this event are for customers doing custom peer invalidation or peer commit push. This event listener gives them the changes. Calls to this method are made after commit and are sequenced so that they are delivered one by one, not in parallel. The event order is the commit and rollback order.

For an ObjectGridEventListener receiving changes in an ObjectMap that is configured to use a OutputFormat.RAW for the keys or values, the keys and values objects in the LogSequences will be SerializedKey or SerializedValue objects respectively. If required, you can use the SerializedEntry.getObject() method to retrieve (possibly inflating the serialized object) the original key or value object.

To override the map's output format configuration, use the PluginOutputFormat annotation in the implementation class.

Specified by:

transactionEnd in interface ObjectGridEventListener

Parameters:

txid - string version of the TxID

isWriteThroughEnabled - boolean flag indicating whether the Session transaction was started using the Session.beginNoWriteThrough(). method. false is passed if beginNoWriteThrough() was used.

committed - a boolean flag indicating whether the transaction was committed (true) or rolled back (false)

changes - a Collection of LogSequences representing the changes that were committed or rolled back.

See Also:

ObjectGridEventListener.transactionEnd(String, boolean, boolean, Collection)

transactionBegin

public void transactionBegin(String txid,
                             boolean isWriteThroughEnabled)

Deprecated.

Description copied from interface: ObjectGridEventListener

Signals the beginning of a Session transaction.

A stringified version of the TxID is provided for correlating with the end of the transaction, if so desired. The type of transaction is also provided by the isWriteThroughEnabled boolean parameter.

Specified by:

transactionBegin in interface ObjectGridEventListener

Parameters:

txid - Stringified version of the TxID

isWriteThroughEnabled - boolean flag indicating whether the Session transaction was started using the Session.beginNoWriteThrough(). method. false is passed if beginNoWriteThrough() was used.

See Also:

ObjectGridEventListener.transactionBegin(String, boolean)

stopTransactionReceiver

public void stopTransactionReceiver(boolean queueTransactionCommitRequests)

Deprecated.

Stops the transaction receiver background thread.

This method is used to control the background thread processing transactions received from other ObjectGrid instances with same "name" and configured with the builtin distributed transaction propagation support. This method 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.

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 queueTransactionCommitRequests parameter is false, the safest approach, transaction commits on the other ObjectGrid instance of the same name will be received by the listener, but the request will be thrown away. For optimistic updates this maybe acceptable, but one users should consider. If the queueTransactionCommitRequests parameter 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 one takes memory in the server. Without the work thread processing these commits, the queue will grow unbounded.

Parameters:

queueTransactionCommitRequests - whether remote requests should be queued up while the receiving commit worker thread is disabled.

startTransactionReceiver

public void startTransactionReceiver()

Deprecated.

Stops the transaction receiver background thread.

This method is used to control the background thread processing transactions received from other ObjectGrid instances with same "name" and configured with the builtin distributed transaction propagation support. This method 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()

Deprecated.

Gets the compression mode.

Returns:

the compression mode.

See Also:

setCompressionMode(String)

setCompressionMode

public void setCompressionMode(String compressionEnabledOption)

Deprecated.

Sets the compression mode.

This method allows a user to set the compression mode for this listener either programatically or using the XML support. By default, compression is enabled as it reduces the overall network traffic within the cluster, at a cost in the local JVM to compress/uncompress. The acceptable values are either "enable" or "disable", with "disable" being the default if not specified.

Parameters:

compressionEnabledOption - the compression mode to set.

Throws:

IllegalArgumentException - if compressionEnabledOption is null or is not one of the valid compression modes

destroy

public void destroy()

Deprecated.

Called when the ObjectGrid instance itself is being destroyed.

At this point, the reciever cannot be restarted as the ObjectGrid instance is going away permanently.

Specified by:

destroy in interface ObjectGridEventListener

See Also:

ObjectGrid.destroy(), ObjectGridEventListener.destroy()