package ee.telekom.workflow.graph; import ee.telekom.workflow.graph.core.GraphInstanceImpl; /** * A {@link GraphEngineFacade} is the interface that external systems should use * to communicated with a graph engine. * * <p> * * An graph engine executes a workflow. A {@link Graph} specifies how it should * be executed and a {@link GraphInstance} tracks the current state of * execution. It is an graph engine which creates instances of * {@link GraphInstance} and {@link Token}. * * Engines must be thread-safe. Thus implementations of interface may be safely * shared among threads. */ public interface GraphEngineFacade{ /** * A shorthand for {@link #start(String, Integer, Environment, String)} using * the latest graph with the given name and an empty initial environment and * a <code>null</code> external id. */ GraphInstance start( String graphName ); /** * A shorthand for {@link #start(String, Integer, Environment, String)} using * an empty initial environment and a <code>null</code> external id. */ GraphInstance start( String graphName, Integer version ); /** * A shorthand for {@link #start(String, Integer, Environment, String)} using a * <code>null</code> external id. */ GraphInstance start( String graphName, Integer version, Environment initialEnvironment ); /** * Starts a {@link GraphInstance} of the {@link Graph} with the given name * and version and using the given {@link Environment} and associates the created * {@link GraphInstance} with the given external. Is the equivalent of doing * * <pre> * Graph graph = engine.getRepository().getLatestGraph(graphName); * GraphInstance graphInstance = engine.start(graph, initialEnvironment, * externalId); * </pre> * * If no graph is found for the given graphName, a {@link WorkflowException} * will be thrown. * * @param graphName * the name of the graph to execute * @param version * the version of the graph to execute of <code>null</code> for * the latest graph with the given name. * @param initialEnvironment * A starting environment for the {@link GraphInstance}. All * attributes from this environment will be copied into the new * graph instance's environment before execution starts. * @param externalId * the external id that the graph instance is associated with * @throws WorkflowException * If no graph is found with the given graphName * * @return a {@link GraphInstance} of the latest {@link Graph} with the * given name and using the given {@link Environment} which has * already been started (and, given that no wait states were * entered, is already completed). */ GraphInstance start( String graphName, Integer version, Environment initialEnvironment, Long externalId ); /** * A shorthand for {@link #start(Graph, Environment, String)} using an empty * initial environment and a <code>null</code> external id. */ GraphInstance start( Graph graph ); GraphInstance start( Graph graph, Environment initialEnvironment ); /** * Starts a {@link GraphInstance} of the given {@link Graph} using the given * {@link Environment}. A {@link Token} will be generated for the start node * (determined by {@link Graph#getStartNode()}), and this token will be * executed. If the graph does not contain nodes which go into a wait state, * the {@link GraphInstance} returned will be completed. * <p> * Before the graph instance is started, the given initial environment will * be copied into the one of the new graph instance. * * @param graph * the graph to create a graph instance of * @param initialEnvironment * an initial environment for the graph instance * @param externalId * the external id that the graph instance is associated with */ GraphInstanceImpl start( Graph graph, Environment initialEnvironment, Long externalId ); /** * Aborts the given {@link GraphInstance}'s execution and cancels all * associated tokens and work items. * * @param instance * the graph instance to abort */ void abort( GraphInstance instance ); /** * Completes the executed work item and continues execution until another * wait state is reached or until the graph instance is completed. * * @param workItem * the work item to complete */ void complete( GraphWorkItem workItem ); /** * Returns the engine's {@link GraphRepository}. * * @return the engine's {@link GraphRepository} */ GraphRepository getRepository(); /** * Returns the engine's {@link BeanResolver}, or <code>null</code> * if the engine does not support to resolve beans. * * @return the engine's {@link BeanResolver}, or <code>null</code> * if the engine does not support to resolve beans. */ BeanResolver getBeanResolver(); /** * Returns the engine's {@link NewGraphInstanceCreator}, or <code>null</code> * if the engine does not support to create sub graph instances. * * @return the engine's {@link NewGraphInstanceCreator}, or <code>null</code> * if the engine does not support to create sub graph instances. */ NewGraphInstanceCreator getNewGraphInstanceCreator(); /** * Adds a {@link GraphInstanceEventListener} to the engine. * * @param listener * listener to be added */ void registerInstanceEventListener( GraphInstanceEventListener listener ); /** * Adds a {@link GraphWorkItemEventListener} to the engine. * * @param listener * listener to be added */ void registerWorkItemEventListener( GraphWorkItemEventListener listener ); /** * Adds a {@link NodeEventListener} to the engine. * * @param listener * listener to be added */ void registerNodeEventListener( NodeEventListener listener ); }