Package: Collaboration$Provider

Collaboration$Provider

Coverage

1: /*
2: * *********************************************************************************************************************
3: *
4: * TheseFoolishThings: Miscellaneous utilities
5: * http://tidalwave.it/projects/thesefoolishthings
6: *
7: * Copyright (C) 2009 - 2023 by Tidalwave s.a.s. (http://tidalwave.it)
8: *
9: * *********************************************************************************************************************
10: *
11: * Licensed under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with
12: * the License. You may obtain a copy of the License at
13: *
14: * http://www.apache.org/licenses/LICENSE-2.0
15: *
16: * Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on
17: * an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the
18: * specific language governing permissions and limitations under the License.
19: *
20: * *********************************************************************************************************************
21: *
22: * git clone https://bitbucket.org/tidalwave/thesefoolishthings-src
23: * git clone https://github.com/tidalwave-it/thesefoolishthings-src
24: *
25: * *********************************************************************************************************************
26: */
27: package it.tidalwave.actor;
28:
29: import javax.annotation.Nonnegative;
30: import javax.annotation.Nonnull;
31: import com.eaio.uuid.UUID;
32: import org.joda.time.DateTime;
33: import org.joda.time.Duration;
34:
35: /***********************************************************************************************************************
36: *
37: * Represents a single task that is possibly decomposed in multiple subtasks and provides support for waiting for its
38: * completion.
39: *
40: * @author Fabrizio Giudici
41: *
42: **********************************************************************************************************************/
43: public interface Collaboration
44: {
45: /*******************************************************************************************************************
46: *
47: *
48: *
49: ******************************************************************************************************************/
50: public static final Collaboration NULL_COLLABORATION = new Collaboration()
51: {
52: @Override @Nonnull
53: public Object getOriginatingMessage()
54: {
55: return new Object();
56: }
57:
58: @Override
59: public boolean isCompleted()
60: {
61: return true;
62: }
63:
64: @Override
65: public void waitForCompletion()
66: {
67: }
68:
69: @Override @Nonnull
70: public DateTime getStartTime()
71: {
72: return new DateTime(0);
73: }
74:
75: @Override @Nonnull
76: public Duration getDuration()
77: {
78: return new Duration(0);
79: }
80:
81: @Override
82: public Object suspend()
83: {
84: return new UUID();
85: }
86:
87: @Override
88: public void resume (@Nonnull final Object suspensionToken, @Nonnull final Runnable runnable)
89: {
90: }
91:
92: @Override
93: public void resumeAndDie (@Nonnull final Object suspensionToken)
94: {
95: }
96:
97: @Override
98: public boolean isSuspended()
99: {
100: return false;
101: }
102:
103: @Override
104: public int getDeliveringMessagesCount()
105: {
106: return 0;
107: }
108:
109: @Override
110: public int getPendingMessagesCount()
111: {
112: return 0;
113: }
114:
115: @Override
116: public int getRunningThreadsCount()
117: {
118: return 0;
119: }
120: };
121:
122: /*******************************************************************************************************************
123: *
124: * A provider of a {@link Collaboration}.
125: *
126: ******************************************************************************************************************/
127: public static interface Provider
128: {
129: /***************************************************************************************************************
130: *
131: * Returns the {@link Collaboration}.
132: *
133: * @return the {@code Collaboration}
134: *
135: **************************************************************************************************************/
136: @Nonnull
137: public Collaboration getCollaboration();
138: }
139:
140: /*******************************************************************************************************************
141: *
142: * Returns the message that originated this {@code Collaboration}.
143: *
144: * @return the message
145: *
146: ******************************************************************************************************************/
147: @Nonnull
148: public Object getOriginatingMessage();
149:
150: /*******************************************************************************************************************
151: *
152: * Returns {@code true} if the {@code Collaboration} has been completed.
153: *
154: * @return {@code true} if the {@code Collaboration} has been completed
155: *
156: ******************************************************************************************************************/
157: public boolean isCompleted();
158:
159: /*******************************************************************************************************************
160: *
161: * Waits for the completion of this {@code Collaboration}.
162: *
163: * @throws InterruptedException if the wait is interrupted
164: *
165: ******************************************************************************************************************/
166: public void waitForCompletion()
167: throws InterruptedException;
168:
169: /*******************************************************************************************************************
170: *
171: * Return the time when this {@code Collaboration} has been created.
172: *
173: * @return the creation time
174: *
175: ******************************************************************************************************************/
176: @Nonnull
177: public DateTime getStartTime();
178:
179: /*******************************************************************************************************************
180: *
181: * Return the duration of this {@code Collaboration}.
182: *
183: * @return the duration
184: *
185: ******************************************************************************************************************/
186: @Nonnull
187: public Duration getDuration();
188:
189: /*******************************************************************************************************************
190: *
191: * Sometimes a {@code Collaboration} must coordinate with the external world, waiting for an external asynchronous
192: * event that cannot be modeled with agents. For instance, a user intervention (e.g. by clicking a button) or an
193: * external piece of software that is not part of the {@code Collaboration} model. In this case, it can be marked
194: * as 'suspended' and in this case it won't be considered completed, even though there are no related pending
195: * messages or working threads. When the external event occurs, call
196: * {@link #resume(java.lang.Object, java.lang.Runnable)}.
197: *
198: * In order to support multiple reasons for suspension, a token is generated and returned. It must be passed to
199: * {@code resume()} for resuming.
200: *
201: * @see #resume(java.lang.Object, java.lang.Runnable)
202: * @see #isSuspended()
203: *
204: * @return a token representing the reason for the suspension
205: *
206: ******************************************************************************************************************/
207: public Object suspend();
208:
209: /*******************************************************************************************************************
210: *
211: * Resumes a suspended {@code Collaboration}. It executes the given {@link Runnable} which is expected to send new
212: * messages.
213: *
214: * @see #suspend()
215: * @see #isSuspended()
216: *
217: * @param suspensionToken the token representing the reason for the suspension
218: * @param resumerTask the code which resumes the {@code Collaboration}
219: *
220: ******************************************************************************************************************/
221: public void resume (@Nonnull Object suspensionToken, @Nonnull Runnable resumerTask);
222:
223: /*******************************************************************************************************************
224: *
225: * Resumes a suspended {@code Collaboration} and lets it terminate without any further operation.
226: *
227: * @see #suspend()
228: * @see #resume(java.lang.Object, java.lang.Runnable)
229: * @see #isSuspended()
230: *
231: * @param suspensionToken the token representing the reason for the suspension
232: *
233: ******************************************************************************************************************/
234: public void resumeAndDie (@Nonnull Object suspensionToken);
235:
236: /*******************************************************************************************************************
237: *
238: * Returns {@code true} when the current {@code Collaboration} is suspended.
239: *
240: * @see #suspend()
241: * @see #resume(java.lang.Object, java.lang.Runnable)
242: *
243: * @return {@code true} when it's suspended
244: *
245: ******************************************************************************************************************/
246: public boolean isSuspended();
247:
248: /*******************************************************************************************************************
249: *
250: * Returns the number of messages related to this {@code Collaboration} not yet delivered.
251: *
252: * @return the number of messages not yet delivered
253: *
254: ******************************************************************************************************************/
255: @Nonnegative
256: public int getDeliveringMessagesCount();
257:
258: /*******************************************************************************************************************
259: *
260: * Returns the number of messages related to this {@code Collaboration} not yet consumed.
261: *
262: * @return the number of messages not yet consumed
263: *
264: ******************************************************************************************************************/
265: @Nonnegative
266: public int getPendingMessagesCount();
267:
268: /*******************************************************************************************************************
269: *
270: * Returns the number of running threads assigned to this {@code Collaboration}.
271: *
272: * @return the number of threads
273: *
274: ******************************************************************************************************************/
275: @Nonnegative
276: public int getRunningThreadsCount();
277: }