<?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.6/uma.ecore" xmlns:epf="http://www.eclipse.org/epf" epf:version="1.5.1" xmlns:rmc="http://www.ibm.com/rmc" rmc:version="7.5.1" xmi:id="-z4b7YSb0hoz7fKqCWsc8uQ" name="new_guideline,_YRiuIItDEd2gksNyFVJN4g" guid="-z4b7YSb0hoz7fKqCWsc8uQ" changeDate="2008-09-25T01:49:34.000-0700" version="7.5.1">
  <mainDescription>&lt;p>
    W3C defines web service as: &quot;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.&quot;
&lt;/p>
&lt;p>
    In software architecture literature It is agreed that the XML syntax to define the web service is WSDL.
&lt;/p>
&lt;h3>
    Three Approaches
&lt;/h3>
&lt;p>
    From a methodology point of view there are three possible approaches to design a web service:
&lt;/p>
&lt;ul>
    &lt;li>
        &lt;em>top-down&lt;/em>: The architect&amp;nbsp;first defines the Web service interface using WSDL and XML Schema (XSD)
        constructs, then generates implementation code for the service.
    &lt;/li>
    &lt;li>
        &lt;em>bottom-up&lt;/em>: from the developer environment like eclipse, we can create a web service and wsdl from an
        existing java code. The JAX-WS specification&amp;nbsp;defines annotations to put in the code to&amp;nbsp;define the
        service.&amp;nbsp;
    &lt;/li>
    &lt;li>
        &lt;em>meet in the middle:&lt;/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.
    &lt;/li>
&lt;/ul>
&lt;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.
&lt;/p>
&lt;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.
&lt;/p>
&lt;h3>
    Service Definition
&lt;/h3>
&lt;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.
&lt;/p>
&lt;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.
&lt;/p>
&lt;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.
&lt;/p>
&lt;p>
    Asynchronous design means that once the client sent its message&amp;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.
&lt;/p>
&lt;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.
&lt;/p>
&lt;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.
&lt;/p>
&lt;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.
&lt;/p>
&lt;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.
&lt;/p>
&lt;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)&amp;nbsp;that are more pertinent to
    system-level processing associated with the transaction. Such data can include service consumer
    identifier,&amp;nbsp;service producer version number (play old - new service), time stamps,...
&lt;/p></mainDescription>
</org.eclipse.epf.uma:ContentDescription>
