/*******************************************************************************
 * Copyright (c) 2005, 2010 IBM Corporation and others.
 * All rights reserved.   This program and the accompanying materials
 * are made available under the terms of the Eclipse Public License v1.0
 * which accompanies this distribution, and is available at
 * http://www.eclipse.org/legal/epl-v10.html
 *
 * Contributors:
 *   IBM - Initial API and implementation
 *   E.D.Willink - Refactoring to support extensibility and flexible error handling 
 *   Adolfo Sanchez-Barbudo Herrera (Open Canarias) - Bug 333032
 *******************************************************************************/

package org.eclipse.ocl;

import java.util.List;
import java.util.Map;
import java.util.Set;

import org.eclipse.emf.ecore.resource.Resource;
import org.eclipse.ocl.helper.OCLSyntaxHelper;
import org.eclipse.ocl.parser.AbstractOCLParser;
import org.eclipse.ocl.parser.OCLAnalyzer;
import org.eclipse.ocl.parser.OCLFactoryWithHistory;
import org.eclipse.ocl.types.OCLStandardLibrary;
import org.eclipse.ocl.util.Adaptable;
import org.eclipse.ocl.util.OCLUtil;
import org.eclipse.ocl.utilities.Visitor;

/**
 * A factory for creating OCL parser {@link Environment}s.  Clients of the OCL
 * parser that wish to use OCL with their metamodels can provide the parser
 * a factory that creates the suitable environments.  The environment provides
 * mappings from the client's metamodel to the UML concepts required by the
 * parser (corresponding to the generic type parameters, below).  Many of these
 * mappings are optional (e.g., state machines, signals, and association
 * classes aren't supported by all metamodels).
 * <p>
 * @noimplement This interface is <b>not</b> intended to be implemented to be implemented
 * "directly" by providers of metamodel bindings.
 * It is highly recommended to extend the {@link AbstractEnvironmentFactory}
 * class, instead.
 * </p><p>
 * Since 1.2, the {@link AbstractEnvironmentFactory} implements the
 * {@link Adaptable} interface and provides an adapter for the
 * {@link EnvironmentFactory.Lookup} interface.  Use the
 * {@link OCLUtil#getAdapter(EnvironmentFactory, Class)} method to obtain
 * adapters for any factory instance.
 * </p>
 * 
 * @param <PK> is substituted by the metaclass representing the metamodel's
 *    analogue for the UML 2.x <tt>Package</tt>
 * @param <C> corresponds to the UML <tt>Classifier</tt> metaclass
 * @param <O> corresponds to the UML <tt>Operation</tt> metaclass
 * @param <P> corresponds to the UML <tt>Property</tt> metaclass
 * @param <EL> corresponds to the UML <tt>EnumerationLiteral</tt> metaclass
 *    (<tt>Enumeration</tt>s are simply represented as classifiers)
 * @param <PM> corresponds to the UML <tt>Parameter</tt> metaclass
 * @param <S> corresponds to the UML <tt>State</tt> metaclass (for metamodels
 *    that describe state machines)
 * @param <COA> corresponds to the UML <tt>CallOperationAction</tt> metaclass
 *    (used in message expressions)
 * @param <SSA> corresponds to the UML <tt>SendSignalAction</tt> metaclass
 *    (used in message expressions)
 * @param <CT> corresponds to the UML <tt>Constraint</tt> metaclass
 * @param <CLS> corresponds to the UML <tt>Class</tt> metaclass
 * @param <E> corresponds to the UML <tt>Element</tt> metaclass
 *
 * @author Christian W. Damus (cdamus)
 */
public interface EnvironmentFactory<PK, C, O, P, EL, PM, S, COA, SSA, CT, CLS, E> {
	
	/**
	 * Creates a root environment, in which package contexts and/or classifier
     * contexts will be created as nested environments.  All operation body
     * constraints, attribute initial/derived value constraints, and definitions
     * of additional attributes and operations should be maintained by the root
     * environment, so that they will be accessible from constraints parsed in
     * any nested environment.
	 * 
	 * @return a new root environment
	 */
	Environment<PK, C, O, P, EL, PM, S, COA, SSA, CT, CLS, E>
	createEnvironment();
	
	/**
	 * Creates an environment suitable for parsing OCL expressions in the
	 * specified package context.  This context will become a classifier context
	 * when the {@linkplain Environment#setSelfVariable "self" variable}
	 * is defined.
	 * 
	 * @param pathname the qualified package name (the "::"-separated parts)
	 * @return the environment or null if lookup fails to locate a package
	 * 
	 * @see #createClassifierContext
	 * @see #createOperationContext
     * @see #createAttributeContext
	 */
	Environment<PK, C, O, P, EL, PM, S, COA, SSA, CT, CLS, E>
	createPackageContext(
			Environment<PK, C, O, P, EL, PM, S, COA, SSA, CT, CLS, E> parent,
			List<String> pathname);
	
