org.eclipse.ocl.examples.pivot
Class OCL

java.lang.Object
  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