001: /*
002: * $Id: Controller.java 881 2007-02-12 07:54:31Z hengels $
003: * (c) Copyright 2004 con:cern development team.
004: *
005: * This file is part of con:cern (http://concern.sf.net).
006: *
007: * con:cern is free software; you can redistribute it and/or modify
008: * it under the terms of the GNU Lesser General Public License
009: * as published by the Free Software Foundation; either version 2.1
010: * of the License, or (at your option) any later version.
011: *
012: * Please see COPYING for the complete licence.
013: */
014: package org.concern;
015:
016: import java.util.List;
017: import java.util.Map;
018:
019: /**
020: * The controller interface is the runtime client interface of con:cern. An implementation is responsible for
021: * controlling the process flow and invoking the activities. It provides access to the log and the current state
022: * information of the subjects in process.
023: * <p/>
024: * Methods, that import the transactional context:
025: * o createSubject
026: * o lockSubject
027: * o destroySubject
028: * o getSubjects(..)
029: * o complete
030: * o notify
031: * o getLog
032: * o getArchive
033: * o matchPrecondition
034: * o matchPostcondition
035: *
036: * @author hengels[at]mercatis[dot]de
037: * @version $Revision: 881 $
038: */
039: public interface Controller {
040: public static final int STATE_RUNNING = 0;
041: public static final int STATE_STALLED = 1;
042: public static final int STATE_SUSPENDED = 2;
043: public static final int STATE_DESTROYED = 3;
044:
045: /**
046: * A process is identified by a unique name. A separate controller instance is required for every process.
047: * @return the name of the process that is controlled by this controller
048: */
049: String getProcessName();
050:
051: /**
052: * Return the process description.
053: * @return the process description
054: */
055: org.concern.model.Process getProcess();
056:
057: /**
058: * Create a new subject in the process. The userValue is used by both, the activities and the client to identify
059: * the subject. Candidates are a primary key, a distinguished name, a filename, whatever .. depending on the
060: * datastore, that holds the subject's business information.
061: *
062: * @param userValue identifies the subject
063: * @return an internal id
064: * @throws org.concern.SubjectCreationException
065: */
066: Integer createSubject(String userValue)
067: throws org.concern.SubjectCreationException,
068: ControllerException;
069:
070: /**
071: * Determines if {@link #createSubject(String)} has already been called
072: * for the specified <code>userValue</code>.
073: *
074: * @param userValue identifies the subject
075: * @return <code>true</code> if <code>createSubject(...)</code> has already
076: * been called for the specified <code>userValue</code>.
077: * @throws ControllerException
078: */
079: boolean isKnownSubject(String userValue) throws ControllerException;
080:
081: /**
082: * Retrieve a list of all subjects, that are currently in the process.
083: * @return a list with the userValues of all subjects
084: * @param state one of STATE_RUNNING, STATE_IDLE, STATE_DESTROYED
085: */
086: List<String> getSubjects(int state) throws ControllerException;
087:
088: /**
089: * Tell the controller, that a subjects has changed. This method has to be called in order to tell the controller,
090: * that the particular subject should be examined for further execution.
091: * @param userValue identifies the subject
092: */
093: void announceSubject(String userValue)
094: throws UnknownSubjectException, ControllerException;
095:
096: /**
097: *
098: * @param userValue identifies the subject
099: * @param duration in seconds
100: */
101: void scheduleAnnouncement(String userValue, long duration)
102: throws UnknownSubjectException, ControllerException;
103:
104: /**
105: * Append a message to the protocol of the specified subject.
106: * @param log the record to be logged
107: */
108: void log(Log log) throws UnknownSubjectException,
109: ControllerException;
110:
111: /**
112: * Return a list of names of the asynchronous activities, for which the subject is enlisted
113: * @param userValue identifies the subject
114: * @return the enlistments
115: * @throws org.concern.UnknownSubjectException
116: */
117: List<String> getEnlistments(String userValue)
118: throws org.concern.UnknownSubjectException,
119: ControllerException;
120:
121: /**
122: * Return a list of names of the none optional asynchronous activities, for which the subject is enlisted
123: * @param userValue identifies the subject
124: * @return the tasks
125: * @throws org.concern.UnknownSubjectException
126: */
127: List<String> getTasks(String userValue)
128: throws org.concern.UnknownSubjectException,
129: ControllerException;
130:
131: /**
132: * Return a list of names of the optional asynchronous activities, for which the subject is enlisted
133: * @param userValue identifies the subject
134: * @return the tasks
135: * @throws org.concern.UnknownSubjectException
136: */
137: List<String> getOptions(String userValue)
138: throws org.concern.UnknownSubjectException,
139: ControllerException;
140:
141: /**
142: * Get the ids of the subjects, that are enlisted for the specified asynchronous actvity.
143: * @param activity the activity name
144: * @return a list of subject ids
145: */
146: List<String> getSubjects(String activity)
147: throws ControllerException;
148:
149: /**
150: * The controller logs every successful or unsuccessful execution of an activity as well as the creation, destroyal
151: * and stall of subjects.
152: * @param userValue identifies the subject
153: * @return a list of org.concern.Log records
154: * @throws org.concern.UnknownSubjectException
155: */
156: List<Log> getLog(String userValue)
157: throws org.concern.UnknownSubjectException,
158: ControllerException;
159:
160: /**
161: * Subjects, that have reached been destroyed are removed from the process. Their log is archived.
162: * @param userValue identifies the subject
163: * @return a list of org.concern.Log records
164: * @throws org.concern.ControllerException
165: */
166: List<Log> getArchive(String userValue) throws ControllerException,
167: UnknownSubjectException;
168:
169: /**
170: * Complete an asynchronous activtiy. The controller checks the postcondition an logs the successful completion
171: * of the activity.
172: * @param userValue identifies the subject
173: * @param activityName the activity
174: * @return true if the postcondition is matching, false otherwise
175: * @throws org.concern.UnknownSubjectException
176: * @throws org.concern.ControllerException
177: */
178: boolean complete(String userValue, String activityName)
179: throws org.concern.UnknownSubjectException,
180: org.concern.ControllerException;
181:
182: /**
183: * Complete an asynchronous activtiy. The controller checks the postcondition and logs the successful completion
184: * of the activity. If the <code>logAnnotations</code> property is not
185: * <code>null</code>, then those annotations will be stored in the log
186: * entry for the completed activity.
187: *
188: * @param userValue identifies the subject
189: * @param activityName the activity
190: * @param logAnnotations may contain client specific information to be stored with the log entry that will be created for this activity. This parameter may also be <code>null</code>.
191: * @return true if the postcondition is matching, false otherwise
192: * @throws org.concern.UnknownSubjectException
193: * @throws org.concern.ControllerException
194: */
195: boolean complete(String userValue, String activityName,
196: Map<String, String> logAnnotations)
197: throws org.concern.UnknownSubjectException,
198: org.concern.ControllerException;
199:
200: /**
201: * Check if the subject matches the specified condition.
202: * @param userValue identifies the subject
203: * @param conditionName the activity
204: * @return match
205: * @throws org.concern.UnknownSubjectException
206: * @throws org.concern.ControllerException
207: */
208: Boolean matchCondition(String userValue, String conditionName)
209: throws org.concern.UnknownSubjectException,
210: org.concern.ControllerException;
211:
212: /**
213: * Check if the subject matches the precondition of the specified activity.
214: * @param userValue identifies the subject
215: * @param activityName the activity
216: * @return match
217: * @throws org.concern.UnknownSubjectException
218: * @throws org.concern.ControllerException
219: */
220: boolean matchPrecondition(String userValue, String activityName)
221: throws org.concern.UnknownSubjectException,
222: org.concern.ControllerException;
223:
224: /**
225: * Check if the subject matches the postcondition of the specified activity.
226: * @param userValue identifies the subject
227: * @param activityName the activity
228: * @return match
229: * @throws org.concern.UnknownSubjectException
230: * @throws org.concern.ControllerException
231: */
232: boolean matchPostcondition(String userValue, String activityName)
233: throws org.concern.UnknownSubjectException,
234: org.concern.ControllerException;
235:
236: /**
237: * Process the specified subject immediately. When this method returns, all actions are performed.
238: * @param userValue identifies the subject
239: * @throws org.concern.UnknownSubjectException
240: * @throws org.concern.ControllerException
241: */
242: void process(String userValue)
243: throws org.concern.UnknownSubjectException,
244: org.concern.ControllerException;
245:
246: /**
247: * Mark the subject destroyed. When it is processed next, it will be moved to the archive.
248: * @param userValue identifies the subject
249: * @throws UnknownSubjectException
250: * @throws ControllerException
251: */
252: void destroySubject(String userValue)
253: throws UnknownSubjectException, ControllerException;
254:
255: /**
256: * Restore the subject from the archive into the pool of running instances.
257: * @param userValue identifies the subject
258: * @throws UnknownSubjectException
259: * @throws ControllerException
260: */
261: void reviveSubject(String userValue)
262: throws UnknownSubjectException, ControllerException;
263:
264: /**
265: * Notify the controller that an event has occured.
266: * @param userValue
267: * @param eventName
268: * @return
269: * @throws UnknownSubjectException
270: */
271: boolean notify(String userValue, String eventName)
272: throws UnknownSubjectException, ControllerException;
273:
274: /**
275: * Notify the controller that an event has occured.
276: * If the <code>logAnnotations</code> property is not
277: * <code>null</code>, then those annotations will be stored in the log
278: * entry for the notification.
279: *
280: * @param userValue
281: * @param eventName
282: * @param logAnnotations may contain client specific information to be stored with the log entry that will be created for this notification. This parameter may also be <code>null</code>.
283: * @return
284: * @throws UnknownSubjectException
285: */
286: boolean notify(String userValue, String eventName,
287: Map<String, String> logAnnotations)
288: throws UnknownSubjectException, ControllerException;
289:
290: /**
291: * Write-lock the specified subject for the duration of the current transaction.
292: * @param userValue
293: * @throws UnknownSubjectException
294: * @throws ControllerException
295: */
296: void lockSubject(String userValue) throws UnknownSubjectException,
297: ControllerException;
298:
299: boolean isForwardPossible(String userValue, String activityName)
300: throws UnknownSubjectException, ControllerException;
301:
302: void forward(String userValue, String activityName)
303: throws UnknownSubjectException, ControllerException;
304:
305: void forward(String userValue, String activityName,
306: Map<String, String> logAnnotations)
307: throws UnknownSubjectException, ControllerException;
308:
309: boolean isBackwardPossible(String userValue, String activityName)
310: throws UnknownSubjectException, ControllerException;
311:
312: void backward(String userValue, String activityName)
313: throws UnknownSubjectException, ControllerException;
314:
315: void backward(String userValue, String activityName,
316: Map<String, String> logAnnotations)
317: throws UnknownSubjectException, ControllerException;
318:
319: void reset(String userValue, String activityName)
320: throws UnknownSubjectException, ControllerException;
321:
322: void suspendSubject(String userValue)
323: throws UnknownSubjectException, ControllerException;
324:
325: void resumeSubject(String userValue)
326: throws UnknownSubjectException, ControllerException;
327:
328: /**
329: * Start the controller.
330: */
331: void start();
332:
333: /**
334: * Free all resources.
335: * @throws ControllerException
336: */
337: void stop() throws ControllerException;
338:
339: /**
340: * Reread the parameters from the parameter resolver
341: */
342: void reload();
343: }
|