01: /*
02: * $Id: ThreadSafeAccess.java 10489 2008-01-23 17:53:38Z dfeist $
03: * --------------------------------------------------------------------------------------
04: * Copyright (c) MuleSource, Inc. All rights reserved. http://www.mulesource.com
05: *
06: * The software in this package is published under the terms of the CPAL v1.0
07: * license, a copy of which has been included with this distribution in the
08: * LICENSE.txt file.
09: */
10:
11: package org.mule.api;
12:
13: /**
14: * Interface implemented by message-related objects that avoid exposing mutable data to multiple threads
15: * by providing immutable copies. This interface is optional - it is an implementation detail that is
16: * tested for dynamically and used only if available.
17: *
18: * <p>To avoid "scribbling" where several threads change state within in a single method (typically
19: * in inconsistent ways, causing subtle and intermittent errors) we use the following access policy for
20: * message related objects:</p>
21: *
22: * <ul>
23: *
24: * <li>A new object is "unbound" and "mutable".</li>
25: *
26: * <li>An object is "bound" to the first thread that calls the object after it is created.</li>
27: *
28: * <li>A "mutable" object can be modified only by the thread to which it is bound.</li>
29: *
30: * <li>An object is "sealed" (no longer "mutable") when it is accessed by a thread other than the
31: * thread to which it is "bound". It is an error to attempt to change a "sealed" object.</li>
32: *
33: * </ul>
34: *
35: * <p>In practice this means that objects are initially mutable, but become immutable once they are
36: * shared.</p>
37: */
38: public interface ThreadSafeAccess {
39: final boolean WRITE = true;
40: final boolean READ = false;
41:
42: /**
43: * This method may be called before data in the object are accessed. It should verify that the
44: * access policy is followed correctly (if not, a runtime exception may be thrown).
45: *
46: * @param write True if the access will mutate values.
47: */
48: void assertAccess(boolean write);
49:
50: /**
51: * This method should ONLY be used in the construction of composite ThreadSafeAccess instances.
52: * For example, a ThreadSafeAccess MuleEvent contains a ThreadSafeAccess MessageAdapter. During
53: * the construction of the event, the message adapter may be bound to the contructing thread.
54: * Calling this method releases that binding so that the event as a whole can be passed to a new
55: * thread unbound.
56: */
57: void resetAccessControl();
58:
59: /**
60: * @return A new instance of the implementing class, unbound to any thread and mutable.
61: */
62: ThreadSafeAccess newThreadCopy();
63:
64: }
|