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.tool;
046:
047: import java.io.IOException;
048: import java.io.Writer;
049: import java.lang.reflect.InvocationTargetException;
050:
051: /**
052: * Enables the workflow engine or a client to invoke a tool (application or
053: * procedure). Implementations can be stateful only to the extent of containing
054: * service configuration information; their methods must be threadsafe.
055: *
056: * @author Adrian Price
057: */
058: public interface ToolAgent {
059: /**
060: * The tool has not yet been invoked.
061: */
062: int WAITING = 0;
063: /**
064: * The tool agent is running.
065: */
066: int RUNNING = 1;
067: /**
068: * The tool is active.
069: */
070: int ACTIVE = 2;
071: /**
072: * The agent or tool encountered an error.
073: */
074: int ERROR = 3;
075: /**
076: * The tool was terminated.
077: */
078: int TERMINATED = 4;
079: /**
080: * The tool has finished running.
081: */
082: int FINISHED = 5;
083: /**
084: * The tool finished normally.
085: */
086: int EXIT_NORMAL = 0;
087: /**
088: * The tool was cancelled by the user.
089: */
090: int EXIT_CANCEL = 1;
091:
092: /**
093: * Renders the JavaScript necessary to invoke the tool from an HTML browser.
094: *
095: * @param ti
096: * @param writer
097: */
098: void renderInvocationScript(ToolInvocation ti, Writer writer)
099: throws IOException;
100:
101: /**
102: * Invokes the tool. The implementation must update the values of any INOUT
103: * and OUT parameters appropriately, and should set the values of any IN
104: * parameters to <code>null</code>.
105: *
106: * @param ti The tool invocation context.
107: * @return The tool's exit code. One of {@link #EXIT_NORMAL},
108: * {@link #EXIT_CANCEL}.
109: * @throws IllegalStateException if the ToolAgent is not in the
110: * {@link #WAITING} state.
111: * @throws InvocationTargetException As thrown prior to or during during
112: * tool execution.
113: */
114: int invokeApplication(ToolInvocation ti)
115: throws InvocationTargetException;
116:
117: /**
118: * Returns the tool status.
119: *
120: * @return One of: {@link #WAITING}, {@link #RUNNING}, {@link #ACTIVE},
121: * {@link #TERMINATED}, {@link #FINISHED}.
122: */
123: int requestAppStatus();
124:
125: /**
126: * Terminates the running tool.
127: *
128: * @throws IllegalStateException if the tool is not running.
129: */
130: void terminateApp();
131: }
|