001: /*--
002:
003: Copyright (C) 2002 Anthony Eden, Adrian Price.
004: All rights reserved.
005:
006: Redistribution and use in source and binary forms, with or without
007: modification, are permitted provided that the following conditions
008: are met:
009:
010: 1. Redistributions of source code must retain the above copyright
011: notice, this list of conditions, and the following disclaimer.
012:
013: 2. Redistributions in binary form must reproduce the above copyright
014: notice, this list of conditions, and the disclaimer that follows
015: these conditions in the documentation and/or other materials
016: provided with the distribution.
017:
018: 3. The names "OBE" and "Open Business Engine" must not be used to
019: endorse or promote products derived from this software without prior
020: written permission. For written permission, please contact
021: me@anthonyeden.com.
022:
023: 4. Products derived from this software may not be called "OBE" or
024: "Open Business Engine", nor may "OBE" or "Open Business Engine"
025: appear in their name, without prior written permission from
026: Anthony Eden (me@anthonyeden.com).
027:
028: In addition, I request (but do not require) that you include in the
029: end-user documentation provided with the redistribution and/or in the
030: software itself an acknowledgement equivalent to the following:
031: "This product includes software developed by
032: Anthony Eden (http://www.anthonyeden.com/)."
033:
034: THIS SOFTWARE IS PROVIDED ``AS IS'' AND ANY EXPRESSED OR IMPLIED
035: WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES
036: OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
037: DISCLAIMED. IN NO EVENT SHALL THE AUTHOR(S) BE LIABLE FOR ANY DIRECT,
038: INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES
039: (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR
040: SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
041: HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT,
042: STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING
043: IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
044: POSSIBILITY OF SUCH DAMAGE.
045:
046: For more information on OBE, please see <http://obe.sourceforge.net/>.
047:
048: */
049:
050: package org.enhydra.shark.api.client.wfmc.wapi;
051:
052: /**
053: * Enables client applications to connect to and interact with a workflow engine.
054: * <p>
055: * This interface is based on the WfMC's Interface 2 Client WAPI specification. Some of
056: * the methods have been modified from the original specification to fit within the normal
057: * design of Java applications. For instance, the WfMC specification functions always
058: * return an error object (even for success) and uses out parameters to return values.
059: * This interface returns the value and throws an exception when an error occurs. If no
060: * error occurs then an exception is not thrown. The C WAPI uses query handles and
061: * iterator functions to retrieve collections; this Java binding uses {@link WMIterator}.
062: * <p>
063: * For the adoption in Shark, we have changed most of the methods signatures and switched
064: * almost all interfaces into classes, however original intention and functionality
065: * remained. We defined additional method to get immediate access to ProcessDefinition by
066: * its name.
067: *
068: * @author Anthony Eden
069: * @author Adrian Price
070: */
071: public interface WAPI {
072: /**
073: * Connects to a workflow service.
074: *
075: * @param connectInfo The connection info. In OBE, pass <code>null</code> to skip the
076: * JAAS login and retain the current security identity (if any).
077: * @throws Exception Workflow client exception.
078: */
079: WMSessionHandle connect(WMConnectInfo connectInfo) throws Exception;
080:
081: /**
082: * Disconnects from the workflow service.
083: *
084: * @throws Exception Workflow client exception.
085: */
086: void disconnect(WMSessionHandle shandle) throws Exception;
087:
088: /**
089: * Opens a list of process definitions. The items in the list can be retrieved
090: * sequentially in a typesafe way by calling the iterator's <code>tsNext()</code>
091: * method.
092: *
093: * @param filter The filter or null.
094: * @param countFlag True to return count value.
095: * @return An iterator to access the {@link WMProcessDefinition} objects.
096: * @throws Exception Workflow client exception.
097: */
098: WMProcessDefinitionIterator listProcessDefinitions(
099: WMSessionHandle shandle, WMFilter filter, boolean countFlag)
100: throws Exception;
101:
102: /**
103: * Opens a list of process definition states. The items in the state list can be
104: * retrieved sequentially in a typesafe way by calling the iterator's
105: * <code>tsNext()</code> method.
106: *
107: * @param procDefId The unique process definition ID.
108: * @param filter The filter or null.
109: * @param countFlag True to return count value.
110: * @return An iterator to access the {@link WMProcessDefinitionState} objects.
111: * @throws Exception Workflow client exception.
112: */
113: WMProcessDefinitionStateIterator listProcessDefinitionStates(
114: WMSessionHandle shandle, String procDefId, WMFilter filter,
115: boolean countFlag) throws Exception;
116:
117: /**
118: * Changes the process definition state.
119: *
120: * @param procDefId The process definition id.
121: * @param newState The new process definition state.
122: * @throws Exception Workflow client exception.
123: */
124: void changeProcessDefinitionState(WMSessionHandle shandle,
125: String procDefId, WMProcessDefinitionState newState)
126: throws Exception;
127:
128: /**
129: * Creates a new process instance for the given process definition.
130: *
131: * @param procDefId The process definition id.
132: * @param procInstName The name of the process instance.
133: * @return The process instance id.
134: * @throws Exception Workflow client exception.
135: */
136: String createProcessInstance(WMSessionHandle shandle,
137: String procDefId, String procInstName) throws Exception;
138:
139: /**
140: * Starts a process instance. The process instance id is retrieved from a prior call to
141: * <code>createProcessInstance()</code>
142: *
143: * @param procInstId The process instance id retrieved in a prior call to
144: * <code>createProcessInstance()</code>.
145: * @return The new process instance id (which may be the same as the old).
146: * @throws Exception Workflow client exception.
147: */
148: String startProcess(WMSessionHandle shandle, String procInstId)
149: throws Exception;
150:
151: /**
152: * Terminates a process instance.
153: *
154: * @param procInstId The process instance id.
155: * @throws Exception Workflow client exception.
156: */
157: void terminateProcessInstance(WMSessionHandle shandle,
158: String procInstId) throws Exception;
159:
160: /**
161: * Opens a list of process instance states. The items in the state list can be
162: * retrieved sequentially in a typesafe way by calling the iterator's
163: * <code>tsNext()</code> method.
164: *
165: * @param procInstId The unique process instance ID.
166: * @param filter The filter or null.
167: * @param countFlag True to return count value.
168: * @return An iterator to access the {@link WMProcessInstanceState} objects.
169: * @throws Exception Workflow client exception.
170: */
171: WMProcessInstanceStateIterator listProcessInstanceStates(
172: WMSessionHandle shandle, String procInstId,
173: WMFilter filter, boolean countFlag) throws Exception;
174:
175: /**
176: * Changes the state of a process instance.
177: *
178: * @param procInstId The process instance id.
179: * @param newState The new process instance state.
180: * @throws Exception Workflow client exception.
181: */
182: void changeProcessInstanceState(WMSessionHandle shandle,
183: String procInstId, WMProcessInstanceState newState)
184: throws Exception;
185:
186: /**
187: * Opens a list of process instance attributes. The items in the attribute list can be
188: * retrieved sequentially in a typesafe way by calling the iterator's
189: * <code>tsNext()</code> method.
190: *
191: * @param filter The filter or null.
192: * @param countFlag True to return count value.
193: * @return An iterator to access the {@link WMAttribute} objects.
194: * @throws Exception Workflow client exception.
195: */
196: WMAttributeIterator listProcessInstanceAttributes(
197: WMSessionHandle shandle, String procInstId,
198: WMFilter filter, boolean countFlag) throws Exception;
199:
200: /**
201: * Gets the specified process instance attribute value.
202: *
203: * @param procInstId The process instance id.
204: * @param attrName The attribute name.
205: * @return The attribute.
206: * @throws Exception Workflow client exception.
207: */
208: WMAttribute getProcessInstanceAttributeValue(
209: WMSessionHandle shandle, String procInstId, String attrName)
210: throws Exception;
211:
212: /**
213: * Sets the specified process instance attribute value.
214: *
215: * @param procInstId The process instance id.
216: * @param attrName The attribute name.
217: * @param attrValue The attribute value.
218: * @throws Exception Workflow client exception.
219: */
220: void assignProcessInstanceAttribute(WMSessionHandle shandle,
221: String procInstId, String attrName, Object attrValue)
222: throws Exception;
223:
224: /**
225: * Opens a list of process instance states. The items in the state list can be
226: * retrieved sequentially in a typesafe way by calling the iterator's
227: * <code>tsNext()</code> method.
228: *
229: * @param procInstId The process instance id.
230: * @param actInstId The activity instance id.
231: * @param filter The filter or null.
232: * @param countFlag True to return count value.
233: * @return An iterator to access the {@link WMActivityInstanceState} objects.
234: * @throws Exception Workflow client exception.
235: */
236: WMActivityInstanceStateIterator listActivityInstanceStates(
237: WMSessionHandle shandle, String procInstId,
238: String actInstId, WMFilter filter, boolean countFlag)
239: throws Exception;
240:
241: /**
242: * Changes the state of an activity instance.
243: *
244: * @param procInstId The process instance id.
245: * @param actInstId The activity instance id.
246: * @param newState The new activity instance state.
247: * @throws Exception Workflow client exception.
248: */
249: void changeActivityInstanceState(WMSessionHandle shandle,
250: String procInstId, String actInstId,
251: WMActivityInstanceState newState) throws Exception;
252:
253: /**
254: * Opens a list of activity instance attributes. The items in the attribute list can be
255: * retrieved sequentially in a typesafe way by calling the iterator's
256: * <code>tsNext()</code> method.
257: *
258: * @param procInstId The process instance id.
259: * @param actInstId The activity instance id.
260: * @param filter The filter or null.
261: * @param countFlag True to return count value.
262: * @return An iterator to access the {@link WMAttribute} objects.
263: * @throws Exception Workflow client exception.
264: */
265: WMAttributeIterator listActivityInstanceAttributes(
266: WMSessionHandle shandle, String procInstId,
267: String actInstId, WMFilter filter, boolean countFlag)
268: throws Exception;
269:
270: /**
271: * Gets the value of an activity instance attribute.
272: *
273: * @param procInstId The process instance id.
274: * @param actInstId The activity instance id.
275: * @param attrName The attribute name.
276: * @return The attribute.
277: * @throws Exception Workflow client exception.
278: */
279: WMAttribute getActivityInstanceAttributeValue(
280: WMSessionHandle shandle, String procInstId,
281: String actInstId, String attrName) throws Exception;
282:
283: /**
284: * Sets the value of an activity instance attribute.
285: *
286: * @param procInstId The process instance id.
287: * @param actInstId The activity instance id.
288: * @param attrName The attribute name.
289: * @param attrValue The attribute value.
290: * @throws Exception Workflow client exception.
291: */
292: void assignActivityInstanceAttribute(WMSessionHandle shandle,
293: String procInstId, String actInstId, String attrName,
294: Object attrValue) throws Exception;
295:
296: /**
297: * Opens a list of process instances. The items in the list can be retrieved
298: * sequentially in a typesafe way by calling the iterator's <code>tsNext()</code>
299: * method.
300: *
301: * @param filter The filter or null.
302: * @param countFlag True to return count value.
303: * @return An iterator to access the {@link WMProcessInstance} objects.
304: * @throws Exception Workflow client exception.
305: */
306: WMProcessInstanceIterator listProcessInstances(
307: WMSessionHandle shandle, WMFilter filter, boolean countFlag)
308: throws Exception;
309:
310: /**
311: * Retrieves a process instance.
312: *
313: * @param procInstId The process instance id.
314: * @return The process instance.
315: * @throws Exception Workflow client exception.
316: */
317: WMProcessInstance getProcessInstance(WMSessionHandle shandle,
318: String procInstId) throws Exception;
319:
320: /**
321: * Opens a list of activity instances. The items in the list can be retrieved
322: * sequentially in a typesafe way by calling the iterator's <code>tsNext()</code>
323: * method.
324: *
325: * @param filter The filter or null.
326: * @param countFlag True to return count value.
327: * @return An iterator to access the {@link WMActivityInstance} objects.
328: * @throws Exception Workflow client exception.
329: */
330: WMActivityInstanceIterator listActivityInstances(
331: WMSessionHandle shandle, WMFilter filter, boolean countFlag)
332: throws Exception;
333:
334: /**
335: * Retrieves an activity instance.
336: *
337: * @param procInstId The process instance id.
338: * @param actInstId The activity instance id.
339: * @return The activity instance.
340: * @throws Exception Workflow client exception.
341: */
342: WMActivityInstance getActivityInstance(WMSessionHandle shandle,
343: String procInstId, String actInstId) throws Exception;
344:
345: /**
346: * Opens a worklist. The items in the list can be retrieved sequentially using the
347: * iterator's <code>tsNext()</code> method.
348: *
349: * @param filter The filter or null.
350: * @param countFlag True to return count value.
351: * @return An iterator to access the {@link WMWorkItem} objects.
352: * @throws Exception Workflow client exception.
353: */
354: WMWorkItemIterator listWorkItems(WMSessionHandle shandle,
355: WMFilter filter, boolean countFlag) throws Exception;
356:
357: /**
358: * Retrieves a work item.
359: *
360: * @param procInstId The process instance id.
361: * @param workItemId The work item id.
362: * @return The work item.
363: * @throws Exception Workflow client exception.
364: */
365: WMWorkItem getWorkItem(WMSessionHandle shandle, String procInstId,
366: String workItemId) throws Exception;
367:
368: /**
369: * Completes the specified work item.
370: *
371: * @param procInstId The process instance id.
372: * @param workItemId The work item id.
373: * @throws Exception Workflow client exception.
374: */
375: void completeWorkItem(WMSessionHandle shandle, String procInstId,
376: String workItemId) throws Exception;
377:
378: /**
379: * Opens a list of work item states. The items in the work item states list can be
380: * retrieved sequentially in a typesafe way by calling the iterator's
381: * <code>tsNext()</code> method. <p/> N.B. This function is poorly documented in the
382: * WfMC specification, which contains several 'copy/paste' errors. <p/> N.B. The
383: * signature of this method differs from that described in the WAPI2 specification, in
384: * that it has a procInstId parameter. This is because the specification's definition
385: * for this function is clearly in error, having been copied badly from that for
386: * WMOpenProcessDefinitionStatesList. The other WAPI functions that refer to work items
387: * invariably require the procInstId parameter.
388: *
389: * @param procInstId The process instance id.
390: * @param workItemId The process instance id.
391: * @param filter The filter or null.
392: * @param countFlag True to return count value.
393: * @return An iterator to access the {@link WMWorkItemState} objects.
394: * @throws Exception Workflow client exception.
395: */
396: WMWorkItemStateIterator listWorkItemStates(WMSessionHandle shandle,
397: String procInstId, String workItemId, WMFilter filter,
398: boolean countFlag) throws Exception;
399:
400: /**
401: * Changes the state of a work item.
402: * <em>N.B. The signature of this method differs from that described in the
403: * WAPI2 specification, in that it has a <code>procInstId</code> parameter.
404: * This is because the specification's definition for this function is
405: * clearly in error, having been badly copied from that for
406: * <code>WMChangeDefinitionState</code>. The other WAPI functions that refer
407: * to work items invariably require the <code>procInstId</code> parameter.
408: * </em>
409: *
410: * @param procInstId The process instance id.
411: * @param workItemId The work item id.
412: * @param newState The new work item state.
413: * @throws Exception Workflow client exception.
414: */
415: void changeWorkItemState(WMSessionHandle shandle,
416: String procInstId, String workItemId,
417: WMWorkItemState newState) throws Exception;
418:
419: /**
420: * Reassigns a work item to another user.
421: *
422: * @param sourceUser The current user.
423: * @param targetUser The new user.
424: * @param procInstId The process instance id.
425: * @param workItemId The work item id.
426: * @throws Exception Workflow client exception.
427: */
428: void reassignWorkItem(WMSessionHandle shandle, String sourceUser,
429: String targetUser, String procInstId, String workItemId)
430: throws Exception;
431:
432: /**
433: * Opens a list of work item attributes. The items in the attribute list can be
434: * retrieved sequentially in a typesafe way by calling the iterator's
435: * <code>tsNext()</code> method.
436: *
437: * @param procInstId The process instance id.
438: * @param workItemId The work item id.
439: * @param filter The filter or null.
440: * @param countFlag True to return count value.
441: * @return An iterator to access the {@link WMAttribute} objects.
442: * @throws Exception Workflow client exception.
443: */
444: WMAttributeIterator listWorkItemAttributes(WMSessionHandle shandle,
445: String procInstId, String workItemId, WMFilter filter,
446: boolean countFlag) throws Exception;
447:
448: /**
449: * Retrieves the value of a work item attribute.
450: *
451: * @param procInstId The process instance id.
452: * @param workItemId The work item id.
453: * @param attrName The attribute name.
454: * @return The attribute.
455: * @throws Exception Workflow client exception.
456: */
457: WMAttribute getWorkItemAttributeValue(WMSessionHandle shandle,
458: String procInstId, String workItemId, String attrName)
459: throws Exception;
460:
461: /**
462: * Sets the value of a work item attribute.
463: *
464: * @param procInstId The process instance id.
465: * @param workItemId The work item id.
466: * @param attrName The attribute name.
467: * @param attrValue The attribute value.
468: * @throws Exception Workflow client exception.
469: */
470: void assignWorkItemAttribute(WMSessionHandle shandle,
471: String procInstId, String workItemId, String attrName,
472: Object attrValue) throws Exception;
473:
474: /**
475: * Changes the state of selected process instances.
476: *
477: * @param procDefId The ID of the process definition for which instances are to be
478: * changed.
479: * @param filter A filter specification; can be <code>null</code>.
480: * @param newState The new state to apply.
481: * @throws Exception Workflow client exception.
482: */
483: void changeProcessInstancesState(WMSessionHandle shandle,
484: String procDefId, WMFilter filter,
485: WMProcessInstanceState newState) throws Exception;
486:
487: /**
488: * Changes the state of selected activity instances.
489: *
490: * @param procDefId The ID of the process definition for which activity instances are
491: * to be changed.
492: * @param actDefId The ID of the activity definition for which instances are to be
493: * changed.
494: * @param filter A filter specification; can be <code>null</code>.
495: * @param newState The new state to apply.
496: * @throws Exception Workflow client exception.
497: */
498: void changeActivityInstancesState(WMSessionHandle shandle,
499: String procDefId, String actDefId, WMFilter filter,
500: WMActivityInstanceState newState) throws Exception;
501:
502: /**
503: * Terminates a group of process instances.
504: *
505: * @param procDefId The ID of the process definition for which instances are to be
506: * terminated.
507: * @param filter A filter specification; can be <code>null</code>.
508: * @throws Exception Workflow client exception.
509: */
510: void terminateProcessInstances(WMSessionHandle shandle,
511: String procDefId, WMFilter filter) throws Exception;
512:
513: /**
514: * Assigns an attribute value for a group of process instances.
515: *
516: * @param procDefId The ID of the process definition for which instance attributes are
517: * to be assigned.
518: * @param filter A filter specification; can be <code>null</code>.
519: * @param attrName The attribute name.
520: * @param attrValue The attribute value.
521: * @throws Exception Workflow client exception.
522: */
523: void assignProcessInstancesAttribute(WMSessionHandle shandle,
524: String procDefId, WMFilter filter, String attrName,
525: Object attrValue) throws Exception;
526:
527: /**
528: * Assigns an attribute value for a group of process instances.
529: *
530: * @param procDefId The ID of the process definition for which activity instance
531: * attributes are to be assigned.
532: * @param actDefId The ID of the activity definition for which instance attributes are
533: * to be assigned.
534: * @param filter A filter specification; can be <code>null</code>.
535: * @param attrName The attribute name.
536: * @param attrValue The attribute value.
537: * @throws Exception Workflow client exception.
538: */
539: void assignActivityInstancesAttribute(WMSessionHandle shandle,
540: String procDefId, String actDefId, WMFilter filter,
541: String attrName, Object attrValue) throws Exception;
542:
543: /**
544: * Aborts a group of process instances.
545: *
546: * @param procDefId The ID of the process definition for which instances are to be
547: * aborted.
548: * @param filter A filter specification; can be <code>null</code>.
549: * @throws Exception Workflow client exception.
550: */
551: void abortProcessInstances(WMSessionHandle shandle,
552: String procDefId, WMFilter filter) throws Exception;
553:
554: /**
555: * Aborts a process instance.
556: *
557: * @param procInstId The ID of the process instance to abort.
558: * @throws Exception Workflow client exception.
559: */
560: void abortProcessInstance(WMSessionHandle shandle, String procInstId)
561: throws Exception;
562:
563: /**
564: * Retrieves a process definition.
565: *
566: * @param procDefName The process definition unique name.
567: * @return The process definition.
568: * @throws Exception Workflow client exception.
569: */
570: WMProcessDefinition getProcessDefinition(WMSessionHandle shandle,
571: String procDefName) throws Exception;
572:
573: }
|