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 (Enumerations 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, EcoreEnvironment, UMLEnvironment

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 LookupExceptions 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 Variables 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 Environments 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 Variables 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.