001: /*
002: * This file is part of the WfMOpen project.
003: * Copyright (C) 2001-2003 Danet GmbH (www.danet.de), GS-AN.
004: * All rights reserved.
005: *
006: * This program is free software; you can redistribute it and/or modify
007: * it under the terms of the GNU General Public License as published by
008: * the Free Software Foundation; either version 2 of the License, or
009: * (at your option) any later version.
010: *
011: * This program is distributed in the hope that it will be useful,
012: * but WITHOUT ANY WARRANTY; without even the implied warranty of
013: * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
014: * GNU General Public License for more details.
015: *
016: * You should have received a copy of the GNU General Public License
017: * along with this program; if not, write to the Free Software
018: * Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307 USA
019: *
020: * $Id: ToolAgent.java,v 1.6 2006/09/29 12:32:10 drmlipp Exp $
021: *
022: * $Log: ToolAgent.java,v $
023: * Revision 1.6 2006/09/29 12:32:10 drmlipp
024: * Consistently using WfMOpen as projct name now.
025: *
026: * Revision 1.5 2006/09/26 11:23:19 drmlipp
027: * JavaDoc fixes.
028: *
029: * Revision 1.4 2005/09/05 09:41:49 drmlipp
030: * Synchronized with 1.3.2.
031: *
032: * Revision 1.3 2005/08/25 13:24:22 drmlipp
033: * Synchronized with 1.3.1p6.
034: *
035: * Revision 1.2 2005/04/08 11:28:05 drmlipp
036: * Merged changes from 1.3 branch up to 1.3p6.
037: *
038: * Revision 1.1.1.3.6.1 2005/03/02 09:58:16 drmlipp
039: * Removed "just in case" invocation of terminate when a tool calls
040: * complete.
041: *
042: * Revision 1.1.1.3 2004/08/18 15:17:38 drmlipp
043: * Update to 1.2
044: *
045: * Revision 1.14 2004/06/30 14:58:30 lipp
046: * Fixed typo.
047: *
048: * Revision 1.13 2004/04/12 19:33:52 lipp
049: * Clarified application invocation interface.
050: *
051: * Revision 1.12 2004/04/08 09:34:54 lipp
052: * Clarified documentation of package structure.
053: *
054: * Revision 1.11 2004/02/19 17:54:50 lipp
055: * Added RemoteException to ToolAgent.terminate.
056: *
057: * Revision 1.10 2003/11/28 10:53:15 lipp
058: * Passing ActivityProxy to tool agent's terminate to avoid deadlocks.
059: *
060: * Revision 1.9 2003/11/26 16:14:14 lipp
061: * Added possibility to declare tool as ResultProvider.
062: *
063: * Revision 1.8 2003/06/27 08:51:44 lipp
064: * Fixed copyright/license information.
065: *
066: * Revision 1.7 2003/06/17 15:47:26 lipp
067: * Prepared XML argument type control be tool implementation.
068: *
069: * Revision 1.6 2003/06/17 14:18:51 lipp
070: * Improved comment.
071: *
072: * Revision 1.5 2003/05/06 13:21:30 lipp
073: * Resolved cyclic dependency.
074: *
075: * Revision 1.4 2003/04/04 08:19:26 lipp
076: * Updated documentation.
077: *
078: * Revision 1.3 2003/03/19 14:12:34 montag
079: * WSIF support.
080: *
081: * Revision 1.2 2003/02/12 11:57:30 lipp
082: * Improved deadlock (RemoteException) handling for tools. Imroved debug
083: * information.
084: *
085: * Revision 1.1 2002/12/19 21:37:42 lipp
086: * Reorganized interfaces.
087: *
088: * Revision 1.6 2002/10/06 20:14:38 lipp
089: * Updated argument handling.
090: *
091: * Revision 1.5 2002/10/02 10:58:13 lipp
092: * Modifications for tool invocation.
093: *
094: * Revision 1.4 2002/09/17 09:20:12 lipp
095: * Added ApplicationNotStoppedException.
096: *
097: * Revision 1.3 2002/05/18 21:06:33 lipp
098: * Javadoc fix.
099: *
100: * Revision 1.2 2002/05/17 12:52:34 lipp
101: * Cleaned up interface to tools.
102: *
103: * Revision 1.1 2002/05/17 08:34:21 lipp
104: * Renamed aii/Application to aii/ToolAgent.
105: *
106: * Revision 1.3 2002/05/08 13:34:15 lipp
107: * New method cancel.
108: *
109: * Revision 1.2 2002/01/15 17:35:26 lipp
110: * Comment corrected.
111: *
112: * Revision 1.1 2002/01/15 14:56:31 lipp
113: * Initial version.
114: *
115: */
116: package de.danet.an.workflow.spis.aii;
117:
118: import java.util.Map;
119:
120: import java.rmi.RemoteException;
121:
122: import de.danet.an.workflow.api.Activity;
123: import de.danet.an.workflow.api.FormalParameter;
124:
125: /**
126: * This interface is used to control applications that execute work
127: * items. An application may implement this interface directly (it is
128: * "workflow aware"). Usually, however, this interface will be
129: * implemented by some adapter class that controls the application,
130: * and thus acts as an agent for the application.<P>
131: *
132: * An application is declared to participate in a workflow by the
133: * <code>application</code> tag in the XPDL. This declaration is
134: * associated with the implementation class of <code>ToolAgent</code>
135: * using an extension. The extension syntax supported allows to
136: * specify properties of the tool agent (see the <i>User Manual</i>
137: * for details).<P>
138: *
139: * An implementation of <code>ToolAgent</code> must be aware that
140: * several application invocations may be performed using the same
141: * instance of the class implementing <code>ToolAgent</code>. This
142: * implies that implementations must be thread-safe.<P>
143: *
144: * By default, the {@link #invoke <code>invoke</code>} method has full
145: * access to the activity as specified by the {@link
146: * de.danet.an.workflow.api.Activity activity
147: * interface}. Implementations that require long term storage of the
148: * activity must be aware that the activity is passed as an interface
149: * to a remote object and therefore unsuitable for long term
150: * persistence. Tool agents should persist the activity's unique key
151: * instead of the activity. The activity may later be retrieved from
152: * the key using {@link
153: * de.danet.an.workflow.api.ProcessDirectory#lookupActivity
154: * <code>ProcessDirectory.lookupActivity</code>} (obtaining the
155: * process directory from the {@link
156: * de.danet.an.workflow.api.WorkflowService#processDirectory
157: * <code>WorkflowService</code>}.
158: *
159: * @see de.danet.an.workflow.spis.aii
160: */
161: public interface ToolAgent {
162:
163: /**
164: * Invoke an application on the given activity.
165: *
166: * @param activity the activity to be executed. The supplied object
167: * must be serializable in order to support applications running as
168: * servers
169: * @param formalParameters the formal parameter definition as
170: * specified in the process definition. May be used e.g. by
171: * generic applications to adapt to specific formal parameter
172: * lists
173: * @param actualParameters the actual parameters of the
174: * application invocation. There is an entry in the map for every
175: * formal parameter using the id as key in the map.
176: * <code>OUT</code> parameters are initialized
177: * to zero. The map and the objects contained in the map must be
178: * serializable in order to support applications running as
179: * servers.
180: * @throws RemoteException if a temporary problem occurs and the
181: * workflow engine should retry the tool invocation (usually
182: * thrown when a deadlock situation occurs while accessing the
183: * activity).
184: * @throws CannotExecuteException if thrown, causes
185: * the activity to be terminated unless a mapping to a process exception
186: * is defined for the cause of the <code>CannotExecuteException</code>.
187: * If such a mapping is defined, the activity is abandoned.
188: * See the user manual for details.
189: */
190: void invoke(Activity activity, FormalParameter[] formalParameters,
191: Map actualParameters) throws RemoteException,
192: CannotExecuteException;
193:
194: /**
195: * Terminates execution of the given activity. If the activity has
196: * been terminated already, the method should do nothing
197: * (i.e. under certain conditions this method may be called more
198: * than once for a given activity).<P>
199: *
200: * Only the activity's methods <code>key</code> and
201: * <code>uniqueKey</code> should be used in an implementation of
202: * this method. Else, depending on the application server and
203: * database configuration, deadlocks may occur.<P>
204: *
205: * Up to version 1.3 this method has been called by the workflow
206: * engine when processing an invoked tool's call of {@link
207: * de.danet.an.workflow.omgcore.WfActivity#complete
208: * <code>WfActivity.complete()</code>}. The reasoning has been
209: * that the engine cannot be sure that <code>complete()</code> is
210: * called by the tool that has previously been invoked. (To ensure
211: * this, the engine would have to pass some token to the tool
212: * during invocation and the tool would have to pass this back to
213: * the engine when calling <code>complete()</code>. Such a
214: * procedure is, however, not defined by the OMG API.) By invoking
215: * <code>terminate()</code> on the currently running tool when
216: * processing <code>complete()</code>, the engine tried to make
217: * sure that at least the invoked tool is terminated if some
218: * imposter calls <code>complete()</code> instead of the invoked
219: * tool.<P>
220: *
221: * The overlapping of the tool processing the completion and the
222: * invocation of <code>terminate()</code> on the tool has,
223: * however, turned out to cause various problems with respect to
224: * transactions if the tool uses a database. Therefore, this
225: * procedure has been abandoned. Note that this change does not
226: * formally change the API as there has never been a contract
227: * about <code>terminate()</code> being called as part of
228: * processing <code>complete()</code>. The subject has been
229: * explained extensively only to provide an explanation if someone
230: * observes this change of behaviour.
231: *
232: * @param activity the activity to be canceled. The supplied object
233: * must be serializable in order to support applications running as
234: * servers.
235: * @throws ApplicationNotStoppedException if execution cannot be
236: * terminated (see {@link ApplicationNotStoppedException
237: * <code>ApplicationNotStoppedException</code>}).
238: * @throws RemoteException if a temporary problem occurs and the
239: * workflow engine should retry the tool termination
240: */
241: void terminate(Activity activity)
242: throws ApplicationNotStoppedException, RemoteException;
243: }
|