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.wfmc.wapi;
051:
052: /**
053: * Enables client applications to connect to and interact with a workflow
054: * engine.
055: * <p/>
056: * This interface is based on the WfMC's Interface 2 Client WAPI
057: * specification. Some of the methods have been modified from the original
058: * specification to fit within the normal design of Java applications. For
059: * instance, the WfMC specification functions always return an error object
060: * (even for success) and uses out parameters to return values. This
061: * interface returns the value and throws an exception when an error occurs.
062: * If no error occurs then an exception is not thrown. The C WAPI uses
063: * query handles and iterator functions to retrieve collections; this Java
064: * binding uses {@link WMIterator}.
065: *
066: * @author Anthony Eden
067: * @author Adrian Price
068: */
069: public interface WAPI {
070: /**
071: * Connects to a workflow service.
072: *
073: * @param connectInfo The connection info. In OBE, pass <code>null</code>
074: * to skip the JAAS login and retain the current security identity (if any).
075: * @throws WMWorkflowException Workflow client exception.
076: */
077: void connect(WMConnectInfo connectInfo) throws WMWorkflowException;
078:
079: /**
080: * Disconnects from the workflow service.
081: *
082: * @throws WMWorkflowException Workflow client exception.
083: */
084: void disconnect() throws WMWorkflowException;
085:
086: /**
087: * Opens a list of process definitions. The items in the list can be
088: * retrieved sequentially in a typesafe way by calling the iterator's
089: * <code>tsNext()</code> method.
090: *
091: * @param filter The filter or null.
092: * @param countFlag True to return count value.
093: * @return An iterator to access the {@link WMProcessDefinition} objects.
094: * @throws WMWorkflowException Workflow client exception.
095: */
096: WMProcessDefinitionIterator listProcessDefinitions(WMFilter filter,
097: boolean countFlag) throws WMWorkflowException;
098:
099: /**
100: * Opens a list of process definition states. The items in the state list
101: * can be retrieved sequentially in a typesafe way by calling the iterator's
102: * <code>tsNext()</code> method.
103: *
104: * @param procDefId The unique process definition ID.
105: * @param filter The filter or null.
106: * @param countFlag True to return count value.
107: * @return An iterator to access the {@link WMProcessDefinitionState}
108: * objects.
109: * @throws WMWorkflowException Workflow client exception.
110: */
111: WMProcessDefinitionStateIterator listProcessDefinitionStates(
112: String procDefId, WMFilter filter, boolean countFlag)
113: throws WMWorkflowException;
114:
115: /**
116: * Changes the process definition state.
117: *
118: * @param procDefId The process definition id.
119: * @param newState The new process definition state.
120: * @throws WMWorkflowException Workflow client exception.
121: */
122: void changeProcessDefinitionState(String procDefId,
123: WMProcessDefinitionState newState)
124: throws WMWorkflowException;
125:
126: /**
127: * Creates a new process instance for the given process definition.
128: *
129: * @param procDefId The process definition id.
130: * @param procInstName The name of the process instance.
131: * @return The process instance id.
132: * @throws WMWorkflowException Workflow client exception.
133: */
134: String createProcessInstance(String procDefId, String procInstName)
135: throws WMWorkflowException;
136:
137: /**
138: * Starts a process instance. The process instance id is retrieved
139: * from a prior call to <code>createProcessInstance()</code>
140: *
141: * @param procInstId The process instance id retrieved in a prior
142: * call to <code>createProcessInstance()</code>.
143: * @return The new process instance id (which may be the same as the old).
144: * @throws WMWorkflowException Workflow client exception.
145: */
146: String startProcess(String procInstId) throws WMWorkflowException;
147:
148: /**
149: * Terminates a process instance.
150: *
151: * @param procInstId The process instance id.
152: * @throws WMWorkflowException Workflow client exception.
153: */
154: void terminateProcessInstance(String procInstId)
155: throws WMWorkflowException;
156:
157: /**
158: * Opens a list of process instance states. The items in the state list
159: * can be retrieved sequentially in a typesafe way by calling the iterator's
160: * <code>tsNext()</code> method.
161: *
162: * @param procInstId The unique process instance ID.
163: * @param filter The filter or null.
164: * @param countFlag True to return count value.
165: * @return An iterator to access the {@link WMProcessInstanceState} objects.
166: * @throws WMWorkflowException Workflow client exception.
167: */
168: WMProcessInstanceStateIterator listProcessInstanceStates(
169: String procInstId, WMFilter filter, boolean countFlag)
170: throws WMWorkflowException;
171:
172: /**
173: * Changes the state of a process instance.
174: *
175: * @param procInstId The process instance id.
176: * @param newState The new process instance state.
177: * @throws WMWorkflowException Workflow client exception.
178: */
179: void changeProcessInstanceState(String procInstId,
180: WMProcessInstanceState newState) throws WMWorkflowException;
181:
182: /**
183: * Opens a list of process instance attributes. The items in the
184: * attribute list can be retrieved sequentially in a typesafe way by calling
185: * the iterator's <code>tsNext()</code> method.
186: *
187: * @param filter The filter or null.
188: * @param countFlag True to return count value.
189: * @return An iterator to access the {@link WMAttribute} objects.
190: * @throws WMWorkflowException Workflow client exception.
191: */
192: WMAttributeIterator listProcessInstanceAttributes(
193: String procInstId, WMFilter filter, boolean countFlag)
194: throws WMWorkflowException;
195:
196: /**
197: * Gets the specified process instance attribute value.
198: *
199: * @param procInstId The process instance id.
200: * @param attrName The attribute name.
201: * @return The attribute.
202: * @throws WMWorkflowException Workflow client exception.
203: */
204: WMAttribute getProcessInstanceAttributeValue(String procInstId,
205: String attrName) throws WMWorkflowException;
206:
207: /**
208: * Sets the specified process instance attribute value.
209: *
210: * @param procInstId The process instance id.
211: * @param attrName The attribute name.
212: * @param attrValue The attribute value.
213: * @throws WMWorkflowException Workflow client exception.
214: */
215: void assignProcessInstanceAttribute(String procInstId,
216: String attrName, Object attrValue)
217: throws WMWorkflowException;
218:
219: /**
220: * Opens a list of process instance states. The items in the state list
221: * can be retrieved sequentially in a typesafe way by calling the iterator's
222: * <code>tsNext()</code> method.
223: *
224: * @param procInstId The process instance id.
225: * @param actInstId The activity instance id.
226: * @param filter The filter or null.
227: * @param countFlag True to return count value.
228: * @return An iterator to access the {@link WMActivityInstanceState} objects.
229: * @throws WMWorkflowException Workflow client exception.
230: */
231: WMActivityInstanceStateIterator listActivityInstanceStates(
232: String procInstId, String actInstId, WMFilter filter,
233: boolean countFlag) throws WMWorkflowException;
234:
235: /**
236: * Changes the state of an activity instance.
237: *
238: * @param procInstId The process instance id.
239: * @param actInstId The activity instance id.
240: * @param newState The new activity instance state.
241: * @throws WMWorkflowException Workflow client exception.
242: */
243: void changeActivityInstanceState(String procInstId,
244: String actInstId, WMActivityInstanceState newState)
245: throws WMWorkflowException;
246:
247: /**
248: * Opens a list of activity instance attributes. The items in the
249: * attribute list can be retrieved sequentially in a typesafe way by calling
250: * the iterator's <code>tsNext()</code> method.
251: *
252: * @param procInstId The process instance id.
253: * @param actInstId The activity instance id.
254: * @param filter The filter or null.
255: * @param countFlag True to return count value.
256: * @return An iterator to access the {@link WMAttribute} objects.
257: * @throws WMWorkflowException Workflow client exception.
258: */
259: WMAttributeIterator listActivityInstanceAttributes(
260: String procInstId, String actInstId, WMFilter filter,
261: boolean countFlag) throws WMWorkflowException;
262:
263: /**
264: * Gets the value of an activity instance attribute.
265: *
266: * @param procInstId The process instance id.
267: * @param actInstId The activity instance id.
268: * @param attrName The attribute name.
269: * @return The attribute.
270: * @throws WMWorkflowException Workflow client exception.
271: */
272: WMAttribute getActivityInstanceAttributeValue(String procInstId,
273: String actInstId, String attrName)
274: throws WMWorkflowException;
275:
276: /**
277: * Sets the value of an activity instance attribute.
278: *
279: * @param procInstId The process instance id.
280: * @param actInstId The activity instance id.
281: * @param attrName The attribute name.
282: * @param attrValue The attribute value.
283: * @throws WMWorkflowException Workflow client exception.
284: */
285: void assignActivityInstanceAttribute(String procInstId,
286: String actInstId, String attrName, Object attrValue)
287: throws WMWorkflowException;
288:
289: /**
290: * Opens a list of process instances. The items in the list
291: * can be retrieved sequentially in a typesafe way by calling the iterator's
292: * <code>tsNext()</code> method.
293: *
294: * @param filter The filter or null.
295: * @param countFlag True to return count value.
296: * @return An iterator to access the {@link WMProcessInstance} objects.
297: * @throws WMWorkflowException Workflow client exception.
298: */
299: WMProcessInstanceIterator listProcessInstances(WMFilter filter,
300: boolean countFlag) throws WMWorkflowException;
301:
302: /**
303: * Retrieves a process instance.
304: *
305: * @param procInstId The process instance id.
306: * @return The process instance.
307: * @throws WMWorkflowException Workflow client exception.
308: */
309: WMProcessInstance getProcessInstance(String procInstId)
310: throws WMWorkflowException;
311:
312: /**
313: * Opens a list of activity instances. The items in the list can be
314: * retrieved sequentially in a typesafe way by calling the iterator's
315: * <code>tsNext()</code> method.
316: *
317: * @param filter The filter or null.
318: * @param countFlag True to return count value.
319: * @return An iterator to access the {@link WMActivityInstance} objects.
320: * @throws WMWorkflowException Workflow client exception.
321: */
322: WMActivityInstanceIterator listActivityInstances(WMFilter filter,
323: boolean countFlag) throws WMWorkflowException;
324:
325: /**
326: * Retrieves an activity instance.
327: *
328: * @param procInstId The process instance id.
329: * @param actInstId The activity instance id.
330: * @return The activity instance.
331: * @throws WMWorkflowException Workflow client exception.
332: */
333: WMActivityInstance getActivityInstance(String procInstId,
334: String actInstId) throws WMWorkflowException;
335:
336: /**
337: * Opens a worklist. The items in the list can be retrieved
338: * sequentially using the iterator's <code>tsNext()</code> method.
339: *
340: * @param filter The filter or null.
341: * @param countFlag True to return count value.
342: * @return An iterator to access the {@link WMWorkItem} objects.
343: * @throws WMWorkflowException Workflow client exception.
344: */
345: WMWorkItemIterator listWorkItems(WMFilter filter, boolean countFlag)
346: throws WMWorkflowException;
347:
348: /**
349: * Retrieves a work item.
350: *
351: * @param procInstId The process instance id.
352: * @param workItemId The work item id.
353: * @return The work item.
354: * @throws WMWorkflowException Workflow client exception.
355: */
356: WMWorkItem getWorkItem(String procInstId, String workItemId)
357: throws WMWorkflowException;
358:
359: /**
360: * Completes the specified work item.
361: *
362: * @param procInstId The process instance id.
363: * @param workItemId The work item id.
364: * @throws WMWorkflowException Workflow client exception.
365: */
366: void completeWorkItem(String procInstId, String workItemId)
367: throws WMWorkflowException;
368:
369: /**
370: * Opens a list of work item states. The items in the
371: * work item states list can be retrieved sequentially in a typesafe way by
372: * calling the iterator's <code>tsNext()</code> method.
373: * <p/>
374: * N.B. This function is poorly documented in the WfMC specification, which
375: * contains several 'copy/paste' errors.
376: * <p/>
377: * N.B. The signature of this method differs from that described in the
378: * WAPI2 specification, in that it has a procInstId parameter. This
379: * is because the specification's definition for this function is clearly in
380: * error, having been copied badly from that for
381: * WMOpenProcessDefinitionStatesList. The other WAPI functions that refer to
382: * work items invariably require the procInstId parameter.
383: *
384: * @param procInstId The process instance id.
385: * @param workItemId The process instance id.
386: * @param filter The filter or null.
387: * @param countFlag True to return count value.
388: * @return An iterator to access the {@link WMWorkItemState} objects.
389: * @throws WMWorkflowException Workflow client exception.
390: */
391: WMWorkItemStateIterator listWorkItemStates(String procInstId,
392: String workItemId, WMFilter filter, boolean countFlag)
393: throws WMWorkflowException;
394:
395: /**
396: * Changes the state of a work item.
397: * <em>N.B. The signature of this method differs from that described in the
398: * WAPI2 specification, in that it has a <code>procInstId</code> parameter.
399: * This is because the specification's definition for this function is
400: * clearly in error, having been badly copied from that for
401: * <code>WMChangeDefinitionState</code>. The other WAPI functions that refer
402: * to work items invariably require the <code>procInstId</code> parameter.
403: * </em>
404: *
405: * @param procInstId The process instance id.
406: * @param workItemId The work item id.
407: * @param newState The new work item state.
408: * @throws WMWorkflowException Workflow client exception.
409: */
410: void changeWorkItemState(String procInstId, String workItemId,
411: WMWorkItemState newState) throws WMWorkflowException;
412:
413: /**
414: * Reassigns a work item to another user.
415: *
416: * @param sourceUser The current user.
417: * @param targetUser The new user.
418: * @param procInstId The process instance id.
419: * @param workItemId The work item id.
420: * @throws WMWorkflowException Workflow client exception.
421: */
422: void reassignWorkItem(String sourceUser, String targetUser,
423: String procInstId, String workItemId)
424: throws WMWorkflowException;
425:
426: /**
427: * Opens a list of work item attributes. The items in the
428: * attribute list can be retrieved sequentially in a typesafe way by calling
429: * the iterator's <code>tsNext()</code> method.
430: *
431: * @param procInstId The process instance id.
432: * @param workItemId The work item id.
433: * @param filter The filter or null.
434: * @param countFlag True to return count value.
435: * @return An iterator to access the {@link WMAttribute} objects.
436: * @throws WMWorkflowException Workflow client exception.
437: */
438: WMAttributeIterator listWorkItemAttributes(String procInstId,
439: String workItemId, WMFilter filter, boolean countFlag)
440: throws WMWorkflowException;
441:
442: /**
443: * Retrieves the value of a work item attribute.
444: *
445: * @param procInstId The process instance id.
446: * @param workItemId The work item id.
447: * @param attrName The attribute name.
448: * @return The attribute.
449: * @throws WMWorkflowException Workflow client exception.
450: */
451: WMAttribute getWorkItemAttributeValue(String procInstId,
452: String workItemId, String attrName)
453: throws WMWorkflowException;
454:
455: /**
456: * Sets the value of a work item attribute.
457: *
458: * @param procInstId The process instance id.
459: * @param workItemId The work item id.
460: * @param attrName The attribute name.
461: * @param attrValue The attribute value.
462: * @throws WMWorkflowException Workflow client exception.
463: */
464: void assignWorkItemAttribute(String procInstId, String workItemId,
465: String attrName, Object attrValue)
466: throws WMWorkflowException;
467:
468: /**
469: * Changes the state of selected process instances.
470: *
471: * @param procDefId The ID of the process definition for which
472: * instances are to be changed.
473: * @param filter A filter specification; can be <code>null</code>.
474: * @param newState The new state to apply.
475: * @throws WMWorkflowException Workflow client exception.
476: */
477: void changeProcessInstancesState(String procDefId, WMFilter filter,
478: WMProcessInstanceState newState) throws WMWorkflowException;
479:
480: /**
481: * Changes the state of selected activity instances.
482: *
483: * @param procDefId The ID of the process definition for which
484: * activity instances are to be changed.
485: * @param actDefId The ID of the activity definition for which
486: * instances are to be changed.
487: * @param filter A filter specification; can be <code>null</code>.
488: * @param newState The new state to apply.
489: * @throws WMWorkflowException Workflow client exception.
490: */
491: void changeActivityInstancesState(String procDefId,
492: String actDefId, WMFilter filter,
493: WMActivityInstanceState newState)
494: throws WMWorkflowException;
495:
496: /**
497: * Terminates a group of process instances.
498: *
499: * @param procDefId The ID of the process definition for which
500: * instances are to be terminated.
501: * @param filter A filter specification; can be <code>null</code>.
502: * @throws WMWorkflowException Workflow client exception.
503: */
504: void terminateProcessInstances(String procDefId, WMFilter filter)
505: throws WMWorkflowException;
506:
507: /**
508: * Assigns an attribute value for a group of process instances.
509: *
510: * @param procDefId The ID of the process definition for which
511: * instance attributes are to be assigned.
512: * @param filter A filter specification; can be <code>null</code>.
513: * @param attrName The attribute name.
514: * @param attrValue The attribute value.
515: * @throws WMWorkflowException Workflow client exception.
516: */
517: void assignProcessInstancesAttribute(String procDefId,
518: WMFilter filter, String attrName, Object attrValue)
519: throws WMWorkflowException;
520:
521: /**
522: * Assigns an attribute value for a group of process instances.
523: *
524: * @param procDefId The ID of the process definition for which
525: * activity instance attributes are to be assigned.
526: * @param actDefId The ID of the activity definition for which
527: * instance attributes are to be assigned.
528: * @param filter A filter specification; can be <code>null</code>.
529: * @param attrName The attribute name.
530: * @param attrValue The attribute value.
531: * @throws WMWorkflowException Workflow client exception.
532: */
533: void assignActivityInstancesAttribute(String procDefId,
534: String actDefId, WMFilter filter, String attrName,
535: Object attrValue) throws WMWorkflowException;
536:
537: /**
538: * Aborts a group of process instances.
539: *
540: * @param procDefId The ID of the process definition for which
541: * instances are to be aborted.
542: * @param filter A filter specification; can be <code>null</code>.
543: * @throws WMWorkflowException Workflow client exception.
544: */
545: void abortProcessInstances(String procDefId, WMFilter filter)
546: throws WMWorkflowException;
547:
548: /**
549: * Aborts a process instance.
550: *
551: * @param procInstId The ID of the process instance to abort.
552: * @throws WMWorkflowException Workflow client exception.
553: */
554: void abortProcessInstance(String procInstId)
555: throws WMWorkflowException;
556:
557: /**
558: * Connects to the tool agent for a specified work item.
559: *
560: * @return tool agent handle.
561: * @throws WMWorkflowException
562: */
563: // int connectToolAgent(String procInstId, String workItemId)
564: // throws WMWorkflowException;
565: /**
566: *
567: * @throws WMWorkflowException
568: */
569: // void disconnectToolAgent(int toolAgentHandle) throws WMWorkflowException;
570: /**
571: * Invokes a client-side tool.
572: *
573: * @param toolAgentHandle
574: * @param appName The tag name of the tool.
575: * @param procInstId The ID of the associated process instance.
576: * @param workItemId The ID of the associated work item.
577: * @param parameters Parameters to pass to the tool.
578: * @param appMode Application mode, one of:
579: * @throws WMWorkflowException Workflow client exception.
580: */
581: void invokeApplication(int toolAgentHandle, String appName,
582: String procInstId, String workItemId, Object[] parameters,
583: int appMode) throws WMWorkflowException;
584:
585: /**
586: * Requests the status of an invoked tool.
587: *
588: * @param toolAgentHandle The tool handle, returned by the prior call
589: * to {@link #invokeApplication}.
590: * @param procInstId The ID of the associated process instance.
591: * @param workItemId The ID of the associated work item.
592: * @param status
593: * @return The status of specified tool.
594: * @throws WMWorkflowException Workflow client exception.
595: */
596: WMAttribute[] requestAppStatus(int toolAgentHandle,
597: String procInstId, String workItemId, int[] status)
598: throws WMWorkflowException;
599:
600: /**
601: * Terminates a running tool.
602: *
603: * @param toolAgentHandle
604: * @param procInstId The ID of the associated process instance.
605: * @param workItemId The ID of the associated work item.
606: * @throws WMWorkflowException Workflow client exception.
607: */
608: void terminateApp(int toolAgentHandle, String procInstId,
609: String workItemId) throws WMWorkflowException;
610: }
|