001: /*
002: * Copyright (c) 2002-2003 by OpenSymphony
003: * All rights reserved.
004: */
005: package com.opensymphony.workflow;
006:
007: import com.opensymphony.module.propertyset.PropertySet;
008:
009: import com.opensymphony.workflow.config.Configuration;
010: import com.opensymphony.workflow.loader.WorkflowDescriptor;
011: import com.opensymphony.workflow.query.WorkflowExpressionQuery;
012: import com.opensymphony.workflow.query.WorkflowQuery;
013:
014: import java.util.List;
015: import java.util.Map;
016:
017: /**
018: * The core workflow interface.
019: *
020: * @author <a href="mailto:plightbo@hotmail.com">Patrick Lightbody</a>
021: */
022: public interface Workflow {
023: //~ Instance fields ////////////////////////////////////////////////////////
024:
025: String BSF_COL = "col";
026: String BSF_LANGUAGE = "language";
027: String BSF_ROW = "row";
028: String BSF_SCRIPT = "script";
029: String BSF_SOURCE = "source";
030: String BSH_SCRIPT = "script";
031:
032: // statics
033: String CLASS_NAME = "class.name";
034: String EJB_LOCATION = "ejb.location";
035: String JNDI_LOCATION = "jndi.location";
036:
037: //~ Methods ////////////////////////////////////////////////////////////////
038:
039: /**
040: * @deprecated use {@link #getAvailableActions(long, Map)} with an empty Map instead.
041: */
042: public int[] getAvailableActions(long id);
043:
044: /**
045: * Returns a Collection of Step objects that are the current steps of the specified workflow instance.
046: *
047: * @param id The workflow instance id.
048: * @return The steps that the workflow instance is currently in.
049: */
050: public List getCurrentSteps(long id);
051:
052: /**
053: * Return the state of the specified workflow instance id.
054: * @param id The workflow instance id.
055: * @return int The state id of the specified workflow
056: */
057: public int getEntryState(long id);
058:
059: /**
060: * Returns a list of all steps that are completed for the given workflow instance id.
061: *
062: * @param id The workflow instance id.
063: * @return a List of Steps
064: * @see com.opensymphony.workflow.spi.Step
065: */
066: public List getHistorySteps(long id);
067:
068: /**
069: * Get the PropertySet for the specified workflow instance id.
070: * @param id The workflow instance id.
071: */
072: public PropertySet getPropertySet(long id);
073:
074: /**
075: * Get a collection (Strings) of currently defined permissions for the specified workflow instance.
076: * @param id the workflow instance id.
077: * @return A List of permissions specified currently (a permission is a string name).
078: * @deprecated use {@link #getSecurityPermissions(long, java.util.Map)} with a null map instead.
079: */
080: public List getSecurityPermissions(long id);
081:
082: /**
083: * Get a collection (Strings) of currently defined permissions for the specified workflow instance.
084: * @param id id the workflow instance id.
085: * @param inputs inputs The inputs to the workflow instance.
086: * @return A List of permissions specified currently (a permission is a string name).
087: */
088: public List getSecurityPermissions(long id, Map inputs);
089:
090: /**
091: * Get the workflow descriptor for the specified workflow name.
092: * @param workflowName The workflow name.
093: */
094: public WorkflowDescriptor getWorkflowDescriptor(String workflowName);
095:
096: /**
097: * Get the name of the specified workflow instance.
098: * @param id the workflow instance id.
099: */
100: public String getWorkflowName(long id);
101:
102: /**
103: * Check if the calling user has enough permissions to initialise the specified workflow.
104: * @param workflowName The name of the workflow to check.
105: * @param initialStep The id of the initial state to check.
106: * @return true if the user can successfully call initialize, false otherwise.
107: */
108: public boolean canInitialize(String workflowName, int initialStep);
109:
110: /**
111: * Check if the state of the specified workflow instance can be changed to the new specified one.
112: * @param id The workflow instance id.
113: * @param newState The new state id.
114: * @return true if the state of the workflow can be modified, false otherwise.
115: */
116: public boolean canModifyEntryState(long id, int newState);
117:
118: /**
119: * Modify the state of the specified workflow instance.
120: * @param id The workflow instance id.
121: * @param newState the new state to change the workflow instance to.
122: * If the new state is {@link com.opensymphony.workflow.spi.WorkflowEntry.KILLED}
123: * or {@link com.opensymphony.workflow.spi.WorkflowEntry.COMPLETED}
124: * then all current steps are moved to history steps. If the new state is
125: */
126: public void changeEntryState(long id, int newState)
127: throws WorkflowException;
128:
129: /**
130: * Perform an action on the specified workflow instance.
131: * @param id The workflow instance id.
132: * @param actionId The action id to perform (action id's are listed in the workflow descriptor).
133: * @param inputs The inputs to the workflow instance.
134: * @throws InvalidInputException if a validator is specified and an input is invalid.
135: * @throws InvalidActionException if the action is invalid for the specified workflow
136: * instance's current state.
137: */
138: public void doAction(long id, int actionId, Map inputs)
139: throws InvalidInputException, WorkflowException;
140:
141: /**
142: * Executes a special trigger-function using the context of the given workflow instance id.
143: * Note that this method is exposed for Quartz trigger jobs, user code should never call it.
144: * @param id The workflow instance id
145: * @param triggerId The id of the speciail trigger-function
146: */
147: public void executeTriggerFunction(long id, int triggerId)
148: throws WorkflowException;
149:
150: /**
151: * Initializes a workflow so that it can begin processing. A workflow must be initialized before it can
152: * begin any sort of activity. It can only be initialized once.
153: *
154: * @param workflowName The workflow name to create and initialize an instance for
155: * @param initialAction The initial step to start the workflow
156: * @param inputs The inputs entered by the end-user
157: * @throws InvalidRoleException if the user can't start this function
158: * @throws InvalidInputException if a validator is specified and an input is invalid.
159: * @throws InvalidActionException if the specified initial action is invalid for the specified workflow.
160: */
161: public long initialize(String workflowName, int initialAction,
162: Map inputs) throws InvalidRoleException,
163: InvalidInputException, WorkflowException,
164: InvalidEntryStateException, InvalidActionException;
165:
166: /**
167: * Query the workflow store for matching instances
168: * @deprecated use {@link Workflow#query(WorkflowExpressionQuery)} instead.
169: */
170: public List query(WorkflowQuery query) throws WorkflowException;
171:
172: /**
173: * Query the workflow store for matching instances
174: */
175: public List query(WorkflowExpressionQuery query)
176: throws WorkflowException;
177:
178: /**
179: * Get the available actions for the specified workflow instance.
180: * @ejb.interface-method
181: * @param id The workflow instance id.
182: * @param inputs The inputs map to pass on to conditions
183: * @return An array of action id's that can be performed on the specified entry
184: * @throws IllegalArgumentException if the specified id does not exist, or if its workflow
185: * descriptor is no longer available or has become invalid.
186: */
187: int[] getAvailableActions(long id, Map inputs);
188:
189: /**
190: * Set the configuration for this workflow.
191: * If not set, then the workflow will use the default configuration static instance.
192: * @param configuration a workflow configuration
193: */
194: void setConfiguration(Configuration configuration);
195:
196: /**
197: * Get all available workflow names.
198: */
199: String[] getWorkflowNames();
200:
201: /**
202: * Determine if a particular workflow can be initialized.
203: * @param workflowName The workflow name to check.
204: * @param initialAction The potential initial action.
205: * @param inputs The inputs to check.
206: * @return true if the workflow can be initialized, false otherwise.
207: */
208: boolean canInitialize(String workflowName, int initialAction,
209: Map inputs);
210:
211: /**
212: * Remove the specified workflow descriptor.
213: * @param workflowName The workflow name of the workflow to remove.
214: * @return true if the workflow was removed, false otherwise.
215: * @throws FactoryException If the underlying workflow factory has an error removing the workflow,
216: * or if it does not support the removal of workflows.
217: */
218: boolean removeWorkflowDescriptor(String workflowName)
219: throws FactoryException;
220:
221: /**
222: * Add a new workflow descriptor
223: * @param workflowName The workflow name of the workflow to add
224: * @param descriptor The workflow descriptor to add
225: * @param replace true, if an existing descriptor should be overwritten
226: * @return true if the workflow was added, fales otherwise
227: * @throws FactoryException If the underlying workflow factory has an error adding the workflow,
228: * or if it does not support adding workflows.
229: */
230: boolean saveWorkflowDescriptor(String workflowName,
231: WorkflowDescriptor descriptor, boolean replace)
232: throws FactoryException;
233: }
|