/*
 * 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.pvm.internal.env;

import java.io.Serializable;
import java.util.Stack;

import org.jbpm.api.JbpmException;
import org.jbpm.api.cmd.Environment;


/**
 * maintains contextual information for a thread in a set of
 * {@link Context}s.
 * 
 * <h3>Introduction</h3>
 * 
 * <p>Objects have different lifecycles and different context's (aka scopes).  An 
 * environment provides the structure to easily manage objects with different 
 * contexts.
 * </p>
 * 
 * <p>Examples of contexts are: 
 * <ul>
 *   <li><b>process-engine</b>: The process-engine context is used to store e.g. data sources,
 *     session factories and other static resources needed by an application.
 *     The process-engine context lives for the complete duration of the {@link EnvironmentFactory}.  
 *     So if the {@link EnvironmentFactory} is maintained in a static member field, the 
 *     process-engine context lives for the duration of the application.
 *     The same process-engine context is shared for all the Environments produced by one 
 *     EnvironmentFactory.</li>
 *   <li><b>environment</b>: The environment context is used for e.g. a transaction 
 *     and transactional resources, user authentication.  This results in an efficient and 
 *     configurable use of transactional resources that need to be lazily initialized.</li>
 *   <li>The environment can accomodate other contexts as well.  They can be added 
 *     and removed dynamically.  Examples of other potential contexts are web-request, web-session, 
 *     web-application, business processDefinition, jobImpl, ... </li>
 * </ul>    
 *      
 * <center><img src="environment.gif"/></center>
 * 
 * <p>An environment is typically installed like this
 * </p>
 * 
 * <b><pre>static EnvironmentFactory environmentFactory = new DefaultEnvironmentFactory();
 * 
 * ...
 * 
 * EnvironmentImpl environment = environmentFactory.openEnvironment();
 * try {
 * 
 *   ... everything available in this block ... 
 * 
 * } finally {
 *   environment.close();
 * }
 * </pre></b>
 *
 * <h3>Purpose</h3>
 * 
 * <p>The first purpose of the environment is to separate the application from the 
 * environment.  Standard Java and Enterprise Java are quite different and an environment 
 * abstraction like this allows for the development of applications that can run in 
 * both Standard and Enterprise environments.  Also test environments are easier to 
 * tweak this way. 
 * </p>
 * 
 * <p>A second purpose of the environment is to enable specific to global searching 
 * of resources.  E.g. you could search for an 'adminEmailAddress' in the contexts
 * 'execution', 'transaction' and 'process-engine' in the given order.
 * That way, a global adminEmailAddress can be specified in the process-engine context 
 * and it can be refined in more specific contexts.
 * </p>
 * 
 * <h3>Search order</h3>
 * 
 * <p>To find an object in the environment, a searchOrder can be specified.  A 
 * search order is an sequence that specifies the order in which the contexts should
 * be searched.
 * </p>
 * 
 * <p>The default search order is the inverse sequence of how the contexts are 
 * added to the environment.  This is because in general, we can assume that the 
 * more recent a context was added, the more specific it is. 
 * </p>
 *
 * <h3>Transaction, username and classloader</h3>
 * 
 * <p>Three objects are used so frequently in an environment that they get 
 * special treatment:
 * </p>
 * 
 * <ul>
 *   <li><b>Transaction</b>: an abstraction for marking a transaction with 
 *   setRollbackOnly.</li>
 *   <li><b>Classloader</b>: the current class loader.</li>
 *   <li><b>Username</b>: the name of the currently authenticated user.</li>
 * </ul>
 * 
 * <p>For these special properties, setters are also available.  That is to support 
 * programmatic injection into the environment.  Alternatively, they can be configured
 * in one of the contexts. 
 * </p>
 * 
 * 
 * @see EnvironmentFactory
 * @author Tom Baeyens
 */
public abstract class EnvironmentImpl implements Serializable, Environment {

  /**
   * searches a named object in all the contexts in the default search order. 
   * @return the object if it exists in the environment, <code>null</code> if there is no object with the given name in the environment.
   */
  public abstract Object get(String name);

