org.eclipse.ocl.examples.pivot
Class OCL

java.lang.Object
  extended by org.eclipse.ocl.examples.pivot.OCL

public class OCL
extends java.lang.Object

Convenient subclass of the OCL façade that binds the Ecore metamodel to the superclass's generic type parameters. This frees client code from the long list of parameter substitutions. This subclass also provides a shortcut to creating an OCL on the shared EcoreEnvironmentFactory instance.

Author:
Christian W. Damus (cdamus)
See Also:
EcoreEnvironmentFactory

Constructor Summary
protected OCL(EnvironmentFactory envFactory, Environment rootEnv)
          Initializes me with my environment factory and root environment.
 
Method Summary
 boolean check(java.lang.Object context, Constraint constraint)
          Checks whether a constraint is satisfied by an object.
 boolean check(java.lang.Object context, ExpressionInOCL specification)
          Checks whether a constraint, specified simply as an OCL expression, is satisfied by an object.
 EvaluationVisitor createEvaluationVisitor(java.lang.Object context, ExpressionInOCL expression)
          Creates a new evaluation visitor, for the evaluation of an OCL expression in a context.
 OCLHelper createOCLHelper()
          Creates a new OCLHelper instance for convenient parsing of embedded constraints and query expressions in this environment.
 OCLHelper createOCLHelper(org.eclipse.emf.ecore.EObject element)
          Creates a new OCLHelper instance for convenient parsing of embedded constraints and query expressions in the nested environment of a specified element which mya be a Type, Operation or Property.
 Query createQuery(Constraint constraint)
          Creates a new Query encapsulating a constraint with the current environment and extent map.
 Query createQuery(ExpressionInOCL specification)
          Creates a new Query encapsulating a query expression with the current environment and extent map.
 org.eclipse.emf.ecore.resource.Resource cs2pivot(BaseResource csResource)
          Return the Pivot resource counterpart of an Xtext csResource.
 void dispose()
          Disposes any objects that I have created while I have been in use.
 ASResource ecore2pivot(org.eclipse.emf.ecore.resource.Resource ecoreResource)
          Return the Pivot resource counterpart of an ecoreResource.
 java.lang.Object evaluate(java.lang.Object context, ExpressionInOCL expression)
          Evaluates a query expression on a context object (which is bound to the self variable).
 java.util.List<Constraint> getConstraints()
          Obtains all of the constraints parsed hitherto by this OCL instance.
 Environment getEnvironment()
          Obtains the root OCL parsing environment.
 EnvironmentFactory getEnvironmentFactory()
           
 EvaluationEnvironment getEvaluationEnvironment()
          Deprecated. no longer called
 org.eclipse.emf.common.util.Diagnostic getEvaluationProblems()
          Obtains problems, if any, occurred during evaluation of the last OCL constraint or query expression.
 MetaModelManager getMetaModelManager()
           
 DomainModelManager getModelManager()
          Obtains the model manager, 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.
 ExpressionInOCL getSpecification(Constraint constraint)
          Return the Constraint specification as an ExpressionInOCL, parsing any OpaqueExpression that may be encountered.
static java.lang.String initialize(org.eclipse.emf.ecore.resource.ResourceSet resourceSet)
          Initialize registries to support OCL and Ecore usage.
 boolean isEvaluationTracingEnabled()
          Queries whether tracing of evaluation is enabled.
 boolean isParseTracingEnabled()
          Queries whether tracing of parsingis enabled.
 BaseResource load(org.eclipse.emf.common.util.URI uri)
          Load the Complete OCL document specified by the URI into the external ResourceSet and return the concrete syntax resource.
static OCL newInstance()
          Creates a new OCL with no initial Ecore package registry.
static OCL newInstance(Environment env)
          Creates a new OCL using the specified initial Ecore environment.
static OCL newInstance(EnvironmentFactory envFactory)
          Creates a new OCL using the specified Ecore environment factory.
static OCL newInstance(EnvironmentFactory envFactory, org.eclipse.emf.ecore.resource.Resource resource)
          Creates a new OCL using the specified Ecore environment factory and a resource from which to load the initial environment.
