1 /* 2 * $Id: ThreadSafeAccess.java 7976 2007-08-21 14:26:13Z 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 }