org.jbpm.context.exe.ContextInstance Maven / Gradle / Ivy

Go to download
/*
 * 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.context.exe;

import java.util.ArrayList;
import java.util.HashMap;
import java.util.Iterator;
import java.util.List;
import java.util.Map;

import org.jbpm.JbpmException;
import org.jbpm.graph.exe.Token;
import org.jbpm.module.exe.ModuleInstance;

/**
 * maintains all the key-variable pairs for a process instance. You can obtain a ContextInstance
 * from a processInstance from a process instance like this :
 * 
 *  * ProcessInstance processInstance = ...;
 * ContextInstance contextInstance = processInstance.getContextInstance();
 * 
 * 
 * More information on context and process variableInstances can be found in the userguide, section
 * context
 */
public class ContextInstance extends ModuleInstance {

  private static final long serialVersionUID = 1L;

  // maps Tokens to TokenVariableMaps
  protected Map tokenVariableMaps;
  // maps variable names (String) to values (Object)
  protected transient Map transientVariables;
  protected transient List updatedVariableContainers;

  public ContextInstance() {
  }

  // normal variableInstances (persistent) ////////////////////////////////////

  /**
   * creates a variable on the root-token (= process-instance scope) and calculates the actual
   * VariableInstance-type from the value.
   */
  public void createVariable(String name, Object value) {
    setVariableLocally(name, value, getRootToken());
  }

  /**
   * sets the variable on the root token, creates the variable if necessary and calculates the
   * actual VariableInstance-type from the value.
   */
  public void setVariableLocally(String name, Object value) {
    setVariableLocally(name, value, getRootToken());
  }

  /**
   * creates a variable in the scope of the given token and calculates the actual
   * VariableInstance-type from the value.
   */
  public void createVariable(String name, Object value, Token token) {
    setVariableLocally(name, value, token);
  }

  /**
   * creates a variable in the scope of the given token and calculates the actual
   * VariableInstance-type from the value.
   */
  public void setVariableLocally(String name, Object value, Token token) {
    TokenVariableMap tokenVariableMap = createTokenVariableMap(token);
    tokenVariableMap.setVariableLocally(name, value);
  }

  /**
   * gets all the variableInstances on the root-token (= process-instance scope).
   */
  public Map getVariables() {
    return getVariables(getRootToken());
  }

  /**
   * retrieves all the variableInstances in scope of the given token.
   */
  public Map getVariables(Token token) {
    TokenVariableMap tokenVariableMap = getTokenVariableMap(token);
    return tokenVariableMap != null ? tokenVariableMap.getVariables() : null;
  }

  /**
   * adds all the variableInstances on the root-token (= process-instance scope).
   */
  public void addVariables(Map variables) {
    setVariables(variables, getRootToken());
  }

  /**
   * The method setVariables is the same as the {@link #addVariables(Map, Token)}, but it was
   * added for more consistency.
   */
  public void setVariables(Map variables) {
    setVariables(variables, getRootToken());
  }

  /**
   * adds all the variableInstances to the scope of the given token. This method delegates to
   * {@link #setVariables(Map, Token)}. The method setVariables was added for more consistency.
   */
  public void addVariables(Map variables, Token token) {
    setVariables(variables, token);
  }

  /**
   * adds all the variableInstances to the scope of the given token. The method setVariables is
   * the same as the {@link #addVariables(Map, Token)}, but it was added for more consistency.
   */
  public void setVariables(Map variables, Token token) {
    // [JBPM-1778] empty variable map is set as null on process creation
    TokenVariableMap tokenVariableMap = getOrCreateTokenVariableMap(token);
    for (Iterator iter = variables.entrySet().iterator(); iter.hasNext();) {
      Map.Entry entry = (Map.Entry) iter.next();
      String name = (String) entry.getKey();
      Object value = entry.getValue();
      tokenVariableMap.setVariable(name, value);
    }
  }

  /**
   * gets the variable with the given name on the root-token (= process-instance scope).
   */
  public Object getVariable(String name) {
    return getVariable(name, getRootToken());
  }

  /**
   * retrieves a variable in the scope of the token. If the given token does not have a variable
   * for the given name, the variable is searched for up the token hierarchy.
   */
  public Object getVariable(String name, Token token) {
    Object variable = null;
    TokenVariableMap tokenVariableMap = getTokenVariableMap(token);
    if (tokenVariableMap != null) {
      variable = tokenVariableMap.getVariable(name);
    }
    return variable;
  }

  /**
   * retrieves a variable which is local to the token. Method
   * {@link #getVariableLocally(String, Token)} is the same as this method and it was added for
   * naming consistency.
   */
  public Object getLocalVariable(String name, Token token) {
    return getVariableLocally(name, token);
  }

  /**
   * retrieves a variable which is local to the token. this method was added for naming
   * consistency. it is the same as {@link #getLocalVariable(String, Token)}.
   */
  public Object getVariableLocally(String name, Token token) {
    Object variable = null;
    if (tokenVariableMaps != null && tokenVariableMaps.containsKey(token)) {
      TokenVariableMap tokenVariableMap = (TokenVariableMap) tokenVariableMaps.get(token);
      if (tokenVariableMap != null) {
        variable = tokenVariableMap.getVariableLocally(name);
      }
    }
    return variable;
  }

  /**
   * sets a variable on the process instance scope.
   */
  public void setVariable(String name, Object value) {
    setVariable(name, value, getRootToken());
  }

