org.eclipse.ocl.examples.pivot
Interface Environment

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 Superinterfaces:
Adaptable, BasicEnvironment, Customizable
All Known Implementing Classes:
AbstractEnvironment, OCLVMEnvironment, PivotEnvironment

public interface Environment
extends BasicEnvironment

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.

Author:
Edith Schonberg (edith), Christian W. Damus (cdamus)
See Also:
AbstractEnvironment, EnvironmentFactory

Nested Class Summary
static interface Environment.Registry
          A registry of environments.
 
Field Summary
static java.lang.String OCL_NAMESPACE_URI
          Namespace URI of the OCL core metamodel, used for example as the source of certain Ecore annotations.
static java.lang.String RESULT_VARIABLE_NAME
          The name of the operation result variable 'result'.
static java.lang.String SELF_VARIABLE_NAME
          The name of the context variable 'self'.
 
Method Summary
 boolean addElement(java.lang.String name, Variable elem, boolean explicit)
          Adds a variable declaration to the environment.
 void dispose()
          Disposes of any objects that I have created that should be cleaned up.
 Type getContextClassifier()
          Obtains the context classifier of this environment.
 Operation getContextOperation()
          Obtains the context operation of this environment, if it is an operation context.
 Package getContextPackage()
          Obtains my context package, if any.
 Property getContextProperty()
          Obtains the context property of this environment, if it is a property context.
 Constraint getDefinition(java.lang.Object feature)
          Obtains the definition constraint of the specified feature, if it is an additional attribute or operation defined via an OCL constraint.
 EnvironmentFactory getFactory()
          Obtains the factory that created me, or an appropriate default factory if I was not created using a factory.
 MetaModelManager getMetaModelManager()
           
 PivotFactory getOCLFactory()
          Obtains a factory for the creation of types that are parameterized by model elements.
 DomainStandardLibrary getOCLStandardLibrary()
          Obtains the collection of core types representing the OCL Standard Library.
 Environment getParent()
          Obtains my parent environment, if I have one.
 Variable getSelfVariable()
          Gets the self variable, looking it up in a parent environment if necessary.
 java.util.List<State> getStates(Type owner, java.util.List<java.lang.String> pathPrefix)
          Retrieves a list of all possible states of the specified owner whose paths are prefixed by the specified partial name.
 void setSelfVariable(Variable var)
          Sets the "self" variable that is the implicit source of any property, operation, or association class call.
 
Methods inherited from interface org.eclipse.ocl.examples.pivot.Adaptable
getAdapter
 
Methods inherited from interface org.eclipse.ocl.examples.pivot.Customizable
clearOptions, getOptions, getValue, isEnabled, putOptions, removeOption, removeOptions, setOption
 

Field Detail

OCL_NAMESPACE_URI

@NonNull
static final java.lang.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

@NonNull
static final java.lang.String SELF_VARIABLE_NAME
The name of the context variable 'self'.

See Also:
Constant Field Values

RESULT_VARIABLE_NAME

@NonNull
static final java.lang.String RESULT_VARIABLE_NAME
The name of the operation result variable 'result'.

See Also:
Constant Field Values
Method Detail

dispose

void dispose()
Disposes of any objects that I have created that should be cleaned up.


getFactory

@NonNull
EnvironmentFactory 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

@Nullable
Environment 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

getContextPackage

@Nullable
Package 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

@Nullable
Type getContextClassifier()
Obtains the context classifier of this environment. This is the type of the self context variable.

Returns:
the context classifier

getContextOperation

@Nullable
Operation 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

@Nullable
Property 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

@NonNull
DomainStandardLibrary 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

getMetaModelManager

@NonNull
MetaModelManager getMetaModelManager()

getStates

@NonNull
java.util.List<State> getStates(@NonNull
                                        Type owner,
                                        @NonNull
                                        java.util.List<java.lang.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)

addElement

boolean addElement(@NonNull
                   java.lang.String name,
                   @NonNull
                   Variable 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

setSelfVariable

void setSelfVariable(@NonNull
                     Variable var)
Sets the "self" variable that is the implicit source of any property, operation, or association class call.

Parameters:
var - the "self" variable

getSelfVariable

@Nullable
Variable 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)

getDefinition

Constraint getDefinition(@NonNull
                         java.lang.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

getOCLFactory

@NonNull
PivotFactory 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