001/**
002 * Licensed to the Apache Software Foundation (ASF) under one
003 * or more contributor license agreements.  See the NOTICE file
004 * distributed with this work for additional information
005 * regarding copyright ownership.  The ASF licenses this file
006 * to you under the Apache License, Version 2.0 (the
007 * "License"); you may not use this file except in compliance
008 * with the License.  You may obtain a copy of the License at
009 * 
010 *      http://www.apache.org/licenses/LICENSE-2.0
011 * 
012 * Unless required by applicable law or agreed to in writing, software
013 * distributed under the License is distributed on an "AS IS" BASIS,
014 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
015 * See the License for the specific language governing permissions and
016 * limitations under the License.
017 */
018package org.apache.oozie.workflow;
019
020import org.apache.hadoop.conf.Configuration;
021
022
023/**
024 * The workflow library provides application parsing and storage capabilities for workflow instances. <p/> The
025 * implementation is responsible for doing the store operations in a transactional way, either in autocommit or within
026 * the scope of a transaction.
027 */
028public interface WorkflowLib {
029
030    /**
031     * Parse a workflow application definition.
032     *
033     * @param wfXml string containing the workflow definition.
034     * @param jobConf job configuration
035     * @return the parse workflow application.
036     * @throws WorkflowException thrown if the definition could not be parsed.
037     */
038    public WorkflowApp parseDef(String wfXml, Configuration jobConf) throws WorkflowException;
039
040
041    /**
042     * Create a workflow instance.
043     *
044     * @param app application to create a workflow instance of.
045     * @param conf job configuration.
046     * @return the newly created workflow instance.
047     * @throws WorkflowException thrown if the instance could not be created.
048     */
049    public WorkflowInstance createInstance(WorkflowApp app, Configuration conf) throws WorkflowException;
050
051    /**
052     * Create a workflow instance with the given wfId. This will be used for re-running workflows.
053     *
054     * @param app application to create a workflow instance of.
055     * @param conf job configuration.
056     * @param wfId Workflow ID.
057     * @return the newly created workflow instance.
058     * @throws WorkflowException thrown if the instance could not be created.
059     */
060    public WorkflowInstance createInstance(WorkflowApp app, Configuration conf, String wfId) throws WorkflowException;
061
062    /**
063     * Insert a workflow instance in storage.
064     *
065     * @param instance of the workflow instance to insert.
066     * @throws WorkflowException thrown if the instance could not be inserted.
067     */
068    public void insert(WorkflowInstance instance) throws WorkflowException;
069
070    /**
071     * Load a workflow instance from storage.
072     *
073     * @param id ID of the workflow instance to load.
074     * @return the loaded workflow instance.
075     * @throws WorkflowException thrown if the instance could not be loaded.
076     */
077    public WorkflowInstance get(String id) throws WorkflowException;
078
079    /**
080     * Update a workflow instance in storage.
081     *
082     * @param instance workflow instance to update.
083     * @throws WorkflowException thrown if the instance could not be loaded.
084     */
085    public void update(WorkflowInstance instance) throws WorkflowException;
086
087    /**
088     * Delete a workflow instance from storage.
089     *
090     * @param id ID of the workflow instance to delete.
091     * @throws WorkflowException thrown if the instance could not be deleted.
092     */
093    public void delete(String id) throws WorkflowException;
094
095
096    /**
097     * Commit changes to store.
098     *
099     * @throws WorkflowException thrown if the commit could not be done.
100     */
101    public void commit() throws WorkflowException;
102
103    /**
104     * Close store. It rollbacks if there was no commit.
105     *
106     * @throws WorkflowException thrown if the close could not be done.
107     */
108    public void close() throws WorkflowException;
109
110}