processinstance.java

jboss jpdl-3.2.2 nolib

/*
 * JBoss, Home of Professional Open Source
 * Copyright 2005, JBoss Inc., and individual contributors as indicated
 * by the @authors tag. See the copyright.txt in the distribution for a
 * full listing of individual contributors.
 *
 * This is free software; you can redistribute it and/or modify it
 * under the terms of the GNU Lesser General Public License as
 * published by the Free Software Foundation; either version 2.1 of
 * the License, or (at your option) any later version.
 *
 * This software is distributed in the hope that it will be useful,
 * but WITHOUT ANY WARRANTY; without even the implied warranty of
 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
 * Lesser General Public License for more details.
 *
 * You should have received a copy of the GNU Lesser General Public
 * License along with this software; if not, write to the Free
 * Software Foundation, Inc., 51 Franklin St, Fifth Floor, Boston, MA
 * 02110-1301 USA, or see the FSF site: http://www.fsf.org.
 */
package org.jbpm.graph.exe;

import java.io.Serializable;
import java.util.ArrayList;
import java.util.Collection;
import java.util.Date;
import java.util.HashMap;
import java.util.Iterator;
import java.util.List;
import java.util.Map;

import org.jbpm.JbpmException;
import org.jbpm.context.exe.ContextInstance;
import org.jbpm.graph.def.Event;
import org.jbpm.graph.def.Node;
import org.jbpm.graph.def.ProcessDefinition;
import org.jbpm.graph.def.Transition;
import org.jbpm.graph.log.ProcessInstanceCreateLog;
import org.jbpm.graph.log.ProcessInstanceEndLog;
import org.jbpm.logging.exe.LoggingInstance;
import org.jbpm.logging.log.ProcessLog;
import org.jbpm.module.def.ModuleDefinition;
import org.jbpm.module.exe.ModuleInstance;
import org.jbpm.scheduler.SchedulerService;
import org.jbpm.svc.Services;
import org.jbpm.taskmgmt.exe.TaskMgmtInstance;
import org.jbpm.util.Clock;
import org.jbpm.util.EqualsUtil;

/**
 * is one execution of a {@link org.jbpm.graph.def.ProcessDefinition}.
 * To create a new process execution of a process definition, just use the 
 * {@link #ProcessInstance(ProcessDefinition)}.
 * 
 */
public class ProcessInstance  implements Serializable {

  private static final long serialVersionUID = 1L;
  
  long id = 0;
  int version = 0;
  protected String key = null;
  protected Date start = null;
  protected Date end = null;
  protected ProcessDefinition processDefinition = null;
  protected Token rootToken = null;
  protected Token superProcessToken = null;
  protected boolean isSuspended = false;
  protected Map instances = null;
  protected Map transientInstances = null;
  protected List runtimeActions = null;
  /** not persisted */
  protected List cascadeProcessInstances = null;

  // constructors /////////////////////////////////////////////////////////////

  public ProcessInstance() {
  }

  /**
   * creates a new process instance for the given process definition, 
   * puts the root-token (=main path of execution) in the start state 
   * and executes the initial node.  In case the initial node is a 
   * start-state, it will behave as a wait state.
   * For each of the optional module definitions contained in the 
   * {@link ProcessDefinition}, the corresponding module instance 
   * will be created. 
   * @throws JbpmException if processDefinition is null.
   */
  public ProcessInstance(ProcessDefinition processDefinition) {
    this(processDefinition, null, null);
  }

  /**
   * creates a new process instance for the given process definition, 
   * puts the root-token (=main path of execution) in the start state 
   * and executes the initial node.  In case the initial node is a 
   * start-state, it will behave as a wait state.
   * For each of the optional module definitions contained in the 
   * {@link ProcessDefinition}, the corresponding module instance 
   * will be created.
   * @param variables will be inserted into the context variables 
   * after the context submodule has been created and before the 
   * process-start event is fired, which is also before the execution 
   * of the initial node.
   * @throws JbpmException if processDefinition is null.
   */
  public ProcessInstance(ProcessDefinition processDefinition, Map variables) {
    this(processDefinition, variables, null);
  }

