Skip to main content

Notice: this Wiki will be going read only early in 2024 and edits will no longer be possible. Please see: https://gitlab.eclipse.org/eclipsefdn/helpdesk/-/wikis/Wiki-shutdown-plan for the plan.

Jump to: navigation, search

Servus API

This document details Servus' API. First, we give an overview of the plugins implemented by Servus, and then we detail the important abstractions of the plugins.

Plugins

Servus plugins use the base package org.eclipse.emf.servus. We will omit this part of the package names for brevity. The exception is the core package, which has exactly this signature, and will be therefore referenced by Core. This list contains the plugins already created in the CVS. Additional plugins must be created to complete the tool support, such as additional transformations and integration with the Eclipse IDE to drive the transformations.

Main Plugins

  • metamodel - defines the Servus meta-model as an Ecore model.
  • Core - defines the API for all transformations and the data structures used by the transformation, as well as utility classes. Also defines extension points to be implemented by transformations.

Support Plugins

  • app - implements command line applications to run the transformations.
  • app.tests - implements simple tests to drive the command line applications.
  • samples - a container for sample artifacts used to test the applications. Contains WSDL documents, Servus models, Ecore models and so on.
  • rule - a simple rule framework that allows transformations to be defined as AST traversals and typed rules.

WSDLv1 Plugins

The WSDLv1 Plugins depend on the wsdl4j library (javax.wsdl version 1.6.2), which can be imported as an orbit bundle.

  • wsdlv1 - implements the extension points related to WSDL version 1, which defines transformations between WSDLv1 and Servus models.
  • wsdlv1.wsdl2servus - uses the rule framework to implement the transformation from WSDL to Servus.
  • wsdlv1.servus2wsdl - uses the rule framework to implement the transformation from Servus to WSDL.

JAX-WS Plugins

  • jaxws - implements the extension point related to JAX-WS, i.e,. implements a Servus to JAX-WS-based Java source code.

GUI Plugins

  • metamodel.edit - edit functionality for the Servus meta-model.
  • metamodel.editor - a simple editor for the Servus meta-model.

Profile Plugins

  • profile - implements the extension point related to the Profile, which defines transformations between Servus models and profiled Ecore models.
  • profile.servus2ecore - uses the rule framework to implement the transformation from Servus to Ecore.

Plugin Dependencies

The following diagram sketches the dependencies between the plugins. Dependencies are transitive.

Plugins.jpg

The Core Plugin

The Core plugin (org.eclipse.emf.servus) defines the main API for using Servus' functionalities. This section describes its abstractions and data structures.

Containers

Servus manipulates many different types of artifacts. In order to simplify interfaces between transformations, Servus uses Container abstractions to encapsulate those artifacts. Besides carrying the artifacts around, containers are also responsible for knowing how to load and store the artifacts to URIs, usually using EMF's Resources and ResourceSets. The following containers are defined:

ServusContainer

Represents the data related to the Servus space, i.e., it carries the Servus models and the referenced Ecore models (as DataModels). Data Models encapsulate an Ecore EPackage together with additional information, such as the Extended Meta-data used to create the EPackage from XSD and the source WSDL types element. Servus Models encapsulate a WebServicesDescription (defined by the meta-model) with additional information, such as its URI.

The container can store its contents (all Servus and Data models) to resources pointed by an URI. Furthermore, given an URI to a Servus model and to its referenced Data models, it can load them, together with all referenced Servus models.

WSDLContainer

Represents the data related to the WSDL space. It carries WSDL documents and the XSD documents referenced by them. XSDDocuments contain the XSDSchema root object and the corresponding URI. WSDLDocument is an abstract class that must be implemented by different versions of WSDL.

ProfileContainer

Represents the data related to the profile version of a ServusContainer. It contains the same DataModels as the ServusContainer, but instead of ServusModels it carries a profiled EPackage.

ConfigurationContainer

This container is passed around to carry configuration data to transformations. It loads configuration from a map to support tape-safe access to it, also considering the defaults.

Transforms

Transforms are implementations of transformations. Simple Transforms implement a single transformation between two artifacts, such as between a WSDL document and a Servus model. TransformComposition is a transformation that composes two simple Transforms. For example, the WSDLProfileTransform combines WSDLServusTransform with ServusProfileTransform.

The transforms have very clear APIs. Their names represent the source and target artifact spaces concatenated (e.g., WSDLServusTransform will get WSDL artefacts and transform into Servus artefacts). They define only transform methods that take as parameters the artifacts that they need as input (or their URIs) and return containers that carry the result of the transformation. If the result is not an object, such as in JAX-WS code generation, the method returns void.

The following simple transforms are defined:

  • WSDLServusTransform
  • ServusWSDLTransform
  • ServusJAXWSTransform
  • ServusProfileTransform
  • ProfileServusTransform

The following transform compositions are defined:

  • WSDLProfileTransform
  • ProfileWSDLTransform

Helpers

Throughout the source code, Servus tries to define very focused classes. Therefore, it extensively makes use of Helper classes, which carry functionality that is not specific for the class that is using them, and that can usually be reused by other classes. The Core plugin defines the NameHelper class, which provides utility methods for manipulating names, such as transforming between Java and NC names, getting corresponding getters and setters for an attribute and so on.

Back to the top