static OCL newInstance(org.eclipse.emf.ecore.EPackage.Registry reg)
          Creates a new OCL using the specified Ecore package registry.
 org.eclipse.emf.ecore.resource.Resource parse(org.eclipse.emf.common.util.URI uri)
          Load the Complete OCL document specified by the URI into the external ResourceSet and parse the concrete syntax resource returning the resulting abstract syntax resource.
 void pivot2cs(ASResource asResource, BaseResource csResource)
          Update the CS resource from a asResource.
 org.eclipse.emf.ecore.resource.Resource pivot2ecore(org.eclipse.emf.ecore.resource.Resource asResource, org.eclipse.emf.common.util.URI uri)
          Return the Ecore resource counterpart of a asResource, specifying the uri of the resulting Ecore resource.
 void setEvaluationTracingEnabled(boolean b)
          Sets whether tracing of evaluation is enabled.
 void setModelManager(DomainModelManager modelManager)
          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.
 ASResource uml2pivot(org.eclipse.emf.ecore.resource.Resource umlResource)
          Return the Pivot resource counterpart of a umlResource.
 void validate(Constraint 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 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(@NonNull
              EnvironmentFactory envFactory,
              @NonNull
              Environment rootEnv)
Initializes me with my environment factory and root environment.

Parameters:
envFactory - my environment factory
rootEnv - my root environment
Method Detail

initialize

public static java.lang.String initialize(@Nullable
                                          org.eclipse.emf.ecore.resource.ResourceSet resourceSet)
Initialize registries to support OCL and Ecore usage. This method is intended for initialization of standalone behaviors for which plugin extension registrations have not been applied.

A null resourceSet may be provided to initialize the global package registry and global URI mapping registry.

A non-null resourceSet may be provided to identify a specific package registry.

This method is used to configure the ResourceSet used to load the OCL Standard Library.

Parameters:
resourceSet - to be initialized or null for global initialization
Returns:
a failure reason, null if successful

newInstance

@NonNull
public static OCL newInstance()
Creates a new OCL with no initial Ecore package registry. This automatically creates a new EnvironmentFactory and MetaModelManager.

Returns:
the new OCL

newInstance

@NonNull
public static OCL newInstance(@NonNull
                                      org.eclipse.emf.ecore.EPackage.Registry reg)
Creates a new OCL using the specified Ecore package registry. This automatically creates an new EnvironmentFactory and MetaModelManager.

Parameters:
reg - Ecore package registry
Returns:
the new OCL

newInstance

@NonNull
public static OCL newInstance(@NonNull
                                      EnvironmentFactory envFactory)
Creates a new OCL using the specified Ecore environment factory.

Parameters:
envFactory - an environment factory for Ecore
Returns:
the new OCL

newInstance

@NonNull
public static OCL newInstance(@NonNull
                                      EnvironmentFactory envFactory,
                                      @NonNull
                                      org.eclipse.emf.ecore.resource.Resource resource)
Creates a new OCL using the specified Ecore environment factory and a resource from which to load the initial environment.

Parameters:
envFactory - an environment factory for Ecore
resource - the resource containing a persistent environment (which may be empty for an initially empty environment)
Returns:
the new OCL

newInstance

@NonNull
public static OCL newInstance(@NonNull
                                      Environment env)
Creates a new OCL using the specified initial Ecore environment.

Parameters:
env - an environment for Ecore
Returns:
the new OCL

check

public boolean check(java.lang.Object context,
                     @NonNull
                     Constraint 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,
                     @NonNull
                     ExpressionInOCL specification)
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)

createEvaluationVisitor

@NonNull
public EvaluationVisitor createEvaluationVisitor(@Nullable
                                                         java.lang.Object context,
                                                         @NonNull
                                                         ExpressionInOCL expression)
Creates a new evaluation visitor, for the evaluation of an OCL expression in a context. The evaluationVisitor reuses any previously established ModelManager.


createOCLHelper

@NonNull
public OCLHelper createOCLHelper()
Creates a new OCLHelper instance for convenient parsing of embedded constraints and query expressions in this environment. The helper is particularly 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

createOCLHelper