  /**
   * creates a new process instance for the given process definition, 
   * puts the root-token (=main path of execution) in the start state 
   * and executes the initial node.  In case the initial node is a 
   * start-state, it will behave as a wait state.
   * For each of the optional module definitions contained in the 
   * {@link ProcessDefinition}, the corresponding module instance 
   * will be created.
   * @param variables will be inserted into the context variables 
   * after the context submodule has been created and before the 
   * process-start event is fired, which is also before the execution 
   * of the initial node.
   * @throws JbpmException if processDefinition is null.
   */
  public ProcessInstance(ProcessDefinition processDefinition, Map variables, String key) {
    if (processDefinition==null) throw new JbpmException("can't create a process instance when processDefinition is null");
    
    // initialize the members
    this.processDefinition = processDefinition;
    this.rootToken = new Token(this);
    this.start = Clock.getCurrentTime();
    this.key = key;
    
    // if this process instance is created in the context of a persistent operation
    Services.assignId(this);

    // create the optional definitions
    Map definitions = processDefinition.getDefinitions();
    // if the state-definition has optional definitions
    if ( definitions != null ) {
      instances = new HashMap();
      // loop over each optional definition
      Iterator iter = definitions.values().iterator();
      while (iter.hasNext()) {
        ModuleDefinition definition = (ModuleDefinition) iter.next();
        // and create the corresponding optional instance
        ModuleInstance instance = definition.createInstance();
        if (instance != null) {
          addInstance( instance );
        }
      }
    }
    
    // add the creation log
    rootToken.addLog(new ProcessInstanceCreateLog());
    
    // set the variables
    ContextInstance contextInstance = getContextInstance();
    if ( (contextInstance!=null)
         && (variables!=null)
       ) {
      contextInstance.addVariables(variables);
    }

    Node initialNode = rootToken.getNode();
    // fire the process start event
    if (initialNode!=null) {
      ExecutionContext executionContext = new ExecutionContext(rootToken);
      processDefinition.fireEvent(Event.EVENTTYPE_PROCESS_START, executionContext);

      // execute the start node
      initialNode.execute(executionContext);
    }
  }

  // optional module instances ////////////////////////////////////////////////
 
  /**
   * adds the given optional moduleinstance (bidirectional).
   */
  public ModuleInstance addInstance(ModuleInstance moduleInstance) {
    if (moduleInstance == null) throw new IllegalArgumentException("can't add a null moduleInstance to a process instance");
    if (instances == null) instances = new HashMap();
    instances.put(moduleInstance.getClass().getName(), moduleInstance);
    moduleInstance.setProcessInstance(this);
    return moduleInstance;
  }

  /**
   * removes the given optional moduleinstance (bidirectional). 
   */
  public ModuleInstance removeInstance(ModuleInstance moduleInstance) {
    ModuleInstance removedModuleInstance = null;
    if (moduleInstance == null) throw new IllegalArgumentException("can't remove a null moduleInstance from a process instance");
    if (instances != null) {
      removedModuleInstance = (ModuleInstance) instances.remove(moduleInstance.getClass().getName());
      if (removedModuleInstance!=null) {
        moduleInstance.setProcessInstance(null);
      }
    }
    return removedModuleInstance;
  }

  /**
   * looks up an optional module instance by its class.    
   */
  public ModuleInstance getInstance(Class clazz) {
    ModuleInstance moduleInstance = null;
    if ( instances != null ) {
      moduleInstance = (ModuleInstance) instances.get( clazz.getName() );
    }
    
    if (moduleInstance==null) {
      if (transientInstances==null) transientInstances = new HashMap();
      
      // client requested an instance that is not in the map of instances.
      // so we can safely assume that the client wants a transient instance
      moduleInstance = (ModuleInstance) transientInstances.get( clazz.getName() );
      if (moduleInstance==null) {
        try {
          moduleInstance = (ModuleInstance) clazz.newInstance();
          moduleInstance.setProcessInstance(this);

        } catch (Exception e) {
          e.printStackTrace();
          throw new JbpmException("couldn't instantiate transient module '"+clazz.getName()+"' with the default constructor");
        }
        transientInstances.put(clazz.getName(), moduleInstance);
      }
    }

    return moduleInstance;
  }

  /**
   * process instance extension for process variableInstances.
   */
  public ContextInstance getContextInstance() {
    return (ContextInstance) getInstance(ContextInstance.class);
  }

  /**
   * process instance extension for managing the tasks and actors.
   */
  public TaskMgmtInstance getTaskMgmtInstance() {
    return (TaskMgmtInstance) getInstance(TaskMgmtInstance.class);
  }

  /**
   * process instance extension for logging. Probably you don't need to access 
   * the logging instance directly.  Mostly, {@link Token#addLog(ProcessLog)} is 
   * sufficient and more convenient. 
   */