	/**
	 * Loads an environment from the specified <tt>resource</tt>.  If not
	 * already loaded, this method will load the resource.  This resource will
	 * subsequently be used to persist new OCL constraints, so supplying a new,
	 * empty resource will allow the client to determine where the environment
	 * is persisted.
	 * 
	 * @param resource a resource containing the persisted environment
	 */
	Environment<PK, C, O, P, EL, PM, S, COA, SSA, CT, CLS, E>
	loadEnvironment(Resource resource);
	
	/**
	 * Creates an environment suitable for parsing OCL expressions in the
	 * specified <code>context</code>, which is some classifier
	 * in the client's model.
	 * 
	 * @param context the context classifier
	 * @return the environment
	 * 
	 * @see #createOperationContext(Environment, Object)
     * @see #createAttributeContext(Environment, Object)
     * @see #createInstanceContext(Environment, Object)
	 */
	Environment<PK, C, O, P, EL, PM, S, COA, SSA, CT, CLS, E>
	createClassifierContext(
			Environment<PK, C, O, P, EL, PM, S, COA, SSA, CT, CLS, E> parent,
			C context);
	
    /**
     * Creates an environment suitable for parsing OCL expressions on the
     * specified <code>context</code> object, which is an instance of some
     * classifier in the client's model.
     * <p>
     * The context may be an instance of a model class or a data type value
     * on which an OCL expression would be evaluated.  Note that the actual OCL
     * context classifier (as an OCL type or classifier) will be
     * inferred from the context instance according to the metamodel that the
     * environment factory supports, if possible.  If not possible, then the
     * {@link OCLStandardLibrary#getOclAny() OclAny} type is assumed.
     * </p>
     * 
     * @param context the context object or value
     * @return the environment
     * 
     * @see #createClassifierContext(Environment, Object)
     * @see OCLStandardLibrary#getOclAny()
     */
    Environment<PK, C, O, P, EL, PM, S, COA, SSA, CT, CLS, E>
    createInstanceContext(
            Environment<PK, C, O, P, EL, PM, S, COA, SSA, CT, CLS, E> parent,
            Object context);
    
	/**
	 * Creates an environment suitable for parsing OCL expressions on the
	 * specified <code>operation</code>, which is some operation
	 * in the client's metamodel.  Note that operation contexts can be defined
	 * in the context of any classifier to which that operation is applicable.
	 * 
	 * @param parent the parent environment, defining the classifier context
	 * @param operation an operation in the client's metamodel
	 * @return the environment
	 * 
	 * @see #createClassifierContext(Environment, Object)
	 */
	Environment<PK, C, O, P, EL, PM, S, COA, SSA, CT, CLS, E>
	createOperationContext(
			Environment<PK, C, O, P, EL, PM, S, COA, SSA, CT, CLS, E> parent,
			O operation);
	
	/**
	 * Creates an environment suitable for parsing OCL expressions on the
	 * specified <code>property</code>, which is some attribute
	 * in the client's metamodel.  Note that attribute contexts can be defined
	 * in the context of any classifier in which that attribute is available.
	 * 
     * @param parent the parent environment, defining the classifier context
	 * @param property an attribute in the client's metamodel
	 * @return the environment
	 * 
	 * @see #createClassifierContext(Environment, Object)
	 */
	Environment<PK, C, O, P, EL, PM, S, COA, SSA, CT, CLS, E>
	createAttributeContext(
			Environment<PK, C, O, P, EL, PM, S, COA, SSA, CT, CLS, E> parent,
			P property);
	
	/**
	 * Creates a child environment of a specified <code>parent</code>, for
	 * definition of nested scopes.
	 * 
	 * @param parent the parent environment
	 * @return the child environment
	 */
	Environment<PK, C, O, P, EL, PM, S, COA, SSA, CT, CLS, E>
	createEnvironment(Environment<PK, C, O, P, EL, PM, S, COA, SSA, CT, CLS, E> parent);
	
	/**
	 * Creates a new evaluation environment to track the values of variables in
	 * an OCL expression as it is evaluated.
	 * 
	 * @return a new evaluation environment
	 */
	EvaluationEnvironment<C, O, P, CLS, E> createEvaluationEnvironment();
	
