Method: isCompleted()

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