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 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 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, 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, 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.
 org.eclipse.emf.common.util.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.
 org.eclipse.emf.common.util.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, org.eclipse.emf.ecore.resource.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,
              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

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,
                                                                                                     org.eclipse.emf.ecore.resource.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 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

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