Difference between revisions of "Sphinx/digests"

Latest revision as of 03:06, 21 July 2020

Dynamic workflows

Main capabilities

• Based on MWE2 workflows
• Can be written in Java or Xtend
• Can operate on EMF models (handed in and out via slots)
• Dymamic execution of workflows located in workspace (i.e., within same JVM instance)
• Execution of binary workflows located in workflow contributor plug-ins

Extras

• Command line execution
• Workflow handlers (pre/post run hooks)
• Support of metamodels without Sphinx integration

How-tos

Create a new dyamic/binary workflow

• Create a plug-in project in runtime/development workspace
• Add a dependency to the org.eclipse.sphinx.emf.mwe.dynamic plug-in
• Create a Java or Xtend class that extends WorkspaceWorkflow
• Create Java or Xtend classes that extend AbstractWorkspaceWorkflowComponent or AbstractModelWorkflowComponent
• Add workflow components to workflow

Contribute a binary workflow

• Use org.eclipse.sphinx.emf.mwe.dynamic.workflowContributors extension point

Run a dynamic or binary workflow interactively

• Right-click on workflow file to execute or model file(s)/element(s) to operate on
• Select Run Workflow > Run...

Run a dynamic or binary workflow from the command line

• Use org.eclipse.sphinx.emf.mwe.dynamic.headless.WorkflowRunner application
• Specify workspace-relative workflow path or qualified workflow class name using -workflow option
• Specify absolute/relative model file/element URI using -model option

Create a workflow handler

• Use org.eclipse.sphinx.emf.mwe.dynamic.workflowHandlers extension point

Related examples

• org.eclipse.sphinx.examples.workflows
• org.eclipse.sphinx.examples.workflows.lib
• org.eclipse.sphinx.examples.hummingbird20.workflows
• org.eclipse.sphinx.examples.library.workflows

Check validation

Main capabilities

• Lightweight approach to model validation
• Based on EMF's EValidator and Diagnostician
• Constraint logic in Java or Xtend classes with @Check annotated methods
• Optional externalization of severities, messages, etc. to EMF-based check catalog
• Organization of checks in categories
• Produces EMF Diagnostics and Eclipse problem markers
• Dedicated Check Validation view

Extras

• Navigation from Check Validation view entries to related model element in
  • Double-click → associated editor
  • Show-In menu → Model Explorer, Project Explorer, Properties view
• Execution of EMF's intrinsic model integrity constraints (EObjectValidator)
• Execution of check validations in workflows

How-tos

Create a new check validator

• Create a Java or Xtend class that extends AbstractCheckValidator
• Create check method(s) that have
  • an @Check annotation
  • precisely one parameter through which the model element to be checked can be passed
• Implement check logic and issue findings using protected error()/warning()/info()/issue() methods
• Contribute check validator to org.eclipse.sphinx.emf.check.checkvalidators extension point

Run a check validation interactively

• Right-click on model file(s)/element(s) to be checked
• Select Validate > Check-based Validation
• View result in Check Validation view

Create and use a check catalog

• Create a copy of /org.eclipse.sphinx.emf.check.catalog/model/samples/Empty.checkcatalog and open it in Sample Reflective Ecore Model Editor
• Edit Catalog properties and add Category and Constraint children as appropriate
• Associate check methods in check validators with constraints by adding a constraint field to the check method's @Check annotation that refers to the id of the corresponding constraint in the check catalog
• Optionally restrain applicability of the check method by adding a categories field to @Check annotation that lists only a subset of the categories referenced by corresponding constraint in the check catalog
• Issue check findings using protected issue() method rather than error()/warning()/info() methods
• Contribute check catalog and associate it with contributed check validators to org.eclipse.sphinx.emf.check.checkvalidators extension point

Reference information

Diagnostic usage

• severity → Constraint severity as per error()/warning()/info() method invocation or check catalog
• source → Qualified check validator class name
• code → not used, always 0
• message → Constraint message as per error()/warning()/info() method invocation or check catalog
• data →
  • DiagnosticLocation referencing affected model object and feature in first position
  • SourceLocation referencing underlying check validator class, check method and constraint id in second position
  • optional user-defined data as per error()/warning()/info() method invocation on subsequent positions

Check Problem marker usage

• EValidator.URI_ATTRIBUTE → URI of affected model object
• IMarker.LOCATION → Name of affected model object class and feature extracted from diagnostic data
• IMarker.SEVERITY → Diagnostic severity
• IMarker.MESSAGE → Diagnostic message
• IMarker.SOURCE_ID → Constraint id or name of underlying check validator class and method extracted from diagnostic data if available or diagnostic source otherwise

Related examples

• org.eclipse.sphinx.examples.hummingbird20.check

Viatra Query integration

Main capabilities

• Fast queries on big models using Viatra Query pattern language (*.vql files) and powerful indexing backend
• Easy to use Sphinx-defined model query service providing common model queries (e.g., all instances of)
• Possibility to implement and use custom model queries alongside
• Full awareness of Sphinx resource scoping

Extras

• Fast index-based resolution of proxy objects (i.e., cross-document references)

How-tos

Contribute a Sphinx model query service for a given metamodel

• Implement the queries exposed by the Sphinx model query service for the given metamodel using Viatra Query pattern language (*.vql files)
• Create a Java or Xtend class extending AbstractMatcherProvider for every EPackage of the metamodel in question
• Override and implement initSupportedTypes() and getMatcher() methods by invoking appropriate Viatra Query-generated query matchers on provided ViatraQueryEngine instance
• Create a Java or Xtend class extending
  • AbstractModelQueryService → to implement a model query service that considers all instances of the given metamodel in the workspace
  • AbstractWorkspaceModelQueryService → to implement a model query service that is aware of Sphinx resource scoping and only considers the metamodel instance behind the context object passed to the model query service method being invoked