	/**
	 * Creates a new evaluation environment as a nested environment of the
	 * specified <tt>parent</tt>.
	 * 
	 * @param parent a nesting evaluation environment
	 * @return a new nested evaluation environment
	 */
	EvaluationEnvironment<C, O, P, CLS, E> createEvaluationEnvironment(
			EvaluationEnvironment<C, O, P, CLS, E> parent);
	
    /**
     * Creates a new evaluation visitor, for the evaluation of OCL expressions.
     * 
     * @param env the environment in which the expression was originally parsed
     *    (or some compatible environment)
     * @param evalEnv the evaluation environment that the visitor is to use
     *    for tracking variables, navigating properties, etc.
     * @param extentMap the map of <tt>Class</tt>es to their extends
     * @return the new evaluation visitor
     */
	EvaluationVisitor<PK, C, O, P, EL, PM, S, COA, SSA, CT, CLS, E>
	createEvaluationVisitor(
			Environment<PK, C, O, P, EL, PM, S, COA, SSA, CT, CLS, E> env,
			EvaluationEnvironment<C, O, P, CLS, E> evalEnv,
			Map<? extends CLS, ? extends Set<? extends E>> extentMap);

	/**
	 * Creates an instance of the OCLAnalyzer that analyzes the
	 * given input on behalf of this environment.
	 * 
	 * @param input the text to be analyzed
	 * 
	 * @return an OCLAnalyzer instance for this environment
	 * @since 3.1
	 */
	OCLAnalyzer<PK, C, O, P, EL, PM, S, COA, SSA, CT, CLS, E> createOCLAnalyzer(
		Environment<PK, C, O, P, EL, PM, S, COA, SSA, CT, CLS, E> environment, String input);

	/**
	 * Creates an instance of the OCLAnalyzer that will use 
	 * a given parser to perform syntactic and lexical analysis.
	 * 
	 * @param parser performing syntax analysis
	 * 
	 * @return an OCLAnalyzer instance for this environment
	 * @since 3.1
	 */
	OCLAnalyzer<PK, C, O, P, EL, PM, S, COA, SSA, CT, CLS, E> createOCLAnalyzer(
		AbstractOCLParser parser);

	/**
	 * Creates an instance of the OCLFactoryWithHistory object for this environment.
	 * 
	 * @param env an OCL environment (must not be <code>null</code>)
	 * 
	 * @return an OCLFactoryWithHistory instance for this environment
	 * @since 3.1
	 */
	OCLFactoryWithHistory createOCLFactoryWithHistory(
			Environment<PK, C, O, P, EL, PM, S, COA, SSA, CT, CLS, E> env);

	/**
	 * Creates an instance of the OCLSyntaxHelper object for this environment.
	 * 
	 * @param environment an OCL environment (must not be <code>null</code>)
	 * 
	 * @return an OCLSyntaxHelper instance for this environment
	 * @since 3.1
	 */
	OCLSyntaxHelper createOCLSyntaxHelper(
			Environment<PK, C, O, P, EL, PM, S, COA, SSA, CT, CLS, E> environment);

	/**
	 * Obtains an instance of the validation visitor that validates against the
	 * specified environment, which presumably was used in parsing the OCL in
	 * the first place.
	 * 
	 * @param environment an OCL environment (must not be <code>null</code>)
	 * 
	 * @return a validation visitor instance for the specified environment
	 * @since 3.1
	 */
	Visitor<Boolean, C, O, P, EL, PM, S, COA, SSA, CT> createValidationVisitor(
		Environment<PK, C, O, P, EL, PM, S, COA, SSA, CT, CLS, E> environment);
	
	/**
	 * Optional adapter interface for look-up methods that throw
	 * {@link LookupException}s on abnormal failures (usually ambiguous names).
	 * 
	 * @author Christian W. Damus (cdamus)
	 * 
	 * @since 1.2
	 */
	interface Lookup<PK, C, O, P, EL, PM, S, COA, SSA, CT, CLS, E> {
		/**
		 * Creates an environment suitable for parsing OCL expressions in the
		 * specified package context.  This context will become a classifier context
		 * when the {@linkplain Environment#setSelfVariable "self" variable}
		 * is defined.
		 * 
		 * @param pathname the qualified package name (the "::"-separated parts)
		 * @return the environment or null if lookup fails to locate a package
		 * @throws LookupException if package lookup encounters an error such as an ambiguity
		 * 
		 * @see #createClassifierContext
		 * @see #createOperationContext
	     * @see #createAttributeContext
		 */
		Environment<PK, C, O, P, EL, PM, S, COA, SSA, CT, CLS, E>
		tryCreatePackageContext(
				Environment<PK, C, O, P, EL, PM, S, COA, SSA, CT, CLS, E> parent,
				List<String> pathname) throws LookupException;
	}
}