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

Difference between revisions of "Servus Annotations"

(Web Services Annotations)
(Web Services Annotations)
Line 225: Line 225:
 
|-
 
|-
 
|}
 
|}
 +
  
  
Line 266: Line 267:
 
|-
 
|-
 
|}
 
|}
 +
 +
  
 
===WebOperation===
 
===WebOperation===

Revision as of 17:52, 24 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 or when a ServusWrapperAnnotation is used. 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:

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.
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.
namespace The namespace of the annotation. Usually this attribute is unnecessary, but it is used if elements of different namespaces 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, but can be customized by a unique WebPackage annotation attached to it. We will also discuss this attribute for each annotation, as it maps to different entities in WSDL and JAX-WS.
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

Servus Web Services Annotations are used to attach Web Services specific information to Ecore models. The information that can be described by these annotations is a super set of the information provided by WSDL versions 1 and 2, while trying to keep a nomenclature close to WSDLv2. This means that Web Services models described by any version of WSDL can be translated to an Ecore model annotated with Servus Annotations; however, we can create models that are not representable in both WSDL versions and tooling is needed to alert the developer of the situation.

WS Annotations can be seen as part of three groups. The first group is composed of annotations that describe the general structure of the Web Services and are comparable to classes and interfaces (they are usually attached to EClasses). The most important of those is the WebEndpoint. It is used on top of an EClass to indicate that the class represents a Web Service that can be accessed or deployed at a certain address. It connects all other annotations of this group (WebService, WebInterface and WebBinding) and is the only mandatory annotation (meaning that we can always assume default values for other annotations, but not for the WebEndpoint). The additional annotations are used merely to customize default values.

A second group contains annotations that describe the operations, including their parameters and return types, and are usually attached to an EOperation or EParameter. These annotation are: WebOperation, WebInput, WebOutput and WebFault. The last group contains annotations used only to customize the package name (WebPackage) and to store WSDLv1 specific information (WebMessage) and are attached to EPackages.

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> element.

WSDLv2 Mapping: Maps to an <endpoint> element inside a <service> element.

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

Notes:

  • The WebEndpoint is the glue that connects all top-level annotations. The additional annotations are only used to customize values and, hence, are optional.
  • This annotation creates a link between one interface, one binding and one service. If there are many WebEndpoints in the same EClass, the mapping goes as follows:
    • for WSDLv1, we aggregate the endpoints based on their corresponding WebService's names. That's because in WSDLv1 a single <service> can implement many interfaces since the <portType> link occurs through the <port> element.
    • JAX-WS is currently only compatible with WSDLv1. Therefore, we aggregate the endpoints like WSDLv1 to generate source code.
    • for WSDLv2, we aggregate the endpoints based on both the WebService's names and the WebInterface's names. That's because in WSDLv2 a <service> can implement only a single interface. This means that some Servus models are not compatible with WSDLv2, in the unlikely case that there are enpoints that have the same WebService's name but point to different WebInterfaces.
WebEndpoint attributes
Attribute Description Default Value WSDLv1 Mapping WSDLv2 Mapping JAX-WS Mapping
name Used to customize the name of the endpoint. The EClass non-qualified name. Maps to a <port>'s name attribute. Maps to an <endpoint>'s name attribute. In a Client Proxy, maps to the of the port's getter and to a @WebEndpoint annotation's name. In a Server, maps to a @WebService's portName.
namespace This attribute is ignored on this annotation, as the namespace is determined by the corresponding WebService annotation.
address Determines the address where the endpoint is exposed. There is no default, this attribute is mandatory. Maps to a <port>'s <soap:address>'s location attribute, or a corresponding attribute if a different binding is used. Maps to a <service>'s address attribute. In a Client Proxy, maps to the URL of a constructor and to a @WebServiceClient annotation's wsdlLocation. In a Server, maps to a @WebService's wsdlLocation. In these cases, the string ?wsdl is appended to the address.
binding Determines the binding in use by the endpoint, by pointing to a WebBinding annotation. If there is a unique WebBinding annotation in the host EClass, points to it. If there are no bindings, points to a WebBinding with default values. If there are multiple WebBindings in the host, this attribute is mandatory. Determines the link of the <port>'s binding attribute. Determines the link of the <endpoint>'s binding attribute. This attribute is not mapped directly to JAX-WS, but indicates which bindings are used in the classes.
service Determines the service that contains this endpoint, by pointing to a WebService annotation. Similar to the binding attribute, this is mandatory for multiple WebServices in the host, uses the unique if present, or a default if no WebServices are found in the host. Determines the WebService that will create the enclosing <service> element. This attribute is not mapped directly to JAX-WS, but indicates which services are used to generate the classes.
interface Determines the interface implemented by the endpoint, by pointing to a WebInterface annotation. Similar to the previous attributes, this is mandatory for multiple WebInterfaces in the host, uses the unique if present, or a default if no WebInterfaces are found in the host. Determines the link of the <binding>'s type attribute. Determines the link of the <service>'s interface attribute and possibly of the <binding>'s type attribute (if the binding is not generic). This attribute is not mapped directly to JAX-WS, but indicates which are used sources are used to generate the service's interface.


