| <?xml version="1.0" encoding="UTF-8"?> |
| <org.eclipse.epf.uma:ContentDescription xmi:version="2.0" |
| xmlns:xmi="http://www.omg.org/XMI" xmlns:org.eclipse.epf.uma="http://www.eclipse.org/epf/uma/1.0.5/uma.ecore" |
| xmlns:epf="http://www.eclipse.org/epf" epf:version="1.5.0" xmi:id="-z4b7YSb0hoz7fKqCWsc8uQ" |
| name="new_guideline,_YRiuIItDEd2gksNyFVJN4g" guid="-z4b7YSb0hoz7fKqCWsc8uQ" changeDate="2008-09-25T13:49:34.281-0700"> |
| <mainDescription><p>
 |
| W3C defines web service as: "A Web service is a software application identified by a URI, whose interfaces and binding
 |
| are capable of being defined, described, and discovered by XML artifacts, and supports direct interactions with other
 |
| software applications using XML-based messages via Internet-based protocols."
 |
| </p>
 |
| <p>
 |
| In software architecture literature It is agreed that the XML syntax to define the web service is WSDL.
 |
| </p>
 |
| <h3>
 |
| Three Approaches
 |
| </h3>
 |
| <p>
 |
| From a methodology point of view there are three possible approaches to design a web service:
 |
| </p>
 |
| <ul>
 |
| <li>
 |
| <em>top-down</em>: The architect&nbsp;first defines the Web service interface using WSDL and XML Schema (XSD)
 |
| constructs, then generates implementation code for the service.
 |
| </li>
 |
| <li>
 |
| <em>bottom-up</em>: from the developer environment like eclipse, we can create a web service and wsdl from an
 |
| existing java code. The JAX-WS specification&nbsp;defines annotations to put in the code to&nbsp;define the
 |
| service.&nbsp;
 |
| </li>
 |
| <li>
 |
| <em>meet in the middle:</em> combines the two approached above, but involves the development of code to manage the
 |
| new interface as generated by the WSDL and the old API from the existing function.
 |
| </li>
 |
| </ul>
 |
| <p>
 |
| The bottom-up approach as the advantage to quickly expose web service, and also permit to test within a java
 |
| environment the implementation of the service. But this approach leads to have incompatible type definitions and so
 |
| have multiple definitions for the same semantic.
 |
| </p>
 |
| <p>
 |
| There is a common acceptance among software architects to use a top-down or meet in the middle approach, and define the
 |
| common interface within the portType declaration of WSDL. The XML Schema specification defines a broader range of
 |
| constructs for describing message structures than Java. Some of these include choices, derivation by restriction,
 |
| annotation. Therefore, it is better to define your interface using WSDL and XSD, and generate skeletal Java code.
 |
| </p>
 |
| <h3>
 |
| Service Definition
 |
| </h3>
 |
| <p>
 |
| A service interface should generally contain more than one operation. Operations defined as part of a single service
 |
| interface should be semantically related. Business transactions related to the same data as for example a claim are
 |
| mapped to operations within the same interface: ProcessClaim. Having one interface per business function may lead to
 |
| have a huge amount of service interfaces. Service proliferation, in turn, results in service governance problems,
 |
| making it harder to pursue effective code reuse.
 |
| </p>
 |
| <p>
 |
| if for example the data are coming from different physical systems, we could map the access to those different data
 |
| sources with technical interfaces, and aggregate these interfaces into a single business interface.
 |
| </p>
 |
| <p>
 |
| The signature of each operation can support different set of approaches: synchronous/ asynchronous, stateless/stateful,
 |
| header based or carrying payload, use of faults or not.
 |
| </p>
 |
| <p>
 |
| Asynchronous design means that once the client sent its message&nbsp;it does not know if the message was successfully
 |
| delivered or not, and if the service was able to process it. This is a one-way operation. It may be a good
 |
| implementation for a Event Driven Architecture, leveraging an ESB for message reliability and delivery.
 |
| </p>
 |
| <p>
 |
| Synchronous involves request-response operation. The client is blocked until it gets the response or a fault. Faults
 |
| convey error information about failures that occur during the service invocation. Online application should leverage a
 |
| synchronous definition of the service to ensure someone is taking care of the errors.
 |
| </p>
 |
| <p>
 |
| When designing a new service, do not mix synchronous and asynchronous invocation semantics in a single WSDL port type.
 |
| If it is advantageous to support both semantics, define separate interfaces for synchronous and asynchronous
 |
| invocations.
 |
| </p>
 |
| <p>
 |
| An important design consideration on the operation response message. It has to include some business semantic so that
 |
| the client caller can do something in case of failure, like for example asynchronously ping the service for new
 |
| response.
 |
| </p>
 |
| <p>
 |
| Exchanges between services can be stateful or stateless in nature. A stateful, or conversational, exchange between
 |
| services occurs when the service provider retains knowledge of data that has been exchanged between the service
 |
| consumer and the service provider during preceding operation invocations. Stateless interfaces are considered superior
 |
| in the context of building an SOA. A stateless interface can be readily reused by many service consumer applications
 |
| that are free to manage state in the manner best suited to each application.
 |
| </p>
 |
| <p>
 |
| The request messages contain data that will be used by the service to perform the business logic of the operation.
 |
| These messages can also contain data (ins SOAP user-defined headers for example)&nbsp;that are more pertinent to
 |
| system-level processing associated with the transaction. Such data can include service consumer
 |
| identifier,&nbsp;service producer version number (play old - new service), time stamps,...
 |
| </p></mainDescription> |
| </org.eclipse.epf.uma:ContentDescription> |
