org.eclipse.ocl
Class OCL<PK,C,O,P,EL,PM,S,COA,SSA,CT,CLS,E>

java.lang.Object
  extended by org.eclipse.ocl.OCL<PK,C,O,P,EL,PM,S,COA,SSA,CT,CLS,E>
Direct Known Subclasses:
OCL, OCL

public class OCL<PK,C,O,P,EL,PM,S,COA,SSA,CT,CLS,E>
extends Object

The Façade for parsing and evaluation of OCL documents and constraints. The OCL is initialized with an environment factory that supports the metamodel of the model to which the OCL constraints are to be applied.

Since 1.2, the helper supplies diagnostics indicating any problems encountered while parsing. The diagnostics pertain always to the most recently executed parse operation.

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

Providers of OCL bindings for metamodels may extend this class for the convenience of their clients, to specify the type parameter substitutions.


Constructor Summary
protected OCL(Environment<PK,C,O,P,EL,PM,S,COA,SSA,CT,CLS,E> env)
          Initializes me with a root environment.
protected OCL(EnvironmentFactory<PK,C,O,P,EL,PM,S,COA,SSA,CT,CLS,E> envFactory)
          Initializes me with an environment factory, which I will use to create a root environment.
protected OCL(EnvironmentFactory<PK,C,O,P,EL,PM,S,COA,SSA,CT,CLS,E> envFactory, Environment<PK,C,O,P,EL,PM,S,COA,SSA,CT,CLS,E> rootEnv)
          Initializes me with my environment factory and root environment.
protected OCL(EnvironmentFactory<PK,C,O,P,EL,PM,S,COA,SSA,CT,CLS,E> envFactory, Resource resource)
          Initializes me with an environment factory and a resource in which my environment is to be persisted, or from which it may be loaded if the resource already has content.
 
Method Summary
 boolean check(Object context, CT constraint)
          Checks whether a constraint is satisfied by an object.
 boolean check(Object context, OCLExpression<C> constraint)
          Checks whether a constraint, specified simply as an OCL expression, is satisfied by an object.
 OCLHelper<C,O,P,CT> createOCLHelper()
          Creates a new OCLHelper instance for convenient parsing of embedded constraints and query expressions in this environment.
 Query<C,CLS,E> createQuery(CT constraint)
          Creates a new Query encapsulating a constraint with the current environment and extent map.
 Query<C,CLS,E> createQuery(OCLExpression<C> query)
          Creates a new Query encapsulating a query expression with the current environment and extent map.
 void dispose()
          Disposes any objects that I have created while I have been in use.
 Object evaluate(Object context, OCLExpression<C> expression)
          Evaluates a query expression on a context object (which is bound to the self variable).
 List<CT> getConstraints()
          Obtains all of the constraints parsed hitherto by this OCL instance.
 Environment<PK,C,O,P,EL,PM,S,COA,SSA,CT,CLS,E> getEnvironment()
          Obtains the OCL parsing environment.
 EvaluationEnvironment<C,O,P,CLS,E> getEvaluationEnvironment()
          Obtains the OCL evaluation environment.
 Map<CLS,? extends Set<? extends E>> getExtentMap()
          Obtains the extent map, if any, provided by the client to customize the evaluation of constraints.
 Diagnostic getProblems()
          Obtains problems, if any, found in parsing the last OCL constraint or query expression.
 boolean isEvaluationTracingEnabled()
          Queries whether tracing of evaluation is enabled.
 boolean isInvalid(Object value)
          Queries whether a value is the special OclInvalid token.
 boolean isParseTracingEnabled()
          Queries whether tracing of parsingis enabled.
static
<PK,C,O,P,EL,PM,S,COA,SSA,CT,CLS,E>
OCL<PK,C,O,P,EL,PM,S,COA,SSA,CT,CLS,E>
newInstance(Environment<PK,C,O,P,EL,PM,S,COA,SSA,CT,CLS,E> env)
          Creates a new OCL on the specified root environment.
