org.eclipse.emf.ocl.helper
Interface IOCLHelper


public interface IOCLHelper

A utility object that provides OCL syntax completion suggestions for OCL expressions on the metamodel and user model levels. Metamodel OCL help is available for any EMF metamodel, but user model help is only available for metamodels for which an org.eclipse.gmf.runtime.emf.core.usermodel.IUserModelSupport extension is available.

Helpers of these two flavours can be created via the HelperUtil#createOCLHelper(ModelingLevel) method, which accepts an enumerated modeling level parameter to indicate metamodel or user-model level.

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

See Also:
HelperUtil.createOCLHelper(EnvironmentFactory)

Method Summary
 boolean check(java.lang.Object context, OCLExpression constraint)
          Evaluates the specified constraint on an instance of my context classifier and returns whether the constraint is satisfied.
 boolean check(java.lang.Object context, java.lang.String constraint)
          Evaluates the specified constraint on an instance of my context classifier and returns whether the constraint is satisfied.
 OCLExpression createBodyCondition(java.lang.String expression)
          Creates an operation body.
 OCLExpression createDerivedValueExpression(java.lang.String expression)
          Creates a property derived value expression.
 OCLExpression createInitialValueExpression(java.lang.String expression)
          Creates a property initial value expression.
 OCLExpression createInvariant(java.lang.String expression)
          Creates an invariant constraint in the current classifier context.
 OCLExpression createPostcondition(java.lang.String expression)
          Creates an operation postcondition constraint.
 OCLExpression createPrecondition(java.lang.String expression)
          Creates an operation precondition constraint.
 OCLExpression createQuery(java.lang.String expression)
          Creates a query expression in the current classifier context.
 org.eclipse.emf.ecore.ETypedElement define(java.lang.String defExpression)
          Defines an additional property or operation in the context classifier, for use in formulating OCL queries and constraints.
 java.lang.Object evaluate(java.lang.Object context, OCLExpression expression)
          Evaluates the specified parsed OCL expression on an instance of my context classifier.
 java.lang.Object evaluate(java.lang.Object context, java.lang.String expression)
          Evaluates the specified expression on an instance of my context classifier.
 org.eclipse.emf.ecore.EClassifier getContextClassifier()
          Obtains my OCL context classifier as an EMF classifier.
 org.eclipse.emf.ecore.EOperation getContextOperation()
          Obtains my context operation as an EMF operation, if my environment is an operation context.
 org.eclipse.emf.ecore.EStructuralFeature getContextProperty()
          Obtains my context operation as an EMF property, if my environment is a property context.
 Environment getEnvironment()
          Obtains the environment defining my current context classifier, operation, or property.
 EnvironmentFactory getEnvironmentFactory()
          Retrieves the environment factory for the metamodel that I am helping.
 java.util.List getSyntaxHelp(ConstraintType constraintType, java.lang.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.
 java.util.List getSyntaxHelp(java.lang.String txt)
          Deprecated. Use the IOCLHelper.getSyntaxHelp(ConstraintType, String) method, instead, to get the correct completions for the context
 void setContext(java.lang.Object context)
          Sets the context of the OCL expression for which syntax or parsing help is to be provided.
 void setContextOperation(java.lang.Object context, java.lang.Object operation)
          Sets the context of the OCL expression for which syntax or parsing help is to be provided.
 void setContextProperty(java.lang.Object context, java.lang.Object property)
          Sets the context of the OCL expression for which syntax or parsing help is to be provided.
 

Method Detail

setContext

public void setContext(java.lang.Object context)
Sets the context of the OCL expression for which syntax or parsing help is to be provided. The context may be either the specific model element on which an OCL expression would be evaluated, or it may be an EClassifier of the target metamodel against which an OCL expression would be parsed. Note that, in the former case, the actual OCL context classifier (as an OCL type or EClassifier) will be inferred from the context object according to the nature of the environment factory.

Parameters:
context - the OCL context object or classifier
See Also:
IOCLHelper.setContextOperation(Object, Object)

getContextClassifier

public org.eclipse.emf.ecore.EClassifier getContextClassifier()
Obtains my OCL context classifier as an EMF classifier.

Returns:
my context classifier (never null)

setContextOperation

public void setContextOperation(java.lang.Object context,
                                java.lang.Object operation)
Sets the 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 classifier; this model element must be able to be represented as an OCL operation.

Parameters:
context - the OCL context object
operation - the OCL context operation
See Also:
IOCLHelper.setContext(Object)

getContextOperation

public org.eclipse.emf.ecore.EOperation getContextOperation()
Obtains my context operation as an EMF operation, if my environment is an operation context.

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

setContextProperty

public void setContextProperty(java.lang.Object context,
                               java.lang.Object property)
Sets the context of the OCL expression for which syntax or parsing help is to be provided. The property is the model element against which the OCL will be parsed as an property available in an OCL classifier; this model element must be able to be represented as an OCL property.

Parameters:
context - the OCL context object
property - the OCL context property
See Also:
IOCLHelper.setContext(Object)

getContextProperty

public org.eclipse.emf.ecore.EStructuralFeature getContextProperty()
Obtains my context operation as an EMF property, if my environment is a property context.

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

getEnvironment

public Environment getEnvironment()
Obtains the environment defining my current context classifier, operation, or property. I do not have an environment until my context is set.

Returns:
my current environment, or null if I have none
See Also:
IOCLHelper.setContext(Object), IOCLHelper.setContextOperation(Object, Object), IOCLHelper.setContextProperty(Object, Object)

getSyntaxHelp

public java.util.List getSyntaxHelp(java.lang.String txt)
Deprecated. Use the IOCLHelper.getSyntaxHelp(ConstraintType, String) method, instead, to get the correct completions for the context

Obtains syntax completion choices for the specified fragment of an OCL expression that is to be used for an invariant constraint (in case of a classifier context) or a postcondition constraint (in case of an operation context). For completion of other operation constraint types, use the IOCLHelper.getSyntaxHelp(ConstraintType, String) method as it will provide completions for syntax only available in these constraints.

Parameters:
txt - a partial OCL expression for which to seek choices that could be appended to it
Returns:
a list of Choices, possibly empty. The ordering of the list may or may not indicate relative relevance or frequency of a choice

getSyntaxHelp

public java.util.List getSyntaxHelp(ConstraintType constraintType,
                                    java.lang.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
txt - a partial OCL expression for which to seek choices that could be appended to it
Returns:
a list of Choices, possibly empty. The ordering of the list may or may not indicate relative relevance or frequency of a choice

createQuery

public OCLExpression createQuery(java.lang.String expression)
                          throws OCLParsingException
Creates a query expression in the current classifier context.

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

createInvariant

public OCLExpression createInvariant(java.lang.String expression)
                              throws OCLParsingException
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 condition
Throws:
OCLParsingException - if the expression fails to parse

createPrecondition

public OCLExpression createPrecondition(java.lang.String expression)
                                 throws OCLParsingException
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:
OCLParsingException - if the expression fails to parse
See Also:
IOCLHelper.setContextOperation(Object, Object)

createPostcondition

public OCLExpression createPostcondition(java.lang.String expression)
                                  throws OCLParsingException
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:
OCLParsingException - if the expression fails to parse
See Also:
IOCLHelper.setContextOperation(Object, Object)

createBodyCondition

public OCLExpression createBodyCondition(java.lang.String expression)
                                  throws OCLParsingException
Creates an operation body. 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 body condition
Throws:
OCLParsingException - if the expression fails to parse
See Also:
IOCLHelper.setContextOperation(Object, Object)

createInitialValueExpression

public OCLExpression createInitialValueExpression(java.lang.String expression)
                                           throws OCLParsingException
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:
OCLParsingException - if the expression fails to parse or is not valid for my context property
See Also:
IOCLHelper.setContextProperty(Object, Object)

createDerivedValueExpression

public OCLExpression createDerivedValueExpression(java.lang.String expression)
                                           throws OCLParsingException
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:
OCLParsingException - if the expression fails to parse or is not valid for my context property
See Also:
IOCLHelper.setContextProperty(Object, Object)

define

public org.eclipse.emf.ecore.ETypedElement define(java.lang.String defExpression)
                                           throws OCLParsingException
Defines an additional property or operation in the context classifier, for use in formulating OCL queries and constraints. This is a "def expression", taking the form of either:
     operation-name(parameters?) : type = expr
 
or
     property-name : type = expr
 

Parameters:
defExpression - the definition expression (without any other context declaration).
Returns:
the newly defined EOperation or EStructuralFeature
Throws:
OCLParsingException - if the expression fails to parse

evaluate

public java.lang.Object evaluate(java.lang.Object context,
                                 OCLExpression expression)
Evaluates the specified parsed OCL expression on an instance of my context classifier. This expression needs not be a boolean-valued constraint.

Parameters:
context - the context object on which to evaluate the expression. This is the self object, if the expression requires one. Note that a context is required even for expressions that use the allInstances() operation to get the instances of an OCL classifier, in order to find resources to search for instances (unless the context is a data type, in which case the instances are not enumerated by models)
Returns:
the result of the expression evaluation. This can be a single object, a collection of objects, or even null

evaluate

public java.lang.Object evaluate(java.lang.Object context,
                                 java.lang.String expression)
                          throws OCLParsingException
Evaluates the specified expression on an instance of my context classifier. This expression needs not be a boolean-valued constraint. This method parses and evaluates the OCL expression in one step.

Parameters:
context - the context object on which to evaluate the expression. This is the self object, if the expression requires one. Note the it is required even for expressions that use the allInstances() operation to get the instances of an OCL classifier, in order to find resources to search for instances (unless the context is a data type, in which case the instances are not enumerated by models)
Returns:
the result of the expression evaluation. This can be a single object, a collection of objects, or even null
Throws:
OCLParsingException - if the expression fails to parse
See Also:
IOCLHelper.evaluate(Object, OCLExpression)

check

public boolean check(java.lang.Object context,
                     OCLExpression constraint)
Evaluates the specified constraint on an instance of my context classifier and returns whether the constraint is satisfied. This expression must be boolean-valued.

Parameters:
context - the context object on which to evaluate the expression. This is the self object, if the expression requires one. Note the it is required even for expressions that use the allInstances() operation to get the instances of an OCL classifier, in order to find resources to search for instances (unless the context is a data type, in which case the instances are not enumerated by models)
constraint - a constraint expression to evaluate
Returns:
true if the context object satisfies the constraint; false, otherwise
Throws:
java.lang.IllegalArgumentException - if the constraint is not boolean-valued

check

public boolean check(java.lang.Object context,
                     java.lang.String constraint)
              throws OCLParsingException
Evaluates the specified constraint on an instance of my context classifier and returns whether the constraint is satisfied. This expression must be boolean-valued. This method parses and evaluates the OCL constraint in one step.

Parameters:
context - the context object on which to evaluate the expression. This is the self object, if the expression requires one. Note the it is required even for expressions that use the allInstances() operation to get the instances of an OCL classifier, in order to find resources to search for instances (unless the context is a data type, in which case the instances are not enumerated by models)
constraint - a constraint expression to evaluate
Returns:
true if the context object satisfies the constraint; false, otherwise
Throws:
OCLParsingException - if the expression fails to parse
java.lang.IllegalArgumentException - if the constraint is not boolean-valued
See Also:
IOCLHelper.check(Object, OCLExpression)

getEnvironmentFactory

public EnvironmentFactory getEnvironmentFactory()
Retrieves the environment factory for the metamodel that I am helping.

Returns:
my environment factory (never null)

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