Revision as of 14:21, 11 July 2008

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.

Notation

In the next section, we use the following notation:

• code style is used on Servus Model Annotations, classes and XML elements, like WebEndpoint, EClass and <port>.
• a regular Java annotation is also in code style, but prefixed by an @, like @WebMethod
• an annotation attribute is written in italics, like namespace, unless it is a table's first column, when it is bold.

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. They are both defined by an Ecore meta-model found in the org.eclipse.emf.servus.annotation project.

All annotations can be represented in 2 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. A model using these annotations conforms to the annotations meta-model. The EAnnotation form is the one regularly used in Ecore models. It uses regular EAnnotations with the appropriate the source attribute (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. The ServusAnnotation class provides methods to transform between these two forms.

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

Web Services Annotations

WebEndpoint

Host Ecore Types: EClass.

Description: Defines that the EClass represents a Web Service Endpoint. An endpoint defines that a web interface is exposed at an address using a certain binding.

WSDLv1 Mapping: Maps to a <port> element inside a <service>.

JAX-WS Mapping: Maps to a Server Skeleton implementation and a Client Proxy (that extends javax.xml.ws.Service)

WebService

WebBinding

SOAP Annotations