001: /*--
002:
003: Copyright (C) 2002-2005 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: adrianprice@sourceforge.net.
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: Adrian Price (adrianprice@users.sourceforge.net).
027:
028: THIS SOFTWARE IS PROVIDED ``AS IS'' AND ANY EXPRESSED OR IMPLIED
029: WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES
030: OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
031: DISCLAIMED. IN NO EVENT SHALL THE AUTHOR(S) BE LIABLE FOR ANY DIRECT,
032: INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES
033: (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR
034: SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
035: HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT,
036: STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING
037: IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
038: POSSIBILITY OF SUCH DAMAGE.
039:
040: For more information on OBE, please see
041: <http://obe.sourceforge.net/>.
042:
043: */
044:
045: package org.obe.client.api;
046:
047: import org.obe.client.api.model.ActivityInstanceAttributes;
048: import org.obe.client.api.model.ProcessInstanceAttributes;
049: import org.obe.client.api.model.WorkItemAttributes;
050: import org.obe.client.api.tool.Parameter;
051: import org.obe.client.api.tool.ToolInvocation;
052: import org.obe.xpdl.model.pkg.XPDLPackage;
053: import org.wfmc.audit.WMAAuditEntryIterator;
054: import org.wfmc.wapi.WAPI;
055: import org.wfmc.wapi.WMFilter;
056: import org.wfmc.wapi.WMInvalidProcessDefinitionException;
057: import org.wfmc.wapi.WMWorkflowException;
058: import org.wfmc.wapi2.WAPI2;
059:
060: /**
061: * WAPI2 extensions for process definition and instance management. The
062: * process repository functions provide for pluggable process definition
063: * language support; at present only {@link #XPDL} is supported.
064: * <p/>
065: * The {@link WAPI} superinterface provides many methods that accept a
066: * {@link WMFilter filter} object to restrict the scope of the operation. The
067: * filter refers to attributes of process instance, activity instance, and work
068: * item as appropriate. In OBE, these system attributes are described by
069: * interfaces in the {@link org.obe.client.api.model} package.
070: *
071: * @author Adrian Price
072: * @see WMClientFactory
073: * @see ProcessInstanceAttributes
074: * @see ActivityInstanceAttributes
075: * @see WorkItemAttributes
076: */
077: public interface WMClient extends WAPI2 {
078: /**
079: * IBM/Microsoft/BEA's Business Process Execution Language for Web Services.
080: */
081: String BPEL4WS = "text/xml/bpel4ws";
082: /**
083: * BPMI's Business Process Modeling Language.
084: */
085: String BPML = "text/xml/bpml";
086: /**
087: * WfMC's Workflow Process Definition Language.
088: */
089: String WPDL = "text/wpdl";
090: /**
091: * IBM's Web Services Flow Language.
092: */
093: String WSFL = "text/xml/wsfl";
094: /**
095: * BPMI's Web Services Process Language.
096: */
097: String WSPL = "text/xml/wspl";
098: /**
099: * Microsoft's BizTalk Process Definition Language.
100: */
101: String XLANG = "text/xml/xlang";
102: /**
103: * WfMC's XML Process Definition Language.
104: */
105: String XPDL = "text/xml/xpdl";
106:
107: /**
108: * Returns the protocol in use by this client instance.
109: *
110: * @return The client protocol.
111: */
112: String getProtocol();
113:
114: /**
115: * Creates a package using the supplied content.
116: *
117: * @param pkg Package definition.
118: * @return The ID of the new package.
119: * @throws WMWorkflowException
120: */
121: String createPackage(XPDLPackage pkg) throws WMWorkflowException;
122:
123: /**
124: * Updates the specified process definition package.
125: *
126: * @param pkg The process definition package.
127: * @throws WMWorkflowException
128: */
129: void updatePackage(XPDLPackage pkg) throws WMWorkflowException;
130:
131: /**
132: * Creates a package using the supplied content in a specified format.
133: *
134: * @param content Package definition in specified format.
135: * @param contentType The MIME content type of the package definition, in a
136: * supported format.
137: * @return The ID of the new package.
138: * @throws WMWorkflowException
139: */
140: String createPackage(String content, String contentType)
141: throws WMWorkflowException;
142:
143: /**
144: * Retrieves an XPDL package.
145: *
146: * @param packageId The package ID.
147: * @return The XPDL package.
148: * @throws WMWorkflowException
149: */
150: XPDLPackage getPackage(String packageId) throws WMWorkflowException;
151:
152: /**
153: * Retrieves the content of the a package in the specified format.
154: *
155: * @param packageId The package ID.
156: * @param contentType The MIME content type of the package definition, must
157: * be a supported format.
158: * @return Package definition in XPDL format.
159: * @throws WMWorkflowException
160: */
161: String getPackageContent(String packageId, String contentType)
162: throws WMWorkflowException;
163:
164: /**
165: * Sets the content of the specified package.
166: *
167: * @param packageId The ID of the package to update.
168: * @param content Package definition in a supported format.
169: * @param contentType The MIME content type of the package definition, must
170: * be a supported format.
171: * @throws WMWorkflowException
172: */
173: void setPackageContent(String packageId, String content,
174: String contentType) throws WMWorkflowException;
175:
176: /**
177: * Permanently deletes the specified process definition.
178: *
179: * @param packageId The process definition ID.
180: * @throws WMWorkflowException
181: */
182: void deletePackage(String packageId) throws WMWorkflowException;
183:
184: /**
185: * Creates a new instance of the named workflow process. The system
186: * instantiates the 'most valid' version of the named process, based on the
187: * versioning metadata in the ProcessHeader (ValidFrom, ValidTo).
188: *
189: * @param name The process definition name.
190: * @param processInstanceName The name of the process instance.
191: * @return The process instance id.
192: * @throws WMInvalidProcessDefinitionException
193: * if the process definition
194: * does not exist, is disabled, under revision, or has no valid versions as
195: * determined for the current system time.
196: * @throws WMWorkflowException Workflow client exception
197: */
198: String createProcessInstanceVersioned(String name,
199: String processInstanceName) throws WMWorkflowException;
200:
201: /**
202: * Deletes a process instance from persistent storage.
203: *
204: * @param processInstanceId The ID of the process instance to delete.
205: * @throws WMWorkflowException
206: */
207: void deleteProcessInstance(String processInstanceId)
208: throws WMWorkflowException;
209:
210: /**
211: * Deletes a process instance from persistent storage.
212: *
213: * @param processDefinitionId The ID of the process definition for which
214: * to delete instances.
215: * @param filter A filter specification; can be <code>null</code>.
216: * @throws WMWorkflowException
217: */
218: void deleteProcessInstances(String processDefinitionId,
219: WMFilter filter) throws WMWorkflowException;
220:
221: /**
222: * Finds audit entries matching a user-supplied criterion.
223: *
224: * @param filter Filter criterion.
225: * @return The matching audit entries.
226: * @throws WMWorkflowException
227: */
228: WMAAuditEntryIterator listAuditEntries(WMFilter filter)
229: throws WMWorkflowException;
230:
231: /**
232: * Deletes audit entries matching a user-supplied criterion.
233: *
234: * @param filter Filter criterion.
235: * @return The count of audit entries deleted.
236: * @throws WMWorkflowException
237: */
238: int deleteAuditEntries(WMFilter filter) throws WMWorkflowException;
239:
240: /**
241: * Returns information to enable a client to invoke a tool. The returned
242: * {@link ToolInvocation ToolInvocations} can either be used directly to
243: * invoke the Application (in the case of a thick client), or can be used to
244: * render a response document (in the case of a thin client such as a
245: * web-based worklist handler).
246: *
247: * @param procInstId The process instance ID.
248: * @param workItemId The work item ID.
249: * @return Tool invocation information.
250: * @throws WMWorkflowException
251: */
252: ToolInvocation[] executeWorkItem(String procInstId,
253: String workItemId) throws WMWorkflowException;
254:
255: /**
256: * Informs the workflow engine that a tool is being started.
257: *
258: * @param procInstId The process instance ID.
259: * @param workItemId The work item ID.
260: * @throws WMWorkflowException
261: */
262: void toolStarted(String procInstId, String workItemId)
263: throws WMWorkflowException;
264:
265: /**
266: * Informs the workflow engine that a tool has finished executing.
267: *
268: * @param procInstId The process instance ID.
269: * @param workItemId The work item ID.
270: * @param appStatus The application exit status.
271: * @param parms Parameters containing output results.
272: * @throws WMWorkflowException
273: */
274: void toolFinished(String procInstId, String workItemId,
275: int appStatus, Parameter[] parms)
276: throws WMWorkflowException;
277: }
|