## org.eclipse.ocl.helper
Interface OCLHelper<C,O,P,CT>

All Known Subinterfaces:
  OCL.Helper

    public interface OCLHelper<C,O,P,CT>

A utility object that provides OCL syntax completion suggestions for OCL expressions and convenient API for parsing OCL constraint expressions without the encumbrance of context declarations. The latter is most useful for processing OCL constraints and expressions embedded in the user model, where the context is implied by the placement of the constraint in the model.

An OCL helper is created by the `OCL.createOCLHelper()` factory method and inherits the current context `Environment` of the `OCL` that created it.

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

Note that this interface is not intended to be implemented by clients.

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

See Also:
  `OCL.createOCLHelper()`

Method Summary
`CT` `createBodyCondition(String expression)` Creates an operation body.
`CT` `createConstraint(ConstraintKind kind, String expression)` Creates a constraint of the specified kind, by parsing the given expression.
`CT` `createDerivedValueExpression(String expression)` Creates a property derived value expression.
`CT` `createInitialValueExpression(String expression)` Creates a property initial value expression.
`CT` `createInvariant(String expression)` Creates an invariant constraint in the current classifier context.
`CT` `createPostcondition(String expression)` Creates an operation postcondition constraint.
`CT` `createPrecondition(String expression)` Creates an operation precondition constraint.
`OCLExpression<C>` `createQuery(String expression)` Creates a query expression in the current classifier context.
`P` `defineAttribute(String defExpression)` Defines an additional attribute in the context classifier, for use in formulating OCL queries and constraints.
`O` `defineOperation(String defExpression)` Defines an additional operation in the context classifier, for use in formulating OCL queries and constraints.
`P` `getContextAttribute()` Obtains my context attribute, if my environment is an attribute context.
`C` `getContextClassifier()` Obtains my OCL context classifier as a classifier.
`O` `getContextOperation()` Obtains my context operation, if my environment is an operation context.
`Environment<?,C,O,P,?,?,?,?,?,CT,?,?>` `getEnvironment()` Obtains the environment defining my current classifier, operation, or attribute context.
`OCL<?,C,O,P,?,?,?,?,?,CT,?,?>` `getOCL()` Obtains the OCL instance that created me.
`Diagnostic` `getProblems()` Obtains problems, if any, found in parsing the last OCL constraint or query expression.
`List<Choice>` `getSyntaxHelp(ConstraintKind constraintType, String txt)` Obtains syntax completion choices for the specified fragment of an OCL expression given that it is intended for a constraint of the specified kind.
`boolean` `isValidating()` Queries whether I validate the expressions that I parse.
`void` `setAttributeContext(C context, P property)` Sets the attribute context of the OCL expression for which syntax or parsing help is to be provided.
`void` `setContext(C context)` Sets the classifier context of the OCL expression for which syntax or parsing help is to be provided.
`void` `setInstanceAttributeContext(Object instance, P property)` Sets the operation context implied by the specified instance.
`void` `setInstanceContext(Object instance)` Sets the classifier context implied by the specified instance.
`void` `setInstanceOperationContext(Object instance, O operation)` Sets the operation context implied by the specified instance.
`void` `setOperationContext(C context, O operation)` Sets the operation context of the OCL expression for which syntax or parsing help is to be provided.
`void` `setValidating(boolean validating)` Sets whether I should validate the expressions that I parse.

Method Detail

### setContext

    void setContext(C context)

  Sets the classifier context of the OCL expression for which syntax or parsing help is to be provided.

  Parameters:
    `context` - the OCL context classifier
  See Also:
    `setOperationContext(Object, Object)`, `setAttributeContext(Object, Object)`

### getContextClassifier

    C getContextClassifier()

  Obtains my OCL context classifier as a classifier.

  Returns:
    my context classifier (never `null`)

### setOperationContext

    void setOperationContext(C context,
                             O operation)

  Sets the operation context of the OCL expression for which syntax or parsing help is to be provided. The operation is the model element against which the OCL will be parsed as an operation applicable to an OCL type. Note that the operation needs not necessarily be defined by the specified context classifier; it could be inherited.

  Parameters:
    `context` - the OCL context classifier
    `operation` - the OCL context operation
  See Also:
    `setContext(Object)`