  /**
   * sets a variable. If a variable exists in the scope given by the token, that variable is
   * updated. Otherwise, the variable is created on the root token (=process instance scope).
   */
  public void setVariable(String name, Object value, Token token) {
    TokenVariableMap tokenVariableMap = getOrCreateTokenVariableMap(token);
    tokenVariableMap.setVariable(name, value);
  }

  /**
   * checks if a variable is present with the given name on the root-token (= process-instance
   * scope).
   */
  public boolean hasVariable(String name) {
    return hasVariable(name, getRootToken());
  }

  /**
   * checks if a variable is present with the given name in the scope of the token.
   */
  public boolean hasVariable(String name, Token token) {
    boolean hasVariable = false;
    TokenVariableMap tokenVariableMap = getTokenVariableMap(token);
    if (tokenVariableMap != null) {
      hasVariable = tokenVariableMap.hasVariable(name);
    }
    return hasVariable;
  }

  /**
   * deletes the given variable on the root-token (=process-instance scope).
   */
  public void deleteVariable(String name) {
    deleteVariable(name, getRootToken());
  }

  /**
   * deletes a variable from the given token. For safety reasons, this method does not propagate
   * the deletion to parent tokens in case the given token does not contain the variable.
   */
  public void deleteVariable(String name, Token token) {
    TokenVariableMap tokenVariableMap = getTokenVariableMap(token);
    if (tokenVariableMap != null) {
      tokenVariableMap.deleteVariable(name);
    }
  }

  // transient variableInstances //////////////////////////////////////////////

  /**
   * retrieves the transient variable for the given name.
   */
  public Object getTransientVariable(String name) {
    Object transientVariable = null;
    if (transientVariables != null) {
      transientVariable = transientVariables.get(name);
    }
    return transientVariable;
  }

  /**
   * sets the transient variable for the given name to the given value.
   */
  public void setTransientVariable(String name, Object value) {
    if (transientVariables == null) {
      transientVariables = new HashMap();
    }
    transientVariables.put(name, value);
  }

  /**
   * tells if a transient variable with the given name is present.
   */
  public boolean hasTransientVariable(String name) {
    if (transientVariables == null) {
      return false;
    }
    return transientVariables.containsKey(name);
  }

  /**
   * retrieves all the transient variableInstances map. note that no deep copy is performed,
   * changing the map leads to changes in the transient variableInstances of this context
   * instance.
   */
  public Map getTransientVariables() {
    return transientVariables;
  }

  /**
   * replaces the transient variableInstances with the given map.
   */
  public void setTransientVariables(Map transientVariables) {
    this.transientVariables = transientVariables;
  }

  /**
   * removes the transient variable.
   */
  public void deleteTransientVariable(String name) {
    if (transientVariables == null) return;
    transientVariables.remove(name);
  }

  private Token getRootToken() {
    return processInstance.getRootToken();
  }

  /**
   * searches for the first token-variable-map for the given token and creates it on the root
   * token if it doesn't exist.
   */
  public TokenVariableMap getOrCreateTokenVariableMap(Token token) {
    if (token == null) {
      throw new JbpmException("can't get variables for token 'null'");
    }

    // if the given token has a variable map
    TokenVariableMap tokenVariableMap = null;
    if ((tokenVariableMaps != null) && (tokenVariableMaps.containsKey(token))) {
      tokenVariableMap = (TokenVariableMap) tokenVariableMaps.get(token);

    }
    else if (!token.isRoot()) {
      tokenVariableMap = getOrCreateTokenVariableMap(token.getParent());

    }
    else {
      tokenVariableMap = createTokenVariableMap(token);
    }

    return tokenVariableMap;
  }

  private TokenVariableMap createTokenVariableMap(Token token) {
    if (tokenVariableMaps == null) {
      tokenVariableMaps = new HashMap();
    }
    TokenVariableMap tokenVariableMap = (TokenVariableMap) tokenVariableMaps.get(token);
    if (tokenVariableMap == null) {
      tokenVariableMap = new TokenVariableMap(token, this);
      tokenVariableMaps.put(token, tokenVariableMap);
    }
    return tokenVariableMap;
  }

  /**
   * looks for the first token-variable-map that is found up the token-parent hierarchy.
   */
  public TokenVariableMap getTokenVariableMap(Token token) {
    TokenVariableMap tokenVariableMap = null;
    if (tokenVariableMaps != null) {
      if (tokenVariableMaps.containsKey(token)) {
        tokenVariableMap = (TokenVariableMap) tokenVariableMaps.get(token);
      }
      else if (!token.isRoot()) {
        tokenVariableMap = getTokenVariableMap(token.getParent());
      }
    }
    return tokenVariableMap;
  }

  public VariableInstance getVariableInstance(String name, Token token) {
    VariableInstance variableInstance = null;
    TokenVariableMap tokenVariableMap = getTokenVariableMap(token);
    if (tokenVariableMap != null) {
      tokenVariableMap.getVariableInstances();
    }
    return variableInstance;
  }

  public Map getTokenVariableMaps() {
    return tokenVariableMaps;
  }

  public List getUpdatedVariableContainers() {
    return updatedVariableContainers;
  }

  void addUpdatedVariableContainer(VariableContainer variableContainer) {
    if (updatedVariableContainers == null) updatedVariableContainers = new ArrayList();
    updatedVariableContainers.add(variableContainer);
  }
}