org.eclipse.ocl.EnvironmentFactory Maven / Gradle / Ivy
/**
*
*
* 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
*
*
*
* $Id: EnvironmentFactory.java,v 1.4 2010/12/24 10:18:07 asanchez Exp $
*/
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).
*
* @noimplement This interface is not intended to be implemented to be implemented
* "directly" by providers of metamodel bindings.
* It is highly recommended to extend the {@link AbstractEnvironmentFactory}
* class, instead.
*
* 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.
*
*
* @param is substituted by the metaclass representing the metamodel's
* analogue for the UML 2.x Package
* @param corresponds to the UML Classifier metaclass
* @param corresponds to the UML Operation metaclass
* @param corresponds to the UML Property metaclass
* @param corresponds to the UML EnumerationLiteral metaclass
* (Enumerations are simply represented as classifiers)
* @param corresponds to the UML Parameter metaclass
* @param corresponds to the UML State metaclass (for metamodels
* that describe state machines)
* @param corresponds to the UML CallOperationAction metaclass
* (used in message expressions)
* @param corresponds to the UML SendSignalAction metaclass
* (used in message expressions)
* @param corresponds to the UML Constraint metaclass
* @param corresponds to the UML Class metaclass
* @param corresponds to the UML Element metaclass
*
* @author Christian W. Damus (cdamus)
*/
public interface EnvironmentFactory {
/**
* 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
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
createPackageContext(
Environment parent,
List pathname);
/**
* Loads an environment from the specified resource. 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
loadEnvironment(Resource resource);
/**
* Creates an environment suitable for parsing OCL expressions in the
* specified context, 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
createClassifierContext(
Environment parent,
C context);
/**
* Creates an environment suitable for parsing OCL expressions on the
* specified context object, which is an instance of some
* classifier in the client's model.
*
* 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.
*
*
* @param context the context object or value
* @return the environment
*
* @see #createClassifierContext(Environment, Object)
* @see OCLStandardLibrary#getOclAny()
*/
Environment
createInstanceContext(
Environment parent,
Object context);
/**
* Creates an environment suitable for parsing OCL expressions on the
* specified operation, 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
createOperationContext(
Environment parent,
O operation);
/**
* Creates an environment suitable for parsing OCL expressions on the
* specified property, 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
createAttributeContext(
Environment parent,
P property);
/**
* Creates a child environment of a specified parent, for
* definition of nested scopes.
*
* @param parent the parent environment
* @return the child environment
*/
Environment
createEnvironment(Environment 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 createEvaluationEnvironment();
/**
* Creates a new evaluation environment as a nested environment of the
* specified parent.
*
* @param parent a nesting evaluation environment
* @return a new nested evaluation environment
*/
EvaluationEnvironment createEvaluationEnvironment(
EvaluationEnvironment 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 Classes to their extends
* @return the new evaluation visitor
*/
EvaluationVisitor
createEvaluationVisitor(
Environment env,
EvaluationEnvironment evalEnv,
Map> 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 createOCLAnalyzer(
Environment 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 createOCLAnalyzer(
AbstractOCLParser parser);
/**
* Creates an instance of the OCLFactoryWithHistory object for this environment.
*
* @param environment an OCL environment (must not be null)
*
* @return an OCLFactoryWithHistory instance for this environment
* @since 3.1
*/
OCLFactoryWithHistory createOCLFactoryWithHistory(
Environment env);
/**
* Creates an instance of the OCLSyntaxHelper object for this environment.
*
* @param environment an OCL environment (must not be null)
*
* @return an OCLSyntaxHelper instance for this environment
* @since 3.1
*/
OCLSyntaxHelper createOCLSyntaxHelper(
Environment 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 null)
*
* @return a validation visitor instance for the specified environment
* @since 3.1
*/
Visitor createValidationVisitor(
Environment 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 {
/**
* 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
tryCreatePackageContext(
Environment parent,
List pathname) throws LookupException;
}
}