1 /*
2 Copyright 2007 Ramon Servadei
3
4 Licensed under the Apache License, Version 2.0 (the "License");
5 you may not use this file except in compliance with the License.
6 You may obtain a copy of the License at
7
8 http://www.apache.org/licenses/LICENSE-2.0
9
10 Unless required by applicable law or agreed to in writing, software
11 distributed under the License is distributed on an "AS IS" BASIS,
12 WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
13 See the License for the specific language governing permissions and
14 limitations under the License.
15 */
16 package fulmine.protocol.wire.operation;
17
18 import java.util.Map;
19 import java.util.Set;
20
21 import fulmine.context.IPermissionProfile;
22 import fulmine.model.component.IComponent;
23
24 /**
25 * This represents some atomic operation that is performed over any number of
26 * objects. This merely marks some operation, this object does not include any
27 * operation logic. Its main purpose is to track all the objects that are
28 * performed in the scope of the operation.
29 * <p>
30 * Implementations can be used to prevent circular references from being
31 * processed or prevent fields from being processed in the operation based on
32 * some criteria.
33 *
34 * @author Ramon Servadei
35 */
36 public interface IOperationScope
37 {
38 /**
39 * Get the set of objects that form the current scope. The operation is
40 * referencing these object. The set should not be mutated.
41 *
42 * @return an immutable {@link Set} of objects that the operation includes.
43 */
44 Set<Object> getScope();
45
46 /**
47 * Get the exceptions that have occurred in the operation up to this point.
48 *
49 * @return a map of the exceptions that occurred, keyed by the object in
50 * which the exception occurred.
51 */
52 Map<Object, Exception> getExceptions();
53
54 /**
55 * Determine if the object should be included in the operation.
56 *
57 * @param object
58 * the object to examine for eligibility in the operation this
59 * represents
60 * @return true if the object should be included in the operation
61 * @see #exiting(IComponent)
62 */
63 boolean include(Object object);
64
65 /**
66 * Signals that the executing thread is exiting a code block that executed
67 * {@link #include(Object)}. This method serves to allow the scope to do any
68 * required post-processing after the {@link #include(Object)} request. A
69 * flag indicates if the object was actually processed or not.
70 *
71 * @param object
72 * an object that was previously examined with
73 * {@link #include(Object)}
74 * @param processed
75 * true if the component was processed
76 */
77 void exiting(Object object, boolean processed);
78
79 /**
80 * Signals an exception occurred during the operation within the object
81 * argument.
82 *
83 * @param object
84 * the object in which the exception occurred
85 * @param e
86 * the exception that occurred
87 */
88 void exception(Object object, Exception e);
89
90 /**
91 * Validate the scope. If there was any exception, this method throws an
92 * {@link IllegalStateException} encapsulating the exceptions that occurred
93 * during the scope.
94 *
95 * @throws IllegalStateException
96 * if there was an exception
97 */
98 void validate();
99
100 /**
101 * Get the permission profile for the operation scope.
102 *
103 * @return the permission profile for this scope
104 */
105 IPermissionProfile getPermissionProfile();
106 }