### getContextOperation

    O getContextOperation()

  Obtains my context operation, if my environment is an operation context.

  Returns:
    my context operation, or `null` if there is only a classifier or attribute context

### setAttributeContext

    void setAttributeContext(C context,
                             P property)

  Sets the attribute context of the OCL expression for which syntax or parsing help is to be provided. The attribute is the model element against which the OCL will be parsed as an attribute available in an OCL classifier. Note that the attribute needs not necessarily be defined by the specified context classifier; it could be inherited.

  Parameters:
    `context` - the OCL context classifier
    `property` - the OCL context attribute
  See Also:
    `setContext(Object)`

### getContextAttribute

    P getContextAttribute()

  Obtains my context attribute, if my environment is an attribute context.

  Returns:
    my context attribute, or `null` if there is only a classifier or operation context

### setInstanceContext

    void setInstanceContext(Object instance)

  Sets the classifier context implied by the specified instance. The appropriate classifier will be determined from the run-time type of this object, if possible. If not possible, `OclAny` is assumed.

  This method is convenient for ad hoc parsing and evaluation of OCL constraints or expressions in the context of a model instance.

  Parameters:
    `instance` - the OCL context instance
  See Also:
    `setContext(Object)`

### setInstanceOperationContext

    void setInstanceOperationContext(Object instance,
                                     O operation)

  Sets the operation context implied by the specified instance. The appropriate classifier will be determined from the run-time type of this object, if possible. If not possible, `OclAny` is assumed.

  This method is convenient for ad hoc parsing and evaluation of OCL constraints or expressions in the context of a model instance.

  Parameters:
    `instance` - the OCL context instance
    `operation` - the OCL context operation
  See Also:
    `setOperationContext(Object, Object)`

### setInstanceAttributeContext

    void setInstanceAttributeContext(Object instance,
                                     P property)

  Sets the operation context implied by the specified instance. The appropriate classifier will be determined from the run-time type of this object, if possible. If not possible, `OclAny` is assumed.

  This method is convenient for ad hoc parsing and evaluation of OCL constraints or expressions in the context of a model instance.

  Parameters:
    `instance` - the OCL context instance
    `property` - the OCL context attribute
  See Also:
    `setAttributeContext(Object, Object)`

### getOCL

    OCL<?,C,O,P,?,?,?,?,?,CT,?,?> getOCL()

  Obtains the OCL instance that created me. Note that many of the generic type parameter bindings will not be known, so clients should keep track of the OCL instance themselves where that is a problem.

  Returns:
    the OCL instance that created me

### getEnvironment

    Environment<?,C,O,P,?,?,?,?,?,CT,?,?> getEnvironment()

  Obtains the environment defining my current classifier, operation, or attribute context. Accessing the environment is convenient for, e.g., adding variable definitions to insert global objects into the OCL context.

  Returns:
    my current context environment, or `null` if I have not yet been assigned a context
  Since:
    1.2
  See Also:
    `setContext(Object)`, `setOperationContext(Object, Object)`, `setAttributeContext(Object, Object)`

### isValidating

    boolean isValidating()

  Queries whether I validate the expressions that I parse. Validation applies more well-formedness checks than are implied by parsing, especially because parsing supports partial (incomplete) expressions for syntax completion. Validation adds some amount of processing, which is not necessary in all cases.

  Returns:
    whether I validate the expressions that I parse. Validation is on by default

### setValidating

    void setValidating(boolean validating)

  Sets whether I should validate the expressions that I parse.

  Parameters:
    `validating` - whether I should validate parsed expressions

### createQuery

    OCLExpression<C> createQuery(String expression)
                                 throws ParserException

  Creates a query expression in the current classifier context. This may be specified, for example, as an expression value in the model.

  Parameters:
    `expression` - the expression (without any context declaration). This expression can have any result type; it needs not be a boolean
  Returns:
    the query expression
  Throws:
    `ParserException` - if the `expression` fails to parse

### createConstraint

    CT createConstraint(ConstraintKind kind,
                        String expression)
                        throws ParserException

  Creates a constraint of the specified kind, by parsing the given expression. In the case of additional attribute or operation definition constraints, the expression must be prefixed by the signature of the feature as follows:

  >          attribute-name : type = expr

  >          operation-name(parameters?) : type = expr

  Parameters:
    `kind` - the kind of constraint to create
    `expression` - the constraint body
  Returns:
    the constraint
  Throws:
    `ParserException` - on failure to parse the constraint

