/*
 * $Id: ProcessManager.java,v 1.2 2004/09/20 10:26:14 koppy Exp $
 *
 * Copyright (c) Siemens AG 2008 
 *           (c) Universität Paderborn 2008 
 * Licensed under EUPL 1.1. 
 * 
 * Created on 13.07.2004
 *
 * $Log: ProcessManager.java,v $
 * Revision 1.2  2004/09/20 10:26:14  koppy
 * +javadoc Dokumentation
 *
 * Revision 1.1  2004/08/30 14:49:59  koppy
 * Initiale Version der Workflow-Komponente
 *
 */
package vkc.workflow.service.manager;

import java.util.List;
import java.util.Locale;
import java.util.Map;

import org.enhydra.shark.api.client.wfbase.BaseException;

import vkc.db.entities.VKCUser;
import vkc.workflow.WorkflowException;
import vkc.workflow.service.WfMConnection;

/**
 * This interface defines methods
 * for managing workflow instances.
 * 
 * @author Andreas Koop
 */
public interface ProcessManager {
    
    /**
     * Returns a list (of type ProcessInstanceInfo)
     * 
     * @param userName username to connect to the workflow engine
     * @param pwd password to connect to the workflow engine
     * @param state the state of instances. Use the constants defined in <code>WfConstants</code>
     * @return list of type ProcessInstanceInfo
     * @throws WorkflowException
     */
    public List getProcessInstances(String userName, String pwd, String state)
    	throws WorkflowException; 
    
    /**
     * Instantiates a process from the given package/process definition id.
     * <p>
     * <b>Note:</b>After instantiation init variables can be set
     * before the process is started.
     * 
     * @param user the VKC user for authentication to workflow engine.
     * @param pkgId tha package id
     * @param pDefId the process id
     * @return procId the process id of the instantiated process.
     * @throws WorkflowException
     */
    public String instantiateProcess( VKCUser user, String pkgId, String pDefId)
		throws WorkflowException;
    
    
    /**
     * Starts the process with the fiven process id.
     * 
     * @param user the VKC user for authentication to workflow engine.
     * @param procId the process id
     * @throws WorkflowException
     */
    public void startProcess( VKCUser user, String procId)
		throws WorkflowException;
    
    /**
     * Aborts the process with the given id.
     * 
     * @param user the VKC user for authentication to workflow engine.
     * @param procId the process id
     * @throws WorkflowException
     */
    public void abortProcess( VKCUser user, String procId)
		throws WorkflowException;
    
    /**
     * Returns a list (of type VariableInfo)
     * associated with some process.
     * 
     * @param sConn workflow connection
     * @param locale locale object for localisation
     * @param procId process id
     * @param onlyInitParamaters set to true, if only init params should be returnd
     * @return list (of type VariableInfo)
     * @throws BaseException
     */
    public List getContextVariables(WfMConnection sConn, Locale locale, String procId, boolean onlyInitParamaters)
    	throws BaseException;
    
    
    /**
     * Updates the variables of some process context.
     * 
     * @param conn workflow connection
     * @param procId the process id
     * @param vars map of new variable values (key:variable id, value: new value)
     * @throws WorkflowException
     */
    public void updateVariables(WfMConnection conn, String procId, Map vars )
		throws WorkflowException;
    
    /**
     * Updates the initial variables of some process context.
     * 
     * @param sConn workflow connection
     * @param procId the process id
     * @param vars map of new variable values (key:variable id, value: new value)
     * @throws WorkflowException
     */
    public void updateInitialVariables(WfMConnection sConn, String procId, Map vars) 
    	throws WorkflowException; 
    
    /**
     * Deletes a closed process.
     * 
     * @param sConn workflow connection
     * @param procId process id
     * @throws WorkflowException
     */
    public void deleteClosedProcess( WfMConnection sConn, String procId ) throws WorkflowException;
    
    /**
     * Deletes ALL closed processes.
     * @param sConn workflow connection
     * @throws WorkflowException
     */
    public void deleteClosedProcesses( WfMConnection sConn) throws WorkflowException;
}