• Override and implement initMatcherProviders() method by adding the matcher provider instances for every EPackage of the metamodel to the model query service's list of matcher providers
• Contribute service to org.eclipse.sphinx.emf.metaModelServices extension point

Use Sphinx model query service

• Acquire Sphinx model query service for metamodel in question using DefaultMetaModelServiceProvider helper class
• Invoke model query service method (e.g., getAllInstancesOf()) providing appropriate context object and query parameters
• Handle resulting model objects as appropriate

Create and use a custom model query

• Implement the custom query as appropriate using Vatra Query pattern language (*.vql files)
• Create an ViatraQueryEngine instance by calling getEngine() on
  • ViatraQueryEngineHelper → to consider all instances of the given metamodel in the workspace
  • WorkspaceViatraQueryEngineHelper → to be aware of Sphinx resource scoping and consider only the metamodel instance behind the context object being passed to getEngine()
• Invoke Viatra Query-generated custom query matcher on ViatraQueryEngine instance
• Handle resulting model objects as appropriate

Contribute a Sphinx proxy resolver service for a given metamodel

• Create proxy resolution queries as appropriate for the proxy URI format used by given metamodel using Viatra Query pattern language (*.vql files)
• Create a Java or Xtend class extending AbstractProxyResolver for every EPackage of the metamodel in question
• Override and implement initSupportedTypes() and getEObjectCandidates() methods by invoking Viatra Query-generated proxy resolution query matchers on provided ViatraQueryEngine instance
• Create a Java or Xtend class extending AbstractProxyResolverService
• Override and implement initProxyResolvers() method by adding a proxy resolver instance for every EPackage of the metamodel to the proxy resolver service's list of proxy resolvers
• Override and implement getTargetEClass() as appropriate
• Contribute service to org.eclipse.sphinx.emf.metaModelServices extension point

Related examples

• org.eclipse.sphinx.examples.hummingbird20.viatra.query
• org.eclipse.sphinx.examples.hummingbird10.viatra.query
• org.eclipse.sphinx.tests.emf.viatra.query

Model search

Main capabilities

• Search for model elements with a given name or name pattern
• New Model Search tab in Eclipse Search dialog
• Matches shown in Eclipse Search view
• Java-based default implementation of model search service

Extras

• Model search service can be overridden with an alternative or Viatra Query-based implementation on a per-metamodel basis
• Navigation from Search view entries to related model element in
  • Double-click → associated editor
  • Show-In menu → Model Explorer, Project Explorer, Properties view

How-tos

Perform a model search

• Select Search > Search... > Model Search
• Enter model element name or name pattern
• Optionally choose additional search options
• Click on Search and see matches in Search view

Contribute a simple custom search service for a given metamodel

• Create a Java or Xtend class implementing IModelSearchService
• Implement getMatches() methods as appropriate
• Contribute service to org.eclipse.sphinx.emf.metaModelServices extension point

Contribute an Viatra Query-based custom search service for a given metamodel

• Create a search query as appropriate to find elements of the given metamodel by their name using Viatra Query pattern language (*.vql file)
• Create a Java or Xtend class extending AbstractViatraQueryModelSearchService
• Override an implement getMatches() method by leveraging Viatra Query-generated search query matcher
• Contribute service to org.eclipse.sphinx.emf.metaModelServices extension point

Related examples

• org.eclipse.sphinx.examples.hummingbird20.viatra.query

EMF Compare integration

Main capabilities

• Comparison of Sphinx-managed models without having to reload them in the compare editor
• Operation on model files or model elements
• Synchronization of compare editor dirty and save state with that of underlying Sphinx-managed models

Extras

• Automatic generation of comparison reports

How-tos

Compare/merge 2 model files/elements

• Right-click on model files/elements to be compared/merged
• Select Compare With > Each Other
• Inspect differences and perform merge operations using corresponding compare editor controls

Save model after comparison/merge

• Save from compare editor
• Save in Model Explorer
• Save from any other Sphinx-based form editor or graphical editor

Contribute a new comparison report generator

• Created a Java or Xtend class that extends AbstractModelCompareReportGenerator
• Override and implement postDiff() and doGenerate() methods as appropriate
• Contribute comparison report generator to org.eclipse.emf.compare.rcp.postProcessor extension point

Related examples

• org.eclipse.sphinx.examples.emf.compare.reports.csv
• org.eclipse.sphinx.examples.emf.compare.reports.html

References view

Main capabilities

• Navigation along the cross-references (i.e., all non-containment reference) of the currently selected model element
• Shows either all cross-referenced model elements or all cross-referencing model elements

Extras

• Navigation from References view entries to related model element in
  • Double-click → associated editor
  • Show-In menu → Model Explorer, Project Explorer, Properties view

How-tos

Display references of a model element

• Right-click on the model element in question
• Select Open References
• View result in References view

Documentation view

Main capabilities

• Display of formatted documentation for currently selected model element (e.g., data from an EAnnotation on the underlying EClass)
• Rendering as HTML using Bootstrap and jQuery
• Generation of documentation view content with Xtend
• Customizable on a per-metamodel basis

How-tos

Contribute a documentation view formatter for a given metamodel

• Create an Xtend class extending AbstractDocumentationViewFormatter
• Override and implement formatHeader() and formatSpecific() methods as appropriate
• Contribute formatter to org.eclipse.sphinx.platform.ui.documentationViewFormatters extension point

Related examples

• org.eclipse.sphinx.examples.views.documentation