### createInvariant

    CT createInvariant(String expression)
                       throws ParserException

  Creates an invariant constraint in the current classifier context.

  Parameters:
    `expression` - the constraint expression (without any context declaration). This must be a boolean-valued expression
  Returns:
    the invariant constraint
  Throws:
    `ParserException` - if the `expression` fails to parse

### createPrecondition

    CT createPrecondition(String expression)
                          throws ParserException

  Creates an operation precondition constraint. This is appropriate only if my context is an operation.

  Parameters:
    `expression` - the constraint expression (without any context declaration). This must be a boolean-valued expression
  Returns:
    the precondition
  Throws:
    `ParserException` - if the `expression` fails to parse
  See Also:
    `setOperationContext(Object, Object)`

### createPostcondition

    CT createPostcondition(String expression)
                           throws ParserException

  Creates an operation postcondition constraint. This is appropriate only if my context is an operation.

  Parameters:
    `expression` - the constraint expression (without any context declaration). This must be a boolean-valued expression
  Returns:
    the postcondition
  Throws:
    `ParserException` - if the `expression` fails to parse
  See Also:
    `setOperationContext(Object, Object)`

### createBodyCondition

    CT createBodyCondition(String expression)
                           throws ParserException

  Creates an operation body. This is appropriate only if my context is an operation.

  Parameters:
    `expression` - the constraint expression (without any context declaration). Ordinarily, this is an expression of the same type as the operation, specifying the value of the operation. Alternatively, this may be a boolean-valued expression phrased like a post-condition (according to the well-formedness rules of UML constraints)
  Returns:
    the body condition
  Throws:
    `ParserException` - if the `expression` fails to parse
  See Also:
    `setOperationContext(Object, Object)`

### createInitialValueExpression

    CT createInitialValueExpression(String expression)
                                    throws ParserException

  Creates a property initial value expression. This is appropriate only if my context is a property.

  Parameters:
    `expression` - the initial value expression (without any context declaration). This must conform to my context property type
  Returns:
    the initial value expression
  Throws:
    `ParserException` - if the `expression` fails to parse or is not valid for my context property
  See Also:
    `setAttributeContext(Object, Object)`

### createDerivedValueExpression

    CT createDerivedValueExpression(String expression)
                                    throws ParserException

  Creates a property derived value expression. This is appropriate only if my context is a property.

  Parameters:
    `expression` - the derived value expression (without any context declaration). This must conform to my context property type
  Returns:
    the derived value expression
  Throws:
    `ParserException` - if the `expression` fails to parse or is not valid for my context property
  See Also:
    `setAttributeContext(Object, Object)`

### defineOperation

    O defineOperation(String defExpression)
                      throws ParserException

  Defines an additional operation in the context classifier, for use in formulating OCL queries and constraints. This is a "def expression", taking the form of:

  >          operation-name(parameters?) : type = expr

  Parameters:
    `defExpression` - the definition expression (without any other context declaration).
  Returns:
    the newly defined operation
  Throws:
    `ParserException` - if the `expression` fails to parse

### defineAttribute

    P defineAttribute(String defExpression)
                      throws ParserException

  Defines an additional attribute in the context classifier, for use in formulating OCL queries and constraints. This is a "def expression", taking the form of:

  >          attribute-name : type = expr

  Parameters:
    `defExpression` - the definition expression (without any other context declaration).
  Returns:
    the newly defined attribute
  Throws:
    `ParserException` - if the `expression` fails to parse

### getSyntaxHelp

    List<Choice> getSyntaxHelp(ConstraintKind constraintType,
                               String txt)

  Obtains syntax completion choices for the specified fragment of an OCL expression given that it is intended for a constraint of the specified kind. The choices returned (if any) will be appropriate for appending to the end of the specified text in the context of this kind of constraint.

  Parameters:
    `constraintType` - the kind of constraint that is being composed, or `null` to indicate completions for a query expression
    `txt` - a partial OCL expression for which to seek choices that could be appended to it
  Returns:
    a list of `Choice`s, possibly empty. The ordering of the list may or may not indicate relative relevance or frequency of a choice

### getProblems

    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

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