@NonNull
public OCLHelper createOCLHelper(@NonNull
                                         org.eclipse.emf.ecore.EObject element)
Creates a new OCLHelper instance for convenient parsing of embedded constraints and query expressions in the nested environment of a specified element which mya be a Type, Operation or Property. 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

@NonNull
public Query createQuery(@NonNull
                                 ExpressionInOCL specification)
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 createQuery(@NonNull
                         Constraint 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)

cs2pivot

@NonNull
public org.eclipse.emf.ecore.resource.Resource cs2pivot(@NonNull
                                                                BaseResource csResource)
Return the Pivot resource counterpart of an Xtext csResource.


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.


ecore2pivot

@NonNull
public ASResource ecore2pivot(@NonNull
                                      org.eclipse.emf.ecore.resource.Resource ecoreResource)
                       throws ParserException
Return the Pivot resource counterpart of an ecoreResource.

Throws:
ParserException

evaluate

@Nullable
public java.lang.Object evaluate(@Nullable
                                          java.lang.Object context,
                                          @NonNull
                                          ExpressionInOCL 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)

getConstraints

@NonNull
public java.util.List<Constraint> 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)

getEnvironment

@NonNull
public Environment getEnvironment()
Obtains the root OCL parsing environment.

Returns:
the parsing environment

getEnvironmentFactory

@NonNull
public EnvironmentFactory getEnvironmentFactory()

getEvaluationEnvironment

@Deprecated
@NonNull
public EvaluationEnvironment getEvaluationEnvironment()
Deprecated. no longer called

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

getEvaluationProblems

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

getMetaModelManager

@NonNull
public MetaModelManager getMetaModelManager()

getModelManager

@Nullable
public DomainModelManager getModelManager()
Obtains the model manager, if any, provided by the client to customize the evaluation of constraints.

Returns:
the client-provided custom model manager, or null if thie OCL is using the default dynamic extent map implementation

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
See Also:
setParserRepairCount(int)

getProblems

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

getSpecification

@Nullable
public ExpressionInOCL getSpecification(@NonNull
                                                 Constraint constraint)
                                 throws ParserException
Return the Constraint specification as an ExpressionInOCL, parsing any OpaqueExpression that may be encountered.

Throws:
ParserException

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)

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)

load

@Nullable
public BaseResource load(@NonNull
                                  org.eclipse.emf.common.util.URI uri)
Load the Complete OCL document specified by the URI into the external ResourceSet and return the concrete syntax resource.


parse

@Nullable
public org.eclipse.emf.ecore.resource.Resource parse(@NonNull
                                                              org.eclipse.emf.common.util.URI uri)
Load the Complete OCL document specified by the URI into the external ResourceSet and parse the concrete syntax resource returning the resulting abstract syntax resource.


pivot2cs

public void pivot2cs(@NonNull
                     ASResource asResource,
                     @NonNull
                     BaseResource csResource)
Update the CS resource from a asResource. For a first update, the csResource may be created by something like

(BaseResource) resourceSet.createResource(outputURI, OCLinEcoreCSPackage.eCONTENT_TYPE);


pivot2ecore

@NonNull
public org.eclipse.emf.ecore.resource.Resource pivot2ecore(@NonNull
                                                                   org.eclipse.emf.ecore.resource.Resource asResource,
                                                                   @NonNull
                                                                   org.eclipse.emf.common.util.URI uri)
                                                    throws java.io.IOException
Return the Ecore resource counterpart of a asResource, specifying the uri of the resulting Ecore resource.

Throws:
java.io.IOException

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

setModelManager

public void setModelManager(@Nullable
                            DomainModelManager modelManager)
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:
modelManager - a custom extent map, or null to use the default dynamic extent map implementation

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
See Also:
getParserRepairCount()

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

uml2pivot

@NonNull
public ASResource uml2pivot(@NonNull
                                    org.eclipse.emf.ecore.resource.Resource umlResource)
                     throws ParserException
Return the Pivot resource counterpart of a umlResource.

Throws:
ParserException

validate

public void validate(@NonNull
                     OCLExpression 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(@NonNull
                     Constraint 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