View Javadoc

1   /*
2    * $Id: ThreadSafeAccess.java 7963 2007-08-21 08:53:15Z dirk.olmes $
3    * --------------------------------------------------------------------------------------
4    * Copyright (c) MuleSource, Inc.  All rights reserved.  http://www.mulesource.com
5    *
6    * The software in this package is published under the terms of the CPAL v1.0
7    * license, a copy of which has been included with this distribution in the
8    * LICENSE.txt file.
9    */
10  
11  package org.mule.impl;
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  {
40  
41      /**
42       * This method may be called before data in the object are accessed.  It should verify that the
43       * access policy is followed correctly (if not, a runtime exception may be thrown).
44       *
45       * @param write True if the access will mutate values.
46       */
47      void assertAccess(boolean write);
48  
49      /**
50       * This method should ONLY be used in the construction of composite ThreadSafeAccess instances.
51       * For example, a ThreadSafeAccess UMOEvent contains a ThreadSafeAccess UMOMessageAdapter. During
52       * the construction of the event, the message adapter may be bound to the contructing thread.
53       * Calling this method releases that binding so that the event as a whole can be passed to a new
54       * thread unbound.
55       */
56      void resetAccessControl();
57  
58      /**
59       * @return A new instance of the implementing class, unbound to any thread and mutable.
60       */
61      ThreadSafeAccess newThreadCopy();
62  
63  }