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 Annotations

Revision as of 13:00, 11 July 2008 by Ttonelli.swen.uwaterloo.ca (Talk | contribs) (Annotations)

Attention : This is work in progress, meaning that the annotations described here are not yet guaranteed to be kept later or to be used with this semantics. However, it is unlikely that they will change a lot, so it can be used to understand what can be done with Servus annotations.

Overview

Servus deals with WSDL documents, Ecore models and Java source code. Servus Model Annotations are a way to express Web Services related information by decorating any Ecore model.

Goals

The main goals of the annotations are to be:

Complete with respect to WSDL

This means that all information available in WSDL documents (versions 1 and 2) can be encoded in the annotations of an Ecore model. If this property is achieved, we can have a full round-trip between WSDL documents and Ecore models, without ever losing information.

As we will see later, there's just one aspect of WSDLv1 that currently cannot be encoded in Servus Annotations: the different files. This means that when we transform from WSDL to Ecore we might lose track of the WSDL files used to create the model. All information is there, but if we now go from Ecore to WSDL we might get a different set of files. However, this just happens if the files contain the same namespace, which is allowed but is not a good practise.

Minimalistic

This means that Servus Annotations have defaults for almost all information, so that they can be left implicit in the model. In fact, the only characteristic of WSDL that cannot be directly encoded in an Ecore model with defaults is the URL of the service. Therefore, a simple WebEndpoint annotation containing an URL and stored in an EClass is enough to represent a full web service (Servus will fill the blanks with defaults, like using SOAP, Document, Literal, etc).

Model Representations

Because Servus extensively relies on implicit information, it is convenient to define 3 different representations (or views) of the same Ecore model, with respect to the Servus Annotations that it carries:

  • actual representation - this view contains the Servus Annotations that are actually stored in the model. This is what a developer sees in the regular editor while manipulating the model.
  • full representation - this view is derived by filling all defaults on the actual representation. It explicitly contains every piece of information of the model. This is useful for developers to understand the implicit information and for tools to generate source code or WSDL documents.
  • compact representation - this view is derived by removing all defaults from the actual representation. Every piece of information that could be inferred by defaults is removed and the model is as clean as possible. This is useful for developers, because it makes the model much smaller, hiding most of the complexity.

Note that the actual representation can be at any point between the full and compact representations. For example, if we start from WSDL, we usually get a full representation, but we can clean it to become a compact representation. If we start from Ecore, we might add a single WebEndpoint annotation and we have the compact representation directly.

Annotations

Currently, there are 2 sets of Servus Annotations. The Web Services Annotations are generic Web Services related annotations. The SOAP Annotations are specific to encode SOAP binding information. All annotations have an EAnnotation and a ServusAnnotation forms. In the ServusAnnotation form, all attributes of the annotation are encoded as fields in a class deriving from ServusAnnotation. This is used for internal manipulation of the annotations and when a ServusWrapperAnnotation is used (more on this later). The EAnnotation form is the one regularly used in Ecore models. It uses the source attribute as the EAnnotation's source (to identify the type of the annotation) and the remaining attributes are encoded as key/value pairs of the details map, using the attribute's name as key.

All annotations extend a basic ServusAnnotation and therefore contain the following attributes:


ServusAnnotation Attributes
Name Description Default Value
source Identifies the type of the annotation. There are no defaults, every annotation has it's own source, defined by http://org/eclipse/emf/servus/annotation/ + the annotation name.
namespace The namespace of the annotation. Usually this attribute is unnecessary, but it is used if elements of different annotations are in the same EPackage. The value of the namespace of the EPackage in which the annotation resides. The namespace of the EPackage is its nsURI.
name Used to customize the name of the element, in case it is different from the default based on the carrying Ecore element. Depends on the annotation. Therefore, we will discuss this attribute on each annotation bellow.
fullyQualifiedName Used to identify this annotation in a model. It is derived from namespace + "#" + name, and should uniquely identify the annotation. There's no default. This is a derived attribute.


Web Services Annotations

WebEndpoint

Source bla
Description bla
Ecore Types There are no defaults, every annotation has it's own source hard coded.

WebService

WebBinding

SOAP Annotations

Back to the top