## org.eclipse.ocl
Interface Environment<PK,C,O,P,EL,PM,S,COA,SSA,CT,CLS,E>

Type Parameters:
  `PK` - is substituted by the metaclass representing the metamodel's analogue for the UML 2.x `Package`
  `C` - corresponds to the UML `Classifier` metaclass
  `O` - corresponds to the UML `Operation` metaclass
  `P` - corresponds to the UML `Property` metaclass
  `EL` - corresponds to the UML `EnumerationLiteral` metaclass (`Enumeration`s are simply represented as classifiers)
  `PM` - corresponds to the UML `Parameter` metaclass
  `S` - corresponds to the UML `State` metaclass (for metamodels that describe state machines)
  `COA` - corresponds to the UML `CallOperationAction` metaclass (used in message expressions)
  `SSA` - corresponds to the UML `SendSignalAction` metaclass (used in message expressions)
  `CT` - corresponds to the UML `Constraint` metaclass
  `CLS` - corresponds to the UML `Class` metaclass
  `E` - corresponds to the UML `Element` metaclass

All Known Subinterfaces:
  Environment.Internal<PK,C,O,P,EL,PM,S,COA,SSA,CT,CLS,E>

All Known Implementing Classes:
  AbstractEnvironment, CompatibilityEnvironment, EcoreEnvironment

    public interface 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`. It also maintains the context classifier and, if appropriate, operation or property. This interface is not typically used by clients of the parser API, but by providers of bindings for particular UML-like metamodels.

The generic type parameters of this interface represent the UML concepts that the OCL parser and evaluation engine require. A binding for a particular metamodel (e.g., Ecore or UML) is implemented as a concrete `Environment` with appropriate metaclasses substituting for these type parameters.

This interface is not intended to be implemented "directly" by providers of metamodel bindings. It is highly recommended to extend the `AbstractEnvironment` class, instead.

Since 1.2, the default abstract implementation of this interface (`AbstractEnvironment`) implements the `Adaptable` protocol to provide dynamic interface adapters. Use the `OCLUtil.getAdapter(Environment, Class)` method to obtain adapters for any environment instance.

See Also:
  `AbstractEnvironment`, `EnvironmentFactory`

Nested Class Summary
`static interface` `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`.
`static interface` `Environment.Lookup<PK,C,O,P>` Optional adapter interface for look-up methods that throw `LookupException`s on abnormal failures (usually ambiguous names).
`static interface` `Environment.Registry` A registry of environments.

Field Summary
`static String` `OCL_NAMESPACE_URI` Namespace URI of the OCL core metamodel, used for example as the source of certain Ecore annotations.
`static String` `RESULT_VARIABLE_NAME` The name of the operation result variable 'result'.
`static String` `SELF_VARIABLE_NAME` The name of the context variable 'self'.

Method Summary
`boolean` `addElement(String name, Variable<C,PM> elem, boolean explicit)` Adds a variable declaration to the environment.
`P` `defineAttribute(C owner, Variable<C,PM> variable, CT constraint)` In processing an additional attribute definition, constructs the property and associates it with its definition constraint.
`O` `defineOperation(C owner, String name, C type, List<Variable<C,PM>> params, CT constraint)` In processing an additional operation definition, constructs the operation and associates it with its definition constraint.
`void` `deleteElement(String name)` Removes a variable when it goes out of scope.
`List<P>` `getAdditionalAttributes(C classifier)` Obtains the additional attributes defined in this environment in the context of the specified classifier.
`List<O>` `getAdditionalOperations(C classifier)` Obtains the additional operations defined in this environment in the context of the specified classifier.
`CT` `getBodyCondition(O operation)` Obtains an operation's body condition constraint.
`C` `getContextClassifier()` Obtains the context classifier of this environment.
`O` `getContextOperation()` Obtains the context operation of this environment, if it is an operation context.
`PK` `getContextPackage()` Obtains my context package, if any.
`P` `getContextProperty()` Obtains the context property of this environment, if it is a property context.
`CT` `getDefinition(Object feature)` Obtains the definition constraint of the specified feature, if it is an additional attribute or operation defined via an OCL constraint.
`CT` `getDeriveConstraint(P property)` Obtains a property's derived-value constraint.
`EnvironmentFactory<PK,C,O,P,EL,PM,S,COA,SSA,CT,CLS,E>` `getFactory()` Obtains the factory that created me, or an appropriate default factory if I was not created using a factory.
`CT` `getInitConstraint(P property)` Obtains a property's with an initial-value constraint, if any.
`OCLFactory` `getOCLFactory()` Obtains a factory for the creation of types that are parameterized by model elements.
`OCLStandardLibrary<C>` `getOCLStandardLibrary()` Obtains the collection of core types representing the OCL Standard Library.
`Environment<PK,C,O,P,EL,PM,S,COA,SSA,CT,CLS,E>` `getParent()` Obtains my parent environment, if I have one.
`Variable<C,PM>` `getSelfVariable()` Gets the self variable, looking it up in a parent environment if necessary.
`List<S>` `getStates(C owner, List<String> pathPrefix)` Retrieves a list of all possible states of the specified `owner` whose paths are prefixed by the specified partial name.
`TypeResolver<C,O,P>` `getTypeResolver()` Obtains a type resolver to be used to create (and cache) concrete bindings for the generic OCL types, based on the user model types provided by this environment.
`UMLReflection<PK,C,O,P,EL,PM,S,COA,SSA,CT>` `getUMLReflection()` Obtains a utility for for reflection on the UML metaclasses that are used by the OCL abstract syntax.
`Collection<Variable<C,PM>>` `getVariables()` Returns the `Variable`s registered explicitly in me and any parents that I may have.
`boolean` `isEmpty()` Queries whether the environment has any local variables defined in it.
`boolean` `isInPostcondition(OCLExpression<C> exp)` Checks whether the specified OCL expression is in an operation postcondition constraint.
`Variable<C,PM>` `lookup(String name)` Obtains the `Variable` bound to a variable name.
`C` `lookupAssociationClassReference(C owner, String name)` Finds a reference in the specified class to the named association class.
`C` `lookupClassifier(List<String> names)` Finds the classifier identified by the specified sequence of names (a qualified name).
`Variable<C,PM>` `lookupImplicitSourceForAssociationClass(String name)` Return an implicit variable that references the named association class.
`Variable<C,PM>` `lookupImplicitSourceForOperation(String name, List<? extends TypedElement<C>> args)` Return an implicit variable declaration that defines the specified operation signature.
`Variable<C,PM>` `lookupImplicitSourceForProperty(String name)` Return the most appropriate matching variable to use as the implicit source of a call to the specified property.
`Variable<C,PM>` `lookupImplicitSourceForSignal(String name, List<? extends TypedElement<C>> args)` Return an implicit variable declaration that defines the specified signal reception signature.
`Variable<C,PM>` `lookupImplicitSourceForState(List<String> path)` Finds the best-matching implicit variable to use as a source for the unqualified `oclIsInState()` invocation with the specified state qualified name path.
`Variable<C,PM>` `lookupLocal(String name)` Obtains the `Variable` bound to a local variable name.
`O` `lookupOperation(C owner, String name, List<? extends TypedElement<C>> args)` Find an operation in the specified class.
`PK` `lookupPackage(List<String> names)` Finds the package identified by the specified sequence of names (a qualified name).
`P` `lookupProperty(C owner, String name)` Finds a property defined or inherited by the specified classifier.
`C` `lookupSignal(C owner, String name, List<? extends TypedElement<C>> args)` Finds a received signal in the specified classifier.
`S` `lookupState(C owner, List<String> path)` Finds the state identified by the specified qualified name path, to resolve an `oclIsInState()` operation.
`void` `setBodyCondition(O operation, CT constraint)` Associates an operation with an body condition constraint.
`void` `setDeriveConstraint(P property, CT constraint)` Associates a property with an derived-value constraint.
`void` `setInitConstraint(P property, CT constraint)` Associates a property with an initial-value constraint.
`void` `setParent(Environment<PK,C,O,P,EL,PM,S,COA,SSA,CT,CLS,E> env)` Sets my parent environment.
`void` `setSelfVariable(Variable<C,PM> var)` Sets the "self" variable that is the implicit source of any property, operation, or association class call.
`void` `undefine(Object feature)` Removes the definition of an additional operation or property.

Field Detail

### OCL_NAMESPACE_URI

    static final String OCL_NAMESPACE_URI

  Namespace URI of the OCL core metamodel, used for example as the source of certain Ecore annotations.

  See Also:
    Constant Field Values

### SELF_VARIABLE_NAME

    static final String SELF_VARIABLE_NAME

  The name of the context variable 'self'.

  See Also:
    Constant Field Values

### RESULT_VARIABLE_NAME

    static final String RESULT_VARIABLE_NAME

  The name of the operation result variable 'result'.

  See Also:
    Constant Field Values

Method Detail

### getFactory

    EnvironmentFactory<PK,C,O,P,EL,PM,S,COA,SSA,CT,CLS,E> getFactory()

  Obtains the factory that created me, or an appropriate default factory if I was not created using a factory. This factory can be used to create nested environments within me.

  Returns:
    my originating factory
  See Also:
    `EnvironmentFactory.createEnvironment(Environment)`

### getParent

    Environment<PK,C,O,P,EL,PM,S,COA,SSA,CT,CLS,E> getParent()

  Obtains my parent environment, if I have one. My parent environment implements a nesting scope of variable names, some of which names may be shadowed by variables in my scope.

  Returns:
    my parent, or `null` if I am a root environment

### setParent

    void setParent(Environment<PK,C,O,P,EL,PM,S,COA,SSA,CT,CLS,E> env)

  Sets my parent environment. The parent environment should not generally be set to `null` if it was not already `null`.

  Parameters:
    `env` - my new parent environment

### getContextPackage

    PK getContextPackage()

  Obtains my context package, if any. The constraints in an OCL document need not declare a package context, but it is at least implicit as the nearest package containing the context classifier.

  Returns:
    my context package
  See Also:
    `getContextClassifier()`

### getContextClassifier

    C getContextClassifier()

  Obtains the context classifier of this environment. This is the type of the `self` context variable.

  Returns:
    the context classifier

### getContextOperation

    O getContextOperation()

  Obtains the context operation of this environment, if it is an operation context.

  Returns:
    the context operation, or `null` if this is not an operation environment

### getContextProperty

    P getContextProperty()

  Obtains the context property of this environment, if it is a property context.

  Returns:
    the context property, or `null` if this is not a property environment

### getOCLStandardLibrary

    OCLStandardLibrary<C> getOCLStandardLibrary()

  Obtains the collection of core types representing the OCL Standard Library. These are the singleton or generic instances of the OCL-defined classifiers such as `OclAny`, `Collection(T)`, etc. Implementers of OCL metamodel bindings are encouraged to share a single instance of the standard library amonst all of the `Environment`s constructed by a particular `EnvironmentFactory`.

  Returns:
    the OCL Standard Library implementation for this environment

### getTypeResolver

    TypeResolver<C,O,P> getTypeResolver()

  Obtains a type resolver to be used to create (and cache) concrete bindings for the generic OCL types, based on the user model types provided by this environment. These are the types that are parameterized by particular user model elements: collections of particular classifiers, meta-types for particular classifiers, message types for particular operations or signals, and tuple types.

  Returns:
    the type resolver

### isEmpty

    boolean isEmpty()

  Queries whether the environment has any local variables defined in it.

  Returns:
    `true` if no local variables are defined; `false`, otherwise

### lookupLocal

    Variable<C,PM> lookupLocal(String name)

  Obtains the `Variable` bound to a local variable name. Does not look in parent environment scopes.

  Parameters:
    `name` - a variable name to look up
  Returns:
    the matching variable, or `null` if not found in this particular environment

### lookup

    Variable<C,PM> lookup(String name)

  Obtains the `Variable` bound to a variable name. Looks in parent environment scopes (recursively) for variables not found in the local scope.

  Parameters:
    `name` - a variable name to look up
  Returns:
    the matching variable, or `null` if not found in this particular environment

### lookupPackage

    PK lookupPackage(List<String> names)

  Finds the package identified by the specified sequence of names (a qualified name).

  Parameters:
    `names` - the qualified name
  Returns:
    the matching package, or `null` if not found

### lookupClassifier

    C lookupClassifier(List<String> names)

  Finds the classifier identified by the specified sequence of names (a qualified name).

  Parameters:
    `names` - the qualified name
  Returns:
    the matching classifier, or `null` if not found

### lookupOperation

    O lookupOperation(C owner,
                      String name,
                      List<? extends TypedElement<C>> args)

  Find an operation in the specified class. Used to resolve operation calls.

  Parameters:
    `owner` - the owner type of the called operation, or `null` to find an implicit owner type (in iteration expressions)
    `name` - the name of the called operation
    `args` - the arguments (expressions or variables) to be matched against the parameter signature of the operation
  Returns:
    the matching operation, or `null` if not found

### lookupProperty

    P lookupProperty(C owner,
                     String name)

  Finds a property defined or inherited by the specified classifier.

  Parameters:
    `owner` - the owner of the property that we are looking for, or `null` to find an implicit owner type (in iteration expressions)
    `name` - the property name
  Returns:
    the property, or `null` if it could not be found

### lookupAssociationClassReference

    C lookupAssociationClassReference(C owner,
                                      String name)

  Finds a reference in the specified class to the named association class.

  Parameters:
    `owner` - the referencing class to search, or `null` to find an implicit owner type (in iteration expressions)
    `name` - the association class name (with an initial lower case as per the OCL convention)
  Returns:
    the association class (generically as a classifier), or `null` if the specified `owner` is not at the end of an association with this particular name

### lookupState

    S lookupState(C owner,
                  List<String> path)
                  throws LookupException,
                         SemanticException

  Finds the state identified by the specified qualified name path, to resolve an `oclIsInState()` operation.

  Parameters:
    `owner` - the type on which the `oclIsInState()` operation is invoked
    `path` - the state name to seek
  Returns:
    the matching state object, or `null` if not found
  Throws:
    `LookupException` - in the case that this `path` is ambiguous; i.e., that it does not qualify a state reference with the state machine name to select between same-named states in different state machines
    `SemanticException` - which usually would actually be a `LookupException` (see above)

### getStates

    List<S> getStates(C owner,
                      List<String> pathPrefix)

  Retrieves a list of all possible states of the specified `owner` whose paths are prefixed by the specified partial name. If the owner is `null`, then the target of the `oclIsInState()` operation call is implicit and must be looked up in the usual way for implicit operation call targets. This method is used for content-assist.

  Parameters:
    `owner` - the classifier for which states are being sought. Can be `null` in the case of an `oclIsInState()` call on an implicit target
    `pathPrefix` - partial path name of the states being sought. This can be empty to find the first level of state names
  Returns:
    the list of all possible states directly contained in the namespace indicated by the path prefix (i.e., only one level of state nesting)

### lookupSignal

    C lookupSignal(C owner,
                   String name,
                   List<? extends TypedElement<C>> args)

  Finds a received signal in the specified classifier.

  Parameters:
    `owner` - the owner type of the signal reception
    `name` - the name of the signal
    `args` - the arguments (expressions or variables) matching the properties of the signal (parameters of the reception feature)
  Returns:
    the matching signal, or `null` if not found

### isInPostcondition

    boolean isInPostcondition(OCLExpression<C> exp)

  Checks whether the specified OCL expression is in an operation postcondition constraint. This is used in validating the usage of constructs that are only valid in postconditions (e.g., `oclIsNew()`).

  Parameters:
    `exp` - an OCL expression
  Returns:
    `true` if it is in a postcondition constraint; `false`, otherwise (including case of no constraint at all)

### addElement

    boolean addElement(String name,
                       Variable<C,PM> elem,
                       boolean explicit)

  Adds a variable declaration to the environment. If the name is null, then a new unique temporary name is generated (this is useful for implicit variables).

  Parameters:
    `name` - the name of the variable, or `null`
    `elem` - a variable declaration
    `explicit` - whether this is an explicitly declared variable
  Returns:
    `true` if the variable was successfully added because it wasn't already declared locally in this environment; `false`, otherwise

### deleteElement

    void deleteElement(String name)

  Removes a variable when it goes out of scope.

  Parameters:
    `name` - the name of the variable to delete

### getVariables

    Collection<Variable<C,PM>> getVariables()

  Returns the `Variable`s registered explicitly in me and any parents that I may have. This does not include implicit variables or variables from parent environments that are shadowed by variables in the nested scope.

  Returns:
    my variable declarations

### setSelfVariable

    void setSelfVariable(Variable<C,PM> var)

  Sets the "self" variable that is the implicit source of any property, operation, or association class call.

  Parameters:
    `var` - the "self" variable

### getSelfVariable

    Variable<C,PM> getSelfVariable()

  Gets the self variable, looking it up in a parent environment if necessary.

  Returns:
    the self variable, or `null` if none (which should only be the case in a root environment having only a package context, if even that)

### lookupImplicitSourceForProperty

    Variable<C,PM> lookupImplicitSourceForProperty(String name)

  Return the most appropriate matching variable to use as the implicit source of a call to the specified property. Variables are returned based on inner-most scope first.

  Parameters:
    `name` - the property name
  Returns:
    the matching variable, or `null` if no appropriate variable can be found whose type defines a property of this name

### lookupImplicitSourceForAssociationClass

    Variable<C,PM> lookupImplicitSourceForAssociationClass(String name)

  Return an implicit variable that references the named association class. Variables are returned based on inner-most scope first.

  Parameters:
    `name` - the association class name to seek
  Returns:
    the matching variable, or `null` if no appropriate variable can be found whose type defines a property of this name

### lookupImplicitSourceForOperation

    Variable<C,PM> lookupImplicitSourceForOperation(String name,
                                                    List<? extends TypedElement<C>> args)

  Return an implicit variable declaration that defines the specified operation signature. Variables are returned based on inner-most scope first.

  Parameters:
    `name` - the operation name
    `args` - the list of arguments (expressions or variables) to match against the operation parameters
  Returns:
    the matching variable, or `null` if no appropriate variable can be found whose type defines a property of this name

### lookupImplicitSourceForSignal

    Variable<C,PM> lookupImplicitSourceForSignal(String name,
                                                 List<? extends TypedElement<C>> args)

  Return an implicit variable declaration that defines the specified signal reception signature. Variables are returned based on inner-most scope first.

  Parameters:
    `name` - the signal name
    `args` - the list of arguments (expressions or variables) to match against the signal reception parameters
  Returns:
    the matching variable, or `null` if no appropriate variable can be found whose type defines a property of this name

### lookupImplicitSourceForState

    Variable<C,PM> lookupImplicitSourceForState(List<String> path)
                                                throws LookupException,
                                                       SemanticException

  Finds the best-matching implicit variable to use as a source for the unqualified `oclIsInState()` invocation with the specified state qualified name path.

  Parameters:
    `path` - the state name to seek
  Returns:
    the implicit variable having the specified state, or `null` if not found
  Throws:
    `LookupException` - in the case that this `path` is ambiguous; i.e., that it does not qualify a state reference with the state machine name to select between same-named states in different state machines
    `SemanticException` - which usually would actually be a `LookupException` (see above)

### defineAttribute

    P defineAttribute(C owner,
                      Variable<C,PM> variable,
                      CT constraint)

  In processing an additional attribute definition, constructs the property and associates it with its definition constraint. The operation definition is local to this environment.

  Parameters:
    `owner` - the context classifier of the property definition constraint
    `variable` - the name and type of the property (conveniently encapsulated in a variable)
    `constraint` - the definition constraint
  Returns:
    the defined property

### getAdditionalAttributes

    List<P> getAdditionalAttributes(C classifier)

  Obtains the additional attributes defined in this environment in the context of the specified classifier.

  Parameters:
    `classifier` - a classifier
  Returns:
    its additional attributes, or an empty list if none

### defineOperation

    O defineOperation(C owner,
                      String name,
                      C type,
                      List<Variable<C,PM>> params,
                      CT constraint)

  In processing an additional operation definition, constructs the operation and associates it with its definition constraint. The operation definition is local to this environment.

  Parameters:
    `owner` - the context classifier of the property definition constraint
    `name` - the operation name
    `params` - the names and types of the parameters, if any (conveniently encapsulated in variables)
    `constraint` - the definition constraint
  Returns:
    the defined operation

### getAdditionalOperations

    List<O> getAdditionalOperations(C classifier)

  Obtains the additional operations defined in this environment in the context of the specified classifier.

  Parameters:
    `classifier` - a classifier
  Returns:
    its additional operations, or an empty list if none

### getDefinition

    CT getDefinition(Object feature)

  Obtains the definition constraint of the specified feature, if it is an additional attribute or operation defined via an OCL constraint.

  Parameters:
    `feature` - a property or operation
  Returns:
    the definition constraint that defines it, or `null` if this feature is not defined by OCL

### undefine

    void undefine(Object feature)

  Removes the definition of an additional operation or property.

  Parameters:
    `feature` - an additional property or operation
  Throws:
    `IllegalArgumentException` - if the specified `feature` is not an additional feature defined via an OCL constraint

### setInitConstraint

    void setInitConstraint(P property,
                           CT constraint)

  Associates a property with an initial-value constraint. The constraint is local to this environment.

  Parameters:
    `property` - an attribute
    `constraint` - its initial-value constraint

### getInitConstraint

    CT getInitConstraint(P property)

  Obtains a property's with an initial-value constraint, if any.

  Parameters:
    `property` - an attribute
  Returns:
    its initial-value constraint, or `null` if none

### setDeriveConstraint

    void setDeriveConstraint(P property,
                             CT constraint)

  Associates a property with an derived-value constraint. The constraint is local to this environment.

  Parameters:
    `property` - an attribute
    `constraint` - its derived-value constraint

### getDeriveConstraint

    CT getDeriveConstraint(P property)

  Obtains a property's derived-value constraint.

  Parameters:
    `property` - an attribute
  Returns:
    its derived-value constraint

### setBodyCondition

    void setBodyCondition(O operation,
                          CT constraint)

  Associates an operation with an body condition constraint. The constraint is local to this environment.

  Parameters:
    `operation` - an operation
    `constraint` - its body condition constraint

### getBodyCondition

    CT getBodyCondition(O operation)

  Obtains an operation's body condition constraint.

  Parameters:
    `operation` - an operation
  Returns:
    its body condition constraint

### getOCLFactory

    OCLFactory getOCLFactory()

  Obtains a factory for the creation of types that are parameterized by model elements. This type factory must create types that are instances of the metaclass describing classifiers in the client metamodel.

  Returns:
    the appropriate type factory

### getUMLReflection

    UMLReflection<PK,C,O,P,EL,PM,S,COA,SSA,CT> getUMLReflection()

  Obtains a utility for for reflection on the UML metaclasses that are used by the OCL abstract syntax.

  Returns:
    the appropriate reflection instance

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