## Package org.eclipse.ocl

Definition of the extensible environment API for OCL parsing and evaluation.

See:
Description

Interface Summary
Environment<PK,C,O,P,EL,PM,S,COA,SSA,CT,CLS,E>: An Environment stores the variables created while evaluating an OCL expression, including `self`.
Environment.Internal<PK,C,O,P,EL,PM,S,COA,SSA,CT,CLS,E>: An interface that merges the `Environment` and `BasicEnviroment` interfaces that define the behaviour realised in abstract form by `AbstractEnviroment`.
Environment.Lookup<PK,C,O,P>: Optional adapter interface for look-up methods that throw `LookupException`s on abnormal failures (usually ambiguous names).
Environment.Registry: A registry of environments.
EnvironmentFactory<PK,C,O,P,EL,PM,S,COA,SSA,CT,CLS,E>: A factory for creating OCL parser `Environment`s.
EnvironmentFactory.Lookup<PK,C,O,P,EL,PM,S,COA,SSA,CT,CLS,E>: Optional adapter interface for look-up methods that throw `LookupException`s on abnormal failures (usually ambiguous names).
EvaluationEnvironment<C,O,P,CLS,E>: The evaluation environment keeps track of the current values of variables in the evaluation of an OCL expression.
EvaluationEnvironment.Enumerations<EL>: Optional adapter interface for evaluation environments that support additional enumeration evaluation capabilities.
EvaluationVisitor<PK,C,O,P,EL,PM,S,COA,SSA,CT,CLS,E>: A specialized visitor that is used for evaluation an OCL expression by walking its AST.
Query<C,CLS,E>: An OCL constraint or query.
TypeResolver<C,O,P>: Definition of a resolver for the dynamically-generated OCL types based on the types in the user model.

Class Summary
AbstractEnvironment<PK,C,O,P,EL,PM,S,COA,SSA,CT,CLS,E>: A partial implementation of the `Environment` interface providing some useful common behavior for providers of metamodel bindings.
AbstractEnvironmentFactory<PK,C,O,P,EL,PM,S,COA,SSA,CT,CLS,E>: Partial implementation of the `EnvironmentFactory` interface, useful for subclassing to define the OCL binding for a metamodel.
AbstractEvaluationEnvironment<C,O,P,CLS,E>: A partial implementation of the `EvaluationEnvironment` interface, providing some useful common behaviors.
AbstractEvaluationVisitor<PK,C,O,P,EL,PM,S,COA,SSA,CT,CLS,E>: An evaluation visitor implementation for OCL expressions.
AbstractTypeResolver<PK,C,O,P,PM>: A partial implementation of the `TypeResolver` interface, useful for providers of environment implementations to build their type resolvers.
EvaluationVisitorDecorator<PK,C,O,P,EL,PM,S,COA,SSA,CT,CLS,E>: A visitor that decorates another `EvaluationVisitor`, to intercept invocations of the `visitXxx(...)`
LazyExtentMap<CLS,E>: A self-populating map that lazily creates the extent of a class when asked for it.
OCL<PK,C,O,P,EL,PM,S,COA,SSA,CT,CLS,E>: The Façade for parsing and evaluation of OCL documents and constraints.
OCLInput: Encapsulation of an OCL document, which may be obtained from a string or from a stream.

Exception Summary
AmbiguousLookupException: A specialized `LookupException` denoting specifically that the problem is multiple ambiguous results.
InvalidLookupException: A specialized `LookupException` denoting specifically that the problem is a single result that is invalid or otherwise unexpected.
LookupException: Exception indicating a semantic error in looking up a definition, typically resulting from an ambiguity.
ParserException: Exception indicating a failure to parse or validate OCL constraints.
SemanticException: Exception indicating a semantic error in parsing or validating OCL expressions.
SyntaxException: Exception indicating a syntax error in parsing OCL expressions.

## Package org.eclipse.ocl Description

Definition of the extensible environment API for OCL parsing and evaluation.

## Package Specification

This package defines the API for the environments in which OCL expressions are parsed and evaluated, along with the parser façade.

First, and most importantly to users of the OCL parser API, parsing of OCL documents is performed by the `OCL` parser façade. OCL documents are provide as `OCLInput` objects, obtaining their content from a string or a data stream. These documents declare constraints of the following forms in one or more classifier, operation, or property contexts (with optional package context declarations):

- invariant constraints (in classifier context)
- pre-condition, post-condition constraints, and body expressions (in operation context)
- initial value and derivation expressions (in property context)
- additional operation and property definitions (in classifier context)

These constraints are defined within the context of a particular `OCL` instance; thus the `OCL` defines a root environment. Disparate sets of constraints (including additional operations and properties) may be defined in multiple different `OCL`s. The constraints and `OCLExpression`s parsed by an `OCL` may be checked (in the case of constraints) or evaluated (in the case of expressions) by the `OCL` on a context element, an instance of the metamodel supported by that `OCL`'s environment factory.

The `OCLHelper` interface provides a convenient API for parsing constraints and query expressions on a finer granularity than the document. It is particularly convenient for parsing end evaluating constraints that are embedded in models, in which the context is usually defined by the placement of the constraint. The OCL helper also provides content-assist (expression completion) facilities.

The `Environment` interface describes the environment in which an OCL expression is parsed. The environment provides two major functions to the parser:

- Name resolution: the parser looks up in its current environment names that it finds in an expression. These include package, classifier, attribute, reference, operation, and variable names. Nested environments define nested scopes, to support shadowing of names (e.g., operation parameters or `let` variables that hide attributes of the context classifier)
- Tracking the context: the environment defines an optional package context, a mandatory classifier context, and (for feature constraints) an operation or property context. An feature context is implemented as a child environment of a classifier context; this allows for definition of constraints on operations in a different classifier context than the classifier that defines the operation
- Metamodel introspection: because the OCL parser API is generic, targeting any EMF-based metamodel that defines UML-like semantics, the environment API also provides the introspection facilities required by the parser to distinguish different kinds of classifiers, to determine the generalization relationships between them, obtain the types of properties, etc.

Environments are created by environment factories. An `EnvironmentFactory` is provided to an `OCL` to create environments when it needs to. Environment factories are the starting point for plugging an EMF-based metamodel into the parser framework. The environments that they create provide the bindings for the generic types representing the UML concepts required by OCL, and perform introspection of the particular metamodel. Abstract partial implementations of the factory and environment are provided and may be extended by clients to support their metamodels. Existing concrete implementations of the environment API may be found in the `org.eclipse.ocl.ecore` package (for the OCL binding to Ecore) and the `org.eclipse.ocl.uml` package (for the OCL binding to UML).

While the `Environment` class provides a parse-time environment, the `EvaluationEnvironment` keeps track of the current values of variables in the evaluation of an OCL expression. It also implements the metamodel-specific mechanisms for invoking operations, navigating properties, etc. The `EnvironmentFactory` is responsible for constructing `EvaluationEnvironment`s. For evaluating OCL constraints, the `EvaluationVisitor` walks the AST (parsed representation of an OCL expression), using the evaluation environment to compute values. The `AbstractEnvironmentFactory` creates a useful default implementation of the evaluation visitor, which supports any metamodel binding. The behavior of this default implementation may be modified as need by custom environment factories, by wrapping it with a custom visitor.

See Also:
  `OCL`, `EnvironmentFactory`, `Environment`, `org.eclipse.ocl.helper`

Copyright 2002, 2007 IBM Corporation and others. All Rights Reserved.