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