Classes in this File | Line Coverage | Branch Coverage | Complexity | ||||
ThreadSafeAccess |
|
| 1.0;1 |
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 | } |