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

java.lang.Object
  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 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.

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, 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, CT constraint) Checks whether a constraint is satisfied by an object.
boolean	check(java.lang.Object context, OCLExpression<C> constraint) Checks whether a constraint, specified simply as an OCL expression, is satisfied by an object.
OCLAnalyzer<PK,C,O,P,EL,PM,S,COA,SSA,CT,CLS,E>	createAnalyzer(java.lang.String input) Return an analyzer configured ready to parse an input string.
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.
java.lang.Object	evaluate(java.lang.Object context, OCLExpression<C> expression) Evaluates a query expression on a context object (which is bound to the self variable).
java.util.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.
Diagnostic	getEvaluationProblems() Obtains problems, if any, occurred during evaluation of the last OCL constraint or query expression.
java.util.Map<CLS,? extends java.util.Set<? extends E>>	getExtentMap() Obtains the extent map, 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.
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(java.lang.Object value) Queries whether a value is the special invalid 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.
java.util.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(java.util.Map<CLS,? extends java.util.Set<? extends E>> extentMap) 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(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

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 java.util.Map<CLS,? extends java.util.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(java.util.Map<CLS,? extends java.util.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

createAnalyzer

public OCLAnalyzer<PK,C,O,P,EL,PM,S,COA,SSA,CT,CLS,E> createAnalyzer(java.lang.String input)

Return an analyzer configured ready to parse an input string.

Parameters:

input - the input to parse

Returns:

an analyzer

Since:

3.0

parse

public java.util.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 java.util.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 java.lang.Object evaluate(java.lang.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(java.lang.Object value)

Queries whether a value is the special invalid 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 invalid; false, otherwise

See Also:

evaluate(Object, OCLExpression)

check

public boolean check(java.lang.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(java.lang.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:

java.lang.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()

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 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

getEvaluationProblems

public 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