static
<PK,C,O,P,EL,PM,S,COA,SSA,CT,CLS,E>
OCL<PK,C,O,P,EL,PM,S,COA,SSA,CT,CLS,E>
newInstance(EnvironmentFactory<PK,C,O,P,EL,PM,S,COA,SSA,CT,CLS,E> envFactory)
          Creates a new OCL with an environment factory, which it will use to create a root environment.
static
<PK,C,O,P,EL,PM,S,COA,SSA,CT,CLS,E>
OCL<PK,C,O,P,EL,PM,S,COA,SSA,CT,CLS,E>
newInstance(EnvironmentFactory<PK,C,O,P,EL,PM,S,COA,SSA,CT,CLS,E> envFactory, Resource resource)
          Creates a new OCL with an environment factory and a resource in which its environment is to be persisted, or from which it may be loaded if the resource already has content.
 List<CT> parse(OCLInput input)
          Parses an OCL document, returning the constraints parsed from it.
 void setEvaluationTracingEnabled(boolean b)
          Sets whether tracing of evaluation is enabled.
 void setExtentMap(Map<CLS,? extends Set<? extends E>> extentMap)
          Assigns a custom extent map to define the extents of classes in evaluation of OCL constraints.
 void setParseTracingEnabled(boolean b)
          Sets whether tracing of parsing is enabled.
 void validate(CT constraint)
          Validates an OCL constraint, which may have been loaded from some resource or constructed via the API (perhaps by translation from some other language).
 void validate(OCLExpression<C> expression)
          Validates an OCL expression, which may have been loaded from some resource or constructed via the API (perhaps by translation from some other language).
 
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 

Constructor Detail

OCL

protected OCL(EnvironmentFactory<PK,C,O,P,EL,PM,S,COA,SSA,CT,CLS,E> envFactory)
Initializes me with an environment factory, which I will use to create a root environment.

Parameters:
envFactory - my environment factory

OCL

protected OCL(Environment<PK,C,O,P,EL,PM,S,COA,SSA,CT,CLS,E> env)
Initializes me with a root environment.

Parameters:
env - my root environment

OCL

protected OCL(EnvironmentFactory<PK,C,O,P,EL,PM,S,COA,SSA,CT,CLS,E> envFactory,
              Resource resource)
Initializes me with an environment factory and a resource in which my environment is to be persisted, or from which it may be loaded if the resource already has content.

Parameters:
envFactory - an environment factory
resource - a resource in which the root environment is persisted

OCL

protected OCL(EnvironmentFactory<PK,C,O,P,EL,PM,S,COA,SSA,CT,CLS,E> envFactory,
              Environment<PK,C,O,P,EL,PM,S,COA,SSA,CT,CLS,E> rootEnv)
Initializes me with my environment factory and root environment.

Parameters:
envFactory - my environment factory
rootEnv - my root environment
Method Detail

newInstance

public static <PK,C,O,P,EL,PM,S,COA,SSA,CT,CLS,E> OCL<PK,C,O,P,EL,PM,S,COA,SSA,CT,CLS,E> newInstance(EnvironmentFactory<PK,C,O,P,EL,PM,S,COA,SSA,CT,CLS,E> envFactory)
Creates a new OCL with an environment factory, which it will use to create a root environment.

Parameters:
envFactory - an environment factory
Returns:
the OCL façade

newInstance

public static <PK,C,O,P,EL,PM,S,COA,SSA,CT,CLS,E> OCL<PK,C,O,P,EL,PM,S,COA,SSA,CT,CLS,E> newInstance(Environment<PK,C,O,P,EL,PM,S,COA,SSA,CT,CLS,E> env)
Creates a new OCL on the specified root environment.

Parameters:
env - the root environment
Returns:
the OCL façade

newInstance

public static <PK,C,O,P,EL,PM,S,COA,SSA,CT,CLS,E> OCL<PK,C,O,P,EL,PM,S,COA,SSA,CT,CLS,E> newInstance(EnvironmentFactory<PK,C,O,P,EL,PM,S,COA,SSA,CT,CLS,E> envFactory,
                                                                                                     Resource resource)