  /**
   * searches a named object in all the contexts in the given search order.  The given 
   * search order doesn't have to include all contexts.  It can be a subset of the 
   * contexts available. 
   * @param searchOrder list of contexts names. The object will be searched in these contexts, in the given order.
   * @return the object if it exists in the environment, <code>null</code> if there is no object with the given name in the specified searchOrder contexts.
   */
  public abstract Object get(String name, String[] searchOrder);

  /** searches an object based on type.  The search doesn take superclasses of the context elements 
   * into account.
   * @return the first object of the given type or null in case no such element was found.  
   */
  public abstract <T> T get(Class<T> type);

  
  /** searches an object based on type.  The search doesn take superclasses of the context elements 
   * into account.
   * @return the first object of the given type or null in case no such element was found.  
   */
  public abstract <T> T get(Class<T> type, String[] searchOrder);

  /** get the authenticated user id */
  public abstract String getAuthenticatedUserId();
  
  /** set the authenticated user id */
  public abstract void setAuthenticatedUserId(String authenticatedUserId);

  /**
   * closes the EnvironmentImpl by removing all its contexts.
   */
  public abstract void close();

  public abstract Context getContext(String contextName);
  public abstract void setContext(Context context);
  public abstract Context removeContext(Context context);
  public abstract Context removeContext(String contextName);
  
  public abstract ClassLoader getClassLoader();
  public abstract void setClassLoader(ClassLoader classLoader);

  // current environment //////////////////////////////////////////////////////
  /** the current environment is maintained in the currentEnvironment thread local */
  static ThreadLocal<EnvironmentImpl> currentEnvironment = new ThreadLocal<EnvironmentImpl>();

  /** in case of nested environments, the current environment stack maintains the outer environments */
  static ThreadLocal<Stack<EnvironmentImpl>> currentEnvironmentStack = new ThreadLocal<Stack<EnvironmentImpl>>();

  /** gets the most inner open environment. */
  public static EnvironmentImpl getCurrent() {
    return currentEnvironment.get();
  }
  
  public static <T> T getFromCurrent(Class<T> type) {
    return getFromCurrent(type, true);
  }

  public static <T> T getFromCurrent(Class<T> type, boolean required) {
    EnvironmentImpl environment = getCurrent();
    if (environment==null) {
      if (required) {
        throw new JbpmException("no environment to get "+type.getName());
      }
      return null;
    }
    T object = environment.get(type);
    if (object==null) {
      if (required) {
        throw new JbpmException("no "+type.getName()+" in current environment");
      }
      return null;
    }
    return object;
  }

  public static Object getFromCurrent(String name) {
    return getFromCurrent(name, true);
  }

  public static Object getFromCurrent(String name, boolean required) {
    EnvironmentImpl environment = getCurrent();
    if (environment==null) {
      if (required) {
        throw new JbpmException("no environment to get '"+name+"'");
      }
      return null;
    }
    Object object = environment.get(name);
    if (object==null) {
      if (required) {
        throw new JbpmException("no '"+name+"' in current environment");
      }
      return null;
    }
    return object;
  }

  static Stack<EnvironmentImpl> getStack() {
    // lazy initialize the current environment stack
    Stack<EnvironmentImpl> stack = currentEnvironmentStack.get();
    if (stack==null) {
      stack = new Stack<EnvironmentImpl>();
      currentEnvironmentStack.set(stack);
    }
    return stack;
  }


  /** pops the closing context from the stack of current contexts.  This 
   * is the first thing that needs to be done when an environment is closed.
   * @see EnvironmentFactory#push(EnvironmentImpl) */ 
  public static synchronized EnvironmentImpl popEnvironment() {
    EnvironmentImpl popped = currentEnvironment.get();
    currentEnvironment.set(null);
    Stack<EnvironmentImpl> stack = currentEnvironmentStack.get();
    if ( (stack!=null)
         && (! stack.isEmpty())
       ) {
      currentEnvironment.set(stack.pop());
    }
    return popped;
  }

  /** after opening of a new environment succeeded, the environment 
   * must be pushed in the stack of current environments.
   * 
   * @see EnvironmentImpl#pop() */
  public static synchronized void pushEnvironment(EnvironmentImpl environment) {
    EnvironmentImpl current = currentEnvironment.get();
    if (current!=null) {
      getStack().push(current);
    }
    currentEnvironment.set(environment);
  }
}