WebService


Host Ecore Types: EClass or EPackage.

Description: Used to customize the name of the Web Service. It can be hosted by an EPackage if the service contains zero Endpoints or, in the case of WSDLv1 if the service implements many interfaces. It can be hosted by an EClass, indicating that it customizes the interface represented by the class or its super classes.

WSDLv1 Mapping: Maps to a <service> element.

WSDLv2 Mapping: Maps to a <service> element.

JAX-WS Mapping: TODO

Notes:

WebEndpoint attributes
Attribute Description Default Value WSDLv1 Mapping WSDLv2 Mapping JAX-WS Mapping
name Used to customize the name of the web service. The non-qualified name of the host (EClass or EPackage) Maps to a <service>'s name attribute. TODO
namespace Used to customize the namespace of the web service. See ServusAnnotation's namespace attribute. Identifies to which <definitions> the <service> element belongs. Identifies the package of the generated artifacts, and maps to the targetNamespace attribute of @WebService and @WebServiceClient


WebBinding


Host Ecore Types: EClass.

Description: Used to customize the name of the Web Binding and additional binding information. This is an abstract annotation that is never directly used. Instead, developers should use protocol specific annotations, such as SOAPBinding.

WSDLv1 Mapping: Maps to a <binding> element.

WSDLv2 Mapping: Maps to a <binding> element.

JAX-WS Mapping: TODO

Notes:

WebEndpoint attributes
Attribute Description Default Value WSDLv1 Mapping WSDLv2 Mapping JAX-WS Mapping
name Used to customize the name of the binding. The non-qualified name of the host EClass Maps to a <binding>'s name attribute. TODO
namespace Used to customize the namespace of the binding. See ServusAnnotation's namespace attribute. Identifies to which <definitions> the <binding> element belongs. TODO


WebInterface


Host Ecore Types: EClass.

Description: Used to customize the name of the web interface.

WSDLv1 Mapping: Maps to a <portType> element.

WSDLv2 Mapping: Maps to an <interface> element.

JAX-WS Mapping: TODO

Notes:

WebEndpoint attributes
Attribute Description Default Value WSDLv1 Mapping WSDLv2 Mapping JAX-WS Mapping
name Used to customize the name of the interface. The non-qualified name of the host EClass. Maps to a <portType>'s name attribute. Maps to an <interface>'s name attribute. TODO
namespace Used to customize the namespace of the interface. See ServusAnnotation's namespace attribute. Identifies to which <definitions> the <portType> element belongs. Identifies to which <definitions> the <interface> element belongs. TODO


WebOperation


Host Ecore Types: EOperation.

Description: Used to customize the name of the operation and keep many WSDLv1-specific names that are not relevant but are needed to achieve round-trip, as well as WSDLv2-specific operation style.

WSDLv1 Mapping: Maps to an <operation> element inside a <portType> element.

WSDLv2 Mapping: Maps to an <operation> element inside a <interface> element.

JAX-WS Mapping: TODO

Notes:

WebEndpoint attributes
Attribute Description Default Value WSDLv1 Mapping WSDLv2 Mapping JAX-WS Mapping
name Used to customize the name of the operation. The name of the host EOperation. Maps to an <operation>'s name attribute. TODO
namespace Used to customize the namespace of the interface. This attribute is ignored on this annotation, as the namespace is determined by the corresponding WebInterface annotation.
pattern Used to determine the message pattern of the operation. The In/Out pattern. Determines if the <operation> has <input>s and <output>s Maps to an <operation>'s pattern attribute. TODO
inputName Determines the name of the <input> element inside an <operation> element. Note that only a single <input> is allowed per <operation>. The default is null (no name). Maps to an <input>'s name attribute. Not mapped. TODO
outputName Determines the name of the <output> element inside an <operation> element. Note that only a single <output> is allowed per <operation>. The default is null (no name). Maps to an <output>'s name attribute. Not mapped. TODO
inputMessageName Determines the name of the <message> element used by the <operation>'s <input> element. Note that only a single <message> is allowed per <operation> (through it's input). The default is null (no name). Maps to a <message>'s name attribute. Not mapped. TODO
style Determines the style of the <operation> in WSDLv2 The default is "http://www.w3.org/ns/wsdl/rpc" Not mapped. Maps to a <operation>'s style attribute. TODO

SOAP Annotations

Back to the top