Creates a new OCL with an environment factory and a resource in which its environment is to be persisted, or from which it may be loaded if the resource already has content.

Parameters:
envFactory - an environment factory
resource - a resource in which the root environment is persisted
Returns:
the OCL façade

getEnvironment

public Environment<PK,C,O,P,EL,PM,S,COA,SSA,CT,CLS,E> getEnvironment()
Obtains the OCL parsing environment. Clients may manipulate this environment to support custom requirements, such as adding variables to it to define "global" values. For any variables that are added, bindings will have to provided, as well, in the evaluation environment.

Returns:
the parsing environment
See Also:
getEvaluationEnvironment()

getEvaluationEnvironment

public EvaluationEnvironment<C,O,P,CLS,E> getEvaluationEnvironment()
Obtains the OCL evaluation environment. Clients may manipulate this environment to support custom requirements, such as binding the values of "global" variables.

Returns:
the evaluation environment
See Also:
getEnvironment()

getExtentMap

public Map<CLS,? extends Set<? extends E>> getExtentMap()
Obtains the extent map, if any, provided by the client to customize the evaluation of constraints.

Returns:
the client-provided custom extent map, or null if thie OCL is using the default dynamic extent map implementation

setExtentMap

public void setExtentMap(Map<CLS,? extends Set<? extends E>> extentMap)
Assigns a custom extent map to define the extents of classes in evaluation of OCL constraints. This is only needed if the default dynamic extent-map implementation is not suitable.

Parameters:
extentMap - a custom extent map, or null to use the default dynamic extent map implementation

parse

public List<CT> parse(OCLInput input)
               throws ParserException
Parses an OCL document, returning the constraints parsed from it. This OCL instance remembers these constraints; they can be retrieved later via the getConstraints() method.

Parameters:
input - an OCL document as either a string or a stream
Returns:
the constraints parsed from the document
Throws:
ParserException - on failure to parse, either because of a syntactic or semantic problem or because of an I/O failure
See Also:
getConstraints()

getConstraints

public List<CT> getConstraints()
Obtains all of the constraints parsed hitherto by this OCL instance. These accumulate with every document that is parsed.

Returns:
the constraints that I have parsed
See Also:
parse(OCLInput)

validate

public void validate(OCLExpression<C> expression)
              throws SemanticException
Validates an OCL expression, which may have been loaded from some resource or constructed via the API (perhaps by translation from some other language).

Parameters:
expression - an expression to validate
Throws:
SemanticException - on detection of any well-formedness problem in the expression
See Also:
validate(Object)

validate

public void validate(CT constraint)
              throws SemanticException
Validates an OCL constraint, which may have been loaded from some resource or constructed via the API (perhaps by translation from some other language).

Parameters:
constraint - a constraint to validate
Throws:
SemanticException - on detection of any well-formedness problem in the constraint

evaluate

public Object evaluate(Object context,
                       OCLExpression<C> expression)
Evaluates a query expression on a context object (which is bound to the self variable). Clients should use the isInvalid(Object) method to check whether the evaluation result is OclInvalid.

Parameters:
context - the context (self) object
expression - the OCL expression to evaluate
Returns:
the value of the expression, or OclInvalid if the evaluation fails for reasons other than a run-time exception
See Also:
isInvalid(Object), check(Object, Object)

isInvalid

public boolean isInvalid(Object value)
Queries whether a value is the special OclInvalid token. This is useful for determining whether the result of an expression evaluation is valid.

Parameters:
value - some OCL value
Returns:
true if it is the OclInvalid; false, otherwise
See Also:
evaluate(Object, OCLExpression)

check

public boolean check(Object context,
                     CT constraint)
Checks whether a constraint is satisfied by an object. If the constraint is an invariant constraint, then no additional variable bindings are required. If it is an operation precondition or postcondition, however, then the appropriate parameter variables and (in the postcondition case) result variable should be bound in the evaluation environment.

Parameters:
context - the self object of the constraint
constraint - the constraint to check
Returns:
whether the context object satisfies the constraint
See Also:
check(Object, OCLExpression), evaluate(Object, OCLExpression)

