org.eclipse.ocl.examples.pivot
Class OCLBase

java.lang.Object
  org.eclipse.ocl.examples.pivot.OCLBase

Direct Known Subclasses:

OCL

public abstract class OCLBase
extends java.lang.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.

Author:

Christian W. Damus (cdamus)

Constructor Summary

protected	OCLBase(Environment env) Initializes me with a root environment.
protected	OCLBase(EnvironmentFactory envFactory) Initializes me with an environment factory, which I will use to create a root environment.
protected	OCLBase(EnvironmentFactory envFactory, Environment rootEnv) Initializes me with my environment factory and root environment.
protected	OCLBase(EnvironmentFactory envFactory, org.eclipse.emf.ecore.resource.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(java.lang.Object context, Constraint constraint) Checks whether a constraint is satisfied by an object.
boolean	check(java.lang.Object context, ExpressionInOcl specification) Checks whether a constraint, specified simply as an OCL expression, is satisfied by an object.
QueryBase	createQuery(Constraint constraint) Creates a new QueryBase encapsulating a constraint with the current environment and extent map.
QueryBase	createQuery(ExpressionInOcl specification) Creates a new QueryBase 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.
Value	evaluate(java.lang.Object context, ExpressionInOcl expression) Evaluates a query expression on a context object (which is bound to the self variable).
java.util.List<Constraint>	getConstraints() Obtains all of the constraints parsed hitherto by this OCL instance.
Environment	getEnvironment() Obtains the OCL parsing environment.
EnvironmentFactory	getEnvironmentFactory()
EvaluationEnvironment	getEvaluationEnvironment() Obtains the OCL evaluation environment.
org.eclipse.emf.common.util.Diagnostic	getEvaluationProblems() Obtains problems, if any, occurred during evaluation of the last OCL constraint or query expression.
ModelManager	getModelManager() Obtains the model manager, if any, provided by the client to customize the evaluation of constraints.
int	getParserRepairCount() Queries the number of repairs to be made by the parser.
org.eclipse.emf.common.util.Diagnostic	getProblems() Obtains problems, if any, found in parsing the last OCL constraint or query expression.
TypeManager	getTypeManager()
ValueFactory	getValueFactory()
boolean	isEvaluationTracingEnabled() Queries whether tracing of evaluation is enabled.
boolean	isParseTracingEnabled() Queries whether tracing of parsingis enabled.
void	setEvaluationTracingEnabled(boolean b) Sets whether tracing of evaluation is enabled.
void	setModelManager(ModelManager modelManager) Assigns a custom extent map to define the extents of classes in evaluation of OCL constraints.
void	setParserRepairCount(int parserRepairCount) Sets the number of repairs to be made by the parser.
void	setParseTracingEnabled(boolean b) Sets whether tracing of parsing is enabled.
void	validate(Constraint 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 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

OCLBase

protected OCLBase(EnvironmentFactory envFactory)

Initializes me with an environment factory, which I will use to create a root environment.

Parameters:

envFactory - my environment factory

OCLBase

protected OCLBase(Environment env)

Initializes me with a root environment.

Parameters:

env - my root environment

OCLBase

protected OCLBase(EnvironmentFactory envFactory,
                  org.eclipse.emf.ecore.resource.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

OCLBase

protected OCLBase(EnvironmentFactory envFactory,
                  Environment rootEnv)

Initializes me with my environment factory and root environment.

Parameters:

envFactory - my environment factory

rootEnv - my root environment

Method Detail

getEnvironment

public Environment 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()

getEnvironmentFactory

public EnvironmentFactory getEnvironmentFactory()

getEvaluationEnvironment

public EvaluationEnvironment 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()

getModelManager

public ModelManager getModelManager()

Obtains the model manager, if any, provided by the client to customize the evaluation of constraints.

Returns:

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

setModelManager

public void setModelManager(ModelManager modelManager)

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:

modelManager - a custom extent map, or null to use the default dynamic extent map implementation

getConstraints

public java.util.List<Constraint> 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 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(Constraint 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 Value evaluate(java.lang.Object context,
                      ExpressionInOcl 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)

check

public boolean check(java.lang.Object context,
                     Constraint 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(java.lang.Object context,
                     ExpressionInOcl specification)

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:

java.lang.IllegalArgumentException - if the constraint expression is not boolean-valued

See Also:

#check(Object, Object), #evaluate(Object, OCLExpression)

createQuery

public QueryBase createQuery(ExpressionInOcl specification)

Creates a new QueryBase 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 QueryBase createQuery(Constraint constraint)

Creates a new QueryBase 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()

getParserRepairCount

public int getParserRepairCount()

Queries the number of repairs to be made by the parser.

The default zero value selects use of the deterministic parser, which terminates after one serious syntax error is detected.

A non-zero value selects the backtracking parser. The backtracking parser may be about three times slower.

Returns:

the number of repairs to be attempted

Since:

1.3

See Also:

setParserRepairCount(int)

setParserRepairCount

public void setParserRepairCount(int parserRepairCount)

Sets the number of repairs to be made by the parser.

The default zero value selects use of the deterministic parser, which terminates after one serious syntax error is detected.

A non-zero value selects the backtracking parser. The backtracking parser may be about three times slower.

Parameters:

parserRepairCount - whether evaluation tracing is enabled

Throws:

java.lang.IllegalArgumentException - if the parserRepairCount is negative

Since:

1.3

See Also:

getParserRepairCount()

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.

Parameters:

b - whether evaluation tracing is enabled

See Also:

isEvaluationTracingEnabled()

getProblems

public org.eclipse.emf.common.util.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

getTypeManager

public TypeManager getTypeManager()

getValueFactory

public ValueFactory getValueFactory()

getEvaluationProblems

public org.eclipse.emf.common.util.Diagnostic getEvaluationProblems()

Obtains problems, if any, occurred during evaluation of the last OCL constraint or query expression.

Returns:

evaluation problems or null if all was OK

Since:

1.3

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