org.eclipse.ocl.pivot.utilities

Class OCL

java.lang.Object

org.eclipse.ocl.pivot.utilities.OCL

Direct Known Subclasses:

EvaluationContext, OCLInternal, UMLOCL

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 EnvironmentFactoryInternal instance.

See Also:

EnvironmentFactoryInternal

Field Summary

Fields

Modifier and Type	Field and Description
static ProjectManager	CLASS_PATH A heavyweight shared read-only ProjectManager that provides access to all external projects.
protected EnvironmentFactoryInternal	environmentFactory The EnvironmentFactory that can create objects and which provides the MetamodelManager, CompleteEnvironment and StandardLibrary.
static ProjectManager	NO_PROJECTS A very lightweight ProjectManager that provodes no access to external projects.

Constructor Summary

Constructors

Modifier	Constructor and Description
protected	OCL(EnvironmentFactoryInternal environmentFactory) Initializes me with my environment factory and root environment.

Method Summary

Modifier and Type	Method and Description
void	as2cs(ASResource asResource, CSResource csResource) Update the CS resource from a asResource.
org.eclipse.emf.ecore.resource.Resource	as2ecore(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.
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.
ExpressionInOCL	createInvariant(org.eclipse.emf.ecore.EObject contextElement, java.lang.String oclExpression) Parse oclExpression using selfType as the type of each run-time self object.
OCLHelper	createOCLHelper(org.eclipse.emf.ecore.EObject contextElement) Creates a new OCLHelper instance for convenient parsing of embedded constraints and query expressions for the specified context which may be an Ecore EClassifier/EOperation/EStructuralFeature or or Pivot Class/Operation/Property.
ExpressionInOCL	createPostcondition(org.eclipse.emf.ecore.EOperation contextOperation, java.lang.String oclExpression)
Query	createQuery(Constraint constraint) Creates a new Query encapsulating a constraint with the current environment and extent map.
ExpressionInOCL	createQuery(org.eclipse.emf.ecore.EObject contextElement, java.lang.String oclExpression)
Query	createQuery(ExpressionInOCL query) Creates a new Query encapsulating a query expression with the current environment and extent map.
ASResource	cs2as(CSResource 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	ecore2as(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).
void	finalize() If the user neglects to dispose(), then detach() the EnvironmentFactory to give it a chance to clean up.
CompleteEnvironment	getCompleteEnvironment()
Class	getContextType(java.lang.Object contextObject)
CSResource	getCSResource(org.eclipse.emf.common.util.URI uri)
CSResource	getCSResource(org.eclipse.emf.common.util.URI uri, java.io.InputStream inputStream)
CSResource	getCSResource(org.eclipse.emf.common.util.URI uri, java.lang.String testDocument)
EnvironmentFactory	getEnvironmentFactory()
IdResolver	getIdResolver()
MetamodelManager	getMetamodelManager()
ModelManager	getModelManager() Obtains the model manager, if any, provided by the client to customize the evaluation of constraints.
org.eclipse.emf.ecore.EPackage.Registry	getPackageRegistry()
ProjectManager	getProjectManager()
org.eclipse.emf.ecore.resource.ResourceSet	getResourceSet()
ExpressionInOCL	getSpecification(Constraint constraint) Return the Constraint specification as an ExpressionInOCL, parsing any OpaqueExpression that may be encountered.
StandardLibrary	getStandardLibrary()
boolean	isEvaluationTracingEnabled() Deprecated.
CSResource	load(org.eclipse.emf.common.util.URI uri) Deprecated.
static OCL	newInstance() Creates a new OCL with a new heavyweight ProjectManager and a new ResourceSet for loaded models.
static OCL	newInstance(EnvironmentFactory environmentFactory) Deprecated. use environmentFactory.createOCL()
static OCL	newInstance(org.eclipse.emf.ecore.EPackage.Registry ePackageRegistry) Creates a new OCL instance using the specified Ecore package registry.
static OCL	newInstance(ProjectManager projectManager) Creates a new OCL using the specified ProjectManager and a new ResourceSet for loaded models.
static OCL	newInstance(ProjectManager projectManager, org.eclipse.emf.ecore.resource.ResourceSet resourceSet) Creates a new OCL using the specified ProjectManager and exploiting the already loaded models and configuration of ResourceSet.
static OCL	newInstance(org.eclipse.emf.ecore.resource.ResourceSet resourceSet) Creates a new OCL with a new heavyweight ProjectManager and exploiting the already loaded models and configuration of ResourceSet.
ASResource	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.
ExpressionInOCL	parseSpecification(LanguageExpression specification) Convert the specification of an OCL expression from textual CS form to parsed executable AS form.
ExpressionInOCL	parseSpecification(java.lang.Object unusedObject, LanguageExpression specification) Deprecated. use parseSpecification(specification)
void	setEvaluationTracingEnabled(boolean b) Deprecated.
void	setModelManager(ModelManager modelManager) Assigns a custom extent map to define the extents of classes in evaluation of OCL constraints.
void	validate(Constraint constraint) Deprecated.
void	validate(OCLExpression expression) Deprecated.

Methods inherited from class java.lang.Object

clone, equals, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Field Detail

NO_PROJECTS

@NonNull
public static final ProjectManager NO_PROJECTS

A very lightweight ProjectManager that provodes no access to external projects.

CLASS_PATH

@NonNull
public static final ProjectManager CLASS_PATH

A heavyweight shared read-only ProjectManager that provides access to all external projects. When running standalone, the available projects are determined by analysis of plugin.xml files on the classpath. When running within Eclipse, the Eclipse workspace and extension points are used.

environmentFactory

protected EnvironmentFactoryInternal environmentFactory

The EnvironmentFactory that can create objects and which provides the MetamodelManager, CompleteEnvironment and StandardLibrary. This is non-null until the OCL is disposed. Any subsequent usage will provoke NPEs.

Constructor Detail

OCL

protected OCL(@NonNull
              EnvironmentFactoryInternal environmentFactory)

Initializes me with my environment factory and root environment.

Parameters:

environmentFactory - my environment factory

Method Detail

newInstance

@NonNull
public static OCL newInstance()

Creates a new OCL with a new heavyweight ProjectManager and a new ResourceSet for loaded models.

newInstance

@NonNull
public static OCL newInstance(@NonNull
                                        ProjectManager projectManager)

Creates a new OCL using the specified ProjectManager and a new ResourceSet for loaded models.

newInstance

@NonNull
public static OCL newInstance(@NonNull
                                        ProjectManager projectManager,
                                        @NonNull
                                        org.eclipse.emf.ecore.resource.ResourceSet resourceSet)

Creates a new OCL using the specified ProjectManager and exploiting the already loaded models and configuration of ResourceSet.

newInstance

@NonNull
public static OCL newInstance(@NonNull
                                        org.eclipse.emf.ecore.resource.ResourceSet resourceSet)

Creates a new OCL with a new heavyweight ProjectManager and exploiting the already loaded models and configuration of ResourceSet.

newInstance

@NonNull
public static OCL newInstance(org.eclipse.emf.ecore.EPackage.Registry ePackageRegistry)

Creates a new OCL instance using the specified Ecore package registry. Note that the returned OCL instance will use their own clean ResourceSet

See Also:

getResourceSet()

newInstance

@Deprecated
 @NonNull
public static OCL newInstance(@NonNull
                                                      EnvironmentFactory environmentFactory)

Deprecated. use environmentFactory.createOCL()

Creates a new OCL using the specified Ecore environment factory.

Parameters:

environmentFactory - an environment factory for Ecore

Returns:

the new OCL

as2cs

public void as2cs(@NonNull
                  ASResource asResource,
                  @NonNull
                  CSResource 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);

as2ecore

@NonNull
public org.eclipse.emf.ecore.resource.Resource as2ecore(@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

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, ExpressionInOCL), evaluate(Object, ExpressionInOCL)

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

specification - 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, ExpressionInOCL), evaluate(Object, ExpressionInOCL)

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.

createInvariant

@NonNull
public ExpressionInOCL createInvariant(@NonNull
                                                 org.eclipse.emf.ecore.EObject contextElement,
                                                 @NonNull
                                                 java.lang.String oclExpression)
                                          throws ParserException

Parse oclExpression using selfType as the type of each run-time self object.

Throws:

ParserException

createPostcondition

public ExpressionInOCL createPostcondition(@NonNull
                                           org.eclipse.emf.ecore.EOperation contextOperation,
                                           @NonNull
                                           java.lang.String oclExpression)
                                    throws ParserException

Throws:

ParserException

createOCLHelper

@NonNull
public OCLHelper createOCLHelper(@Nullable
                                           org.eclipse.emf.ecore.EObject contextElement)

Creates a new OCLHelper instance for convenient parsing of embedded constraints and query expressions for the specified context which may be an Ecore EClassifier/EOperation/EStructuralFeature or or Pivot Class/Operation/Property.

Returns:

a new helper object

createQuery

@NonNull
public ExpressionInOCL createQuery(@Nullable
                                             org.eclipse.emf.ecore.EObject contextElement,
                                             @NonNull
                                             java.lang.String oclExpression)
                                      throws ParserException

Throws:

ParserException

createQuery

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

createQuery

public Query createQuery(@NonNull
                         Constraint constraint)
                  throws ParserException

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

Throws:

ParserException

See Also:

createQuery(ExpressionInOCL)

cs2as

@NonNull
public ASResource cs2as(@NonNull
                                  CSResource 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 detaches the OCL instance from the corresponding environment factory which will release its resources once there are no further attached OCL clients.

dispose() should be invoked to release resources promptly. If a call to dispose() is omitted, finalize() will detach() when garbage collection of the OCL instance occurs.

ecore2as

@NonNull
public ASResource ecore2as(@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).

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:

check(Object, ExpressionInOCL)

finalize

public void finalize()

If the user neglects to dispose(), then detach() the EnvironmentFactory to give it a chance to clean up.

Overrides:

finalize in class java.lang.Object

getCSResource

@NonNull
public CSResource getCSResource(@NonNull
                                          org.eclipse.emf.common.util.URI uri)
                                   throws java.io.IOException

Throws:

java.io.IOException

getCSResource

@NonNull
public CSResource getCSResource(@NonNull
                                          org.eclipse.emf.common.util.URI uri,
                                          @NonNull
                                          java.io.InputStream inputStream)
                                   throws java.io.IOException

Throws:

java.io.IOException

getCSResource

@NonNull
public CSResource getCSResource(@NonNull
                                          org.eclipse.emf.common.util.URI uri,
                                          @NonNull
                                          java.lang.String testDocument)
                                   throws java.io.IOException

Throws:

java.io.IOException

getCompleteEnvironment

@NonNull
public CompleteEnvironment getCompleteEnvironment()

getContextType

public Class getContextType(@Nullable
                            java.lang.Object contextObject)

getEnvironmentFactory

@NonNull
public EnvironmentFactory getEnvironmentFactory()

getIdResolver

@NonNull
public IdResolver getIdResolver()

getMetamodelManager

@NonNull
public MetamodelManager getMetamodelManager()

getModelManager

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

getPackageRegistry

public org.eclipse.emf.ecore.EPackage.Registry getPackageRegistry()

getProjectManager

@NonNull
public ProjectManager getProjectManager()

getResourceSet

@NonNull
public org.eclipse.emf.ecore.resource.ResourceSet getResourceSet()

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

getStandardLibrary

@NonNull
public StandardLibrary getStandardLibrary()

isEvaluationTracingEnabled

@Deprecated
public boolean isEvaluationTracingEnabled()

Deprecated.

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)

load

@Deprecated
 @Nullable
public CSResource load(@NonNull
                                                org.eclipse.emf.common.util.URI uri)

Deprecated.

Load the Complete OCL document specified by the URI into the external ResourceSet and return the concrete syntax resource.

parse

@Nullable
public ASResource 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.

parseSpecification

@NonNull
public ExpressionInOCL parseSpecification(@NonNull
                                                    LanguageExpression specification)
                                             throws ParserException

Convert the specification of an OCL expression from textual CS form to parsed executable AS form. The textual form typically results from simple construction from source text or a UML OpaqueExpression.

The returned object may be the same object as the specification, but with the more derived type to signify successful conversion from textual to executable form. Redundant re-invocation of parseSpecification is harmless.

The specification's container, typically a Constraint or Operation is used as the contextElement to determine self within the expression.

Throws:

ParserException - if text parsing fails

parseSpecification

@Deprecated
 @NonNull
public ExpressionInOCL parseSpecification(@Nullable
                                                                  java.lang.Object unusedObject,
                                                                  @NonNull
                                                                  LanguageExpression specification)
                                                           throws ParserException

Deprecated. use parseSpecification(specification)

Throws:

ParserException

setEvaluationTracingEnabled

@Deprecated
public void setEvaluationTracingEnabled(boolean b)

Deprecated.

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
                            ModelManager 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

validate

@Deprecated
public void validate(@NonNull
                                  OCLExpression expression)
                           throws SemanticException

Deprecated.

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

validate

@Deprecated
public void validate(@NonNull
                                  Constraint constraint)
                           throws SemanticException

Deprecated.

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