check

public boolean check(Object context,
                     OCLExpression<C> constraint)
Checks whether a constraint, specified simply as an OCL expression, is satisfied by an object. If the constraint is an invariant constraint, then no additional variable bindings are required. If it is an operation precondition or postcondition, however, then the appropriate parameter variables and (in the postcondition case) result variable should be bound in the evaluation environment.

Parameters:
context - the self object of the constraint
constraint - the constraint to check, which must be a boolean-valued expression
Returns:
whether the context object satisfies the constraint
Throws:
IllegalArgumentException - if the constraint expression is not boolean-valued
See Also:
check(Object, Object), evaluate(Object, OCLExpression)

createOCLHelper

public OCLHelper<C,O,P,CT> createOCLHelper()
Creates a new OCLHelper instance for convenient parsing of embedded constraints and query expressions in this environment. The helper is particulary useful for parsing constraints embedded in the model, in which case the context of a constraint is determined by its placement and the textual context declarations are unnecessary.

Returns:
a new helper object

createQuery

public Query<C,CLS,E> createQuery(OCLExpression<C> query)
Creates a new Query encapsulating a query expression with the current environment and extent map. This is convenient for repeated evaluation of expressions and for filtering/transforming objects using a query or constraint expression.

Every query maintains its own evaluation environment, which enables concurrent evaluation (where this may be safe in an EMF-based model) and different bindings for client-supplied "global" variables.

Parameters:
query - the OCL query expression, which may be interpreted as a constraint if it is boolean-valued
Returns:
the new query object
See Also:
createQuery(Object)

createQuery

public Query<C,CLS,E> createQuery(CT constraint)
Creates a new Query encapsulating a constraint with the current environment and extent map. This is convenient for repeated evaluation of constraints and for filtering objects using the constraint expression.

Every query maintains its own evaluation environment, which enables concurrent evaluation (where this may be safe in an EMF-based model) and different bindings for client-supplied "global" variables.

Parameters:
constraint - the OCL constraint
Returns:
the new query object
See Also:
createQuery(OCLExpression)

isParseTracingEnabled

public boolean isParseTracingEnabled()
Queries whether tracing of parsingis enabled. Tracing logs the progress of parsing to the console, which may be of use in diagnosing problems.

In an Eclipse environment, tracing is also enabled by turning on the org.eclipse.ocl/debug/parsing debug option.

Returns:
whether parse tracing is enabled
See Also:
setParseTracingEnabled(boolean)

setParseTracingEnabled

public void setParseTracingEnabled(boolean b)
Sets whether tracing of parsing is enabled. Tracing logs the progress of parsing to the console, which may be of use in diagnosing problems.

In an Eclipse environment, tracing is also enabled by turning on the org.eclipse.ocl/debug/parsing debug option.

param b whether parsing tracing is enabled

See Also:
isParseTracingEnabled()

isEvaluationTracingEnabled

public boolean isEvaluationTracingEnabled()
Queries whether tracing of evaluation is enabled. Tracing logs the progress of evaluation to the console, which may be of use in diagnosing problems.

In an Eclipse environment, tracing is also enabled by turning on the org.eclipse.ocl/debug/evaluation debug option.

Returns:
whether evaluation tracing is enabled
See Also:
setEvaluationTracingEnabled(boolean)

setEvaluationTracingEnabled

public void setEvaluationTracingEnabled(boolean b)
Sets whether tracing of evaluation is enabled. Tracing logs the progress of parsing to the console, which may be of use in diagnosing problems.

In an Eclipse environment, tracing is also enabled by turning on the org.eclipse.ocl/debug/evaluation debug option.

param b whether evaluation tracing is enabled

See Also:
isEvaluationTracingEnabled()

getProblems

public Diagnostic getProblems()
Obtains problems, if any, found in parsing the last OCL constraint or query expression.

Returns:
parsing problems or null if all was OK
Since:
1.2

dispose

public void dispose()
Disposes any objects that I have created while I have been in use. This includes disposing of any constraints that I have parsed and disposing of my environment.

Since:
1.2

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