Notice: This Wiki is now read only and edits are no longer possible. Please see: https://gitlab.eclipse.org/eclipsefdn/helpdesk/-/wikis/Wiki-shutdown-plan for the plan.
Servus 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.
Contents
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 EAnnotation
s 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:
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 EClass
es). 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 EPackage
s.
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
WebEndpoint
s 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 theWebInterface
'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 sameWebService
's name but point to differentWebInterface
s.
- for WSDLv1, we aggregate the endpoints based on their corresponding
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 WebBinding s 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 WebService s in the host, uses the unique if present, or a default if no WebService s 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 WebInterface s in the host, uses the unique if present, or a default if no WebInterface s 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:
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:
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:
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:
- This annotation uses the MessagePattern enumeration which is mapped as follows:
-
InOnly
maps to One-Way Operation inWSDLv1
and http://www.w3.org/ns/wsdl/in-only inWSDLv2
-
InOut
maps to Request-Response Operation inWSDLv1
and http://www.w3.org/ns/wsdl/in-out inWSDLv2
-
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 |