org.eclipse.ocl
Interface EvaluationEnvironment<C,O,P,CLS,E>

All Known Implementing Classes:
AbstractEvaluationEnvironment, EcoreEvaluationEnvironment, UMLEvaluationEnvironment

public interface EvaluationEnvironment<C,O,P,CLS,E>

The evaluation environment keeps track of the current values of variables in the evaluation of an OCL expression. It also knows how to navigate properties and association classes, etc. in M0 instances described by models conformant to the metamodel supported by the environment implementation.

See the Environment class for a description of the generic type parameters of this class.

As of the 1.2 release, evaluation environments are encouraged to implement the Adaptable interface to provide optional interfaces such as Customizable for specifying evaluation options. Moreover, the (AbstractEvaluationEnvironment) class implements the Adaptable protocol. Use the OCLUtil.getAdapter(EvaluationEnvironment, Class) method to obtain adapters for any evaluation environment instance.


Nested Class Summary
static interface EvaluationEnvironment.Enumerations<EL>
          Optional adapter interface for evaluation environments that support additional enumeration evaluation capabilities.
 
Method Summary
 void add(java.lang.String name, java.lang.Object value)
          Adds the supplied name and value binding to the environment.
 java.lang.Object callOperation(O operation, int opcode, java.lang.Object source, java.lang.Object[] args)
          Invokes the specified operation on the given source element, according to the particular metamodel semantics.
 void clear()
          Clears the environment of variables.
 java.util.Map<CLS,java.util.Set<E>> createExtentMap(java.lang.Object object)
          Creates an extent map for invocation of OclType.allInstances() using the specified object as a context from which to find the scope in which OCL classifier extents are defined.
 Tuple<O,P> createTuple(C type, java.util.Map<P,java.lang.Object> values)
          Creates a new tuple instance.
 C getType(java.lang.Object object)
          Queries the type of the specified object.
 java.lang.Object getValueOf(java.lang.String name)
          Returns the value associated with the supplied name
 boolean isKindOf(java.lang.Object object, C classifier)
          Queries whether an object is an instance of the specified classifier or some specialization thereof.
 boolean isTypeOf(java.lang.Object object, C classifier)
          Queries whether an object's type is the specified classifier.
 java.lang.Object navigateAssociationClass(C associationClass, P navigationSource, java.lang.Object source)
          Obtains the instance of the specified association class that links the specified source element, optionally via the specified property.
 java.lang.Object navigateProperty(P property, java.util.List<?> qualifiers, java.lang.Object source)
          Obtains the value of the specified operation, for the given source element, according to the particular metamodel semantics.
 boolean overrides(O operation, int opcode)
          Queries whether this evaluation environment provides a custom implementation of the specified pre-defined OCL operation.
 java.lang.Object remove(java.lang.String name)
          Removes the supplied name and binding from the environment (if it exists) and returns it.
 void replace(java.lang.String name, java.lang.Object value)
          Replaces the current value of the supplied name with the supplied value.
 

Method Detail

getValueOf

java.lang.Object getValueOf(java.lang.String name)
Returns the value associated with the supplied name

Parameters:
name - the name whose value is to be returned
Returns:
the value associated with the name

replace

void replace(java.lang.String name,
             java.lang.Object value)
Replaces the current value of the supplied name with the supplied value.

Parameters:
name - the name
value - the new value

add

void add(java.lang.String name,
         java.lang.Object value)
Adds the supplied name and value binding to the environment. The name must not already be bound.

Parameters:
name - the name to add
value - the associated binding
See Also:
replace(String, Object)

remove

java.lang.Object remove(java.lang.String name)
Removes the supplied name and binding from the environment (if it exists) and returns it.

Parameters:
name - the name to remove
Returns:
the value associated with the removed name

clear

void clear()
Clears the environment of variables.


overrides

boolean overrides(O operation,
                  int opcode)
Queries whether this evaluation environment provides a custom implementation of the specified pre-defined OCL operation. In the case that the receiver does, then it must implement the callOperation(O, int, java.lang.Object, java.lang.Object[]) method to apply the operation.

Parameters:
operation - an OCL operation
opcode - the operation code, if one of the operations pre-defined by OCL. Otherwise, -1
Returns:
true if this evaluation environment provides an implementation of this operation; false, otherwise
See Also:
callOperation(O, int, java.lang.Object, java.lang.Object[])

callOperation

java.lang.Object callOperation(O operation,
                               int opcode,
                               java.lang.Object source,
                               java.lang.Object[] args)
                               throws java.lang.IllegalArgumentException
Invokes the specified operation on the given source element, according to the particular metamodel semantics.

Parameters:
operation - the operation to invoke
opcode - the operation code, if this is an OCL Standard Library operation (which this environment overrides)
source - the source element on which the operation is invoked
args - the arguments, or an empty array if none
Returns:
the result of the operation (the operation necessarily is a query if it is invoked by OCL)
Throws:
java.lang.IllegalArgumentException - if the operation is not supported by this environment

navigateProperty

java.lang.Object navigateProperty(P property,
                                  java.util.List<?> qualifiers,
                                  java.lang.Object source)
                                  throws java.lang.IllegalArgumentException
Obtains the value of the specified operation, for the given source element, according to the particular metamodel semantics.

Parameters:
property - the property to navigate
qualifiers - the association-end qualifier values, or an empty list if none
source - the source element owning the property value
Returns:
the property value
Throws:
java.lang.IllegalArgumentException - if the property is not supported by the element or by this environment

navigateAssociationClass

java.lang.Object navigateAssociationClass(C associationClass,
                                          P navigationSource,
                                          java.lang.Object source)
                                          throws java.lang.IllegalArgumentException
Obtains the instance of the specified association class that links the specified source element, optionally via the specified property.

Parameters:
associationClass - the association class to navigate to
navigationSource - in case of ambiguity, the property of the source element's classifier through which to navigate to the association class
source - the source element from which to navigate
Returns:
the association class instance
Throws:
java.lang.IllegalArgumentException - if the association class is not associated with the source element, or is not supported by this environment

createExtentMap

java.util.Map<CLS,java.util.Set<E>> createExtentMap(java.lang.Object object)
Creates an extent map for invocation of OclType.allInstances() using the specified object as a context from which to find the scope in which OCL classifier extents are defined. This scope may be a resource, resource set, or some metamodel-specific scope. Note that in the case that the object is not an org.eclipse.emf.ecore.EObject but is, instead, some primitive type, then this may be difficult to determine.

Clients are encouraged to do what they can to optimize this mapping, by lazy initialization of key-value pairs, workspace indices, or whatever means is available. Note that the map will only ever be accessed by key (Map.get(java.lang.Object)); it will never be queried for all entries, all keys, all values, etc. This knowledge could help optimization.

Parameters:
object - a context object in the scope that covers the OCL classifier extents
Returns:
the extent map

isKindOf

boolean isKindOf(java.lang.Object object,
                 C classifier)
Queries whether an object is an instance of the specified classifier or some specialization thereof.

Parameters:
object - an object
classifier - a classifier
Returns:
true if the specified classifier is the object's type or some supertype thereof; false, otherwise

isTypeOf

boolean isTypeOf(java.lang.Object object,
                 C classifier)
Queries whether an object's type is the specified classifier.

Parameters:
object - an object
classifier - a classifier
Returns:
true if ths specified classifier is the object's type; false, otherwise

getType

C getType(java.lang.Object object)
Queries the type of the specified object.

Parameters:
object - an object
Returns:
its type

createTuple

Tuple<O,P> createTuple(C type,
                       java.util.Map<P,java.lang.Object> values)
Creates a new tuple instance.

Parameters:
type - the type (a TupleType) of the tuple to be created
values - a mapping of the tuple parts
Returns:
the new tuple instance

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