org.mule.api

Interface ThreadSafeAccess

All Known Implementing Classes:

DefaultMessageCollection, DefaultMuleEvent, DefaultMuleMessage

public interface ThreadSafeAccess

Interface implemented by message-related objects that avoid exposing mutable data to multiple threads by providing immutable copies. This interface is optional - it is an implementation detail that is tested for dynamically and used only if available.

To avoid "scribbling" where several threads change state within in a single method (typically in inconsistent ways, causing subtle and intermittent errors) we use the following access policy for message related objects:

• A new object is "unbound" and "mutable".
• An object is "bound" to the first thread that calls the object after it is created.
• A "mutable" object can be modified only by the thread to which it is bound.
• An object is "sealed" (no longer "mutable") when it is accessed by a thread other than the thread to which it is "bound". It is an error to attempt to change a "sealed" object.

In practice this means that objects are initially mutable, but become immutable once they are shared.

Nested Class Summary

Nested Classes

Modifier and Type	Interface and Description
static class	ThreadSafeAccess.AccessControl This helper class can be used by code implementing this interface to determine whether the thread safety of a message should be enforced or not.

Field Summary

Fields

Modifier and Type	Field and Description
static boolean	READ
static boolean	WRITE

Method Summary

Methods

Modifier and Type	Method and Description
void	assertAccess(boolean write) This method may be called before data in the object are accessed.
ThreadSafeAccess	newThreadCopy()
void	resetAccessControl() This method should ONLY be used in the construction of composite ThreadSafeAccess instances.

Field Detail

WRITE

static final boolean WRITE

See Also:

Constant Field Values

READ

static final boolean READ

See Also:

Constant Field Values

Method Detail

assertAccess

void assertAccess(boolean write)

This method may be called before data in the object are accessed. It should verify that the access policy is followed correctly (if not, a runtime exception may be thrown).

Parameters:

write - True if the access will mutate values.

resetAccessControl

void resetAccessControl()

This method should ONLY be used in the construction of composite ThreadSafeAccess instances. For example, a ThreadSafeAccess MuleEvent contains a ThreadSafeAccess MuleMessage. During the construction of the event, the message may be bound to the contructing thread. Calling this method releases that binding so that the event as a whole can be passed to a new thread unbound.

newThreadCopy

ThreadSafeAccess newThreadCopy()

Returns:

A new instance of the implementing class, unbound to any thread and mutable.