SCA Java interface.wsdl (TUSCANY) created by Dan Becker
http://cwiki.apache.org/confluence/display/TUSCANY/SCA+Java+interface.wsdl
Content:
---------------------------------------------------------------------
{section:border=false}
{column:width=15%}
{include: SCA Java Subproject Menu}
{include: Java SCA Menu New}
{column}
{column:width=85%}
h3. <interface.wsdl>
The Tuscany Java SCA runtime supports interfaces that are described by Web
Services Description Lanuage (WSDL) files. The files contain a description of
the service interface, services, references, method requests and responses, and
the data types. The implementation of this WSDL interface can be generated with
the Java SDK tool wsimport. The wsimport generates a skeleton of the service
interface, along with all associated request and respoinse classes, and any
complex data types passed on the interface. The user can augment the skeleton
by putting implementation code in the approproate spot.
The following snippet shows how the WSDL interface and the Java implementation
are used in an SCA composite file and publicised as a component.
{code}
<component name="OrderServiceComponent">
<implementation.java class="org.example.orderservice.OrderServiceImpl"
/>
<service name="OrderService">
<interface.wsdl
interface="http://www.example.org/OrderService/#wsdl.interface(OrderService)" />
<binding.ws uri="http://localhost:8085/OrderService"/>
</service>
</component>
{code}
h3. Examples
This example shows a component with its interface described via WSDL. The web
service binding defaults are used so the endpoint of the Web service will be
http://localhost:8085/OrderService. (Note that this full sample is available in
Tuscany 1.x branch under the samples/holder-ws-service sample).
{code}
<composite xmlns="http://www.osoa.org/xmlns/sca/1.0";
targetNamespace="http://orderservice";
xmlns:hw="http://orderservice";
name="orderws">
<component name="OrderServiceComponent">
<implementation.java class="org.example.orderservice.OrderServiceImpl"
/>
<service name="OrderService">
<interface.wsdl
interface="http://www.example.org/OrderService/#wsdl.interface(OrderService)" />
<binding.ws uri="http://localhost:8085/OrderService"/>
</service>
</component>
</composite>
{code}
WSDL files can be generated with many tools and development environment
plugins. This snippet shows a portion of the WSDL file that describes the
business service data types and the assoicated method calls and responses:
{code}
<wsdl:portType name="OrderService">
<wsdl:operation name="reviewOrder">
<wsdl:input message="tns:reviewOrderRequest"/>
<wsdl:output message="tns:reviewOrderResponse"/>
</wsdl:operation>
</wsdl:portType>
<wsdl:message name="reviewOrderRequest">
<wsdl:part element="tns:reviewOrder" name="myParameters"/>
</wsdl:message>
<wsdl:message name="reviewOrderResponse">
<wsdl:part element="tns:reviewOrderResponse" name="myResult"/>
</wsdl:message>
<wsdl:types>
<xsd:schema targetNamespace="http://www.example.org/OrderService/";>
<xsd:complexType name="order">
<xsd:sequence>
<xsd:element name="customerId" type="xsd:string"
minOccurs="0" />
<xsd:element name="status" type="tns:status" minOccurs="0"
/>
<xsd:element name="total" type="xsd:double" />
<xsd:element name="orderId" type="xsd:int" />
</xsd:sequence>
</xsd:complexType>
<xsd:simpleType name="status">
<xsd:restriction base="xsd:string">
<xsd:enumeration value="Created" />
<xsd:enumeration value="Submitted" />
<xsd:enumeration value="Approved" />
<xsd:enumeration value="Rejected" />
</xsd:restriction>
</xsd:simpleType>
<xsd:element name="reviewOrder">
<xsd:complexType>
<xsd:sequence>
<xsd:element name="myData" type="tns:order"
minOccurs="1" maxOccurs="1" />
</xsd:sequence>
</xsd:complexType>
</xsd:element>
<xsd:element name="reviewOrderResponse">
<xsd:complexType>
<xsd:sequence>
<xsd:element name="myData" type="tns:order"
minOccurs="1" maxOccurs="1" />
</xsd:sequence>
</xsd:complexType>
</xsd:element>
</xsd:schema>
</wsdl:types>
{code}
The Java implementation for this web service can be generated with the Java SDK
tool wsimport. Full documentation is in the Java SDK JavaDocs, but basically
one specifies the source WSDL and the output directory for generated files.
{code}
wsimport -d orderservice -keep orderservice.wsdl
{code}
The generated implementation files can be augmented with code that operates on
provided business objects.
h3. Web Services Holder Pattern
A pattern known as the Web Services Holder Pattern is supported by Tuscany in
the 1.5 and later releases. WSDL files support a parameter mode known as INOUT.
The INOUT mode is used for service interface parameters that are passed into a
business interface and returned
on the same interface.
The advantages of the INOUT mode are:
* supports a well known pattern of parameter pass by reference. Normally SCA
parameters are always passed by value.
* saves instantiation and initialization for large or complex objects.
* simplifies the signature of business interfaces
* saves the user the cost of boxing and returning multiple return objects.
The Holder pattern is created by the Java SDK wsimport tool whenever data type
is both input and output to a given operation>
{code}
<xsd:element name="myOperation">
<xsd:complexType>
<xsd:sequence>
<xsd:element name="myData" type="tns:myDataType" minOccurs="1"
maxOccurs="1"/>
</xsd:sequence>
</xsd:complexType>
</xsd:element>
<xsd:element name="myOperationResponse">
<xsd:complexType>
<xsd:sequence>
<xsd:element name="myData" type="tns:myDataType" minOccurs="1"
maxOccurs="1"/>
</xsd:sequence>
</xsd:complexType>
</xsd:element>
{code}
The generated implemenation code contains annotations that mark the parameter
data as an input output parameter. Also notice that the business object Order
is passed in as a data type javax.xml.ws.Holder<Order>. This Holder class
allows the input object to be returned as an output object, i.e. pass by
reference.
{code}
@WebMethod(action = "http://www.example.org/OrderService/reviewOrder";)
@RequestWrapper(localName = "reviewOrder", targetNamespace =
"http://www.example.org/OrderService/";, className =
"org.example.orderservice.ReviewOrder")
@ResponseWrapper(localName = "reviewOrderResponse", targetNamespace =
"http://www.example.org/OrderService/";, className =
"org.example.orderservice.ReviewOrderResponse")
public void reviewOrder(
@WebParam(name = "myData", targetNamespace = "", mode =
WebParam.Mode.INOUT)
javax.xml.ws.Holder<Order> myData);
{code}
The Java implemenation code can access the wrapped Holder object, perform
updates on the object, and leave it in place to return the object as shown here
with the Java object Order :
{code}
@WebMethod(action = "http://www.example.org/OrderService/reviewOrder";)
@RequestWrapper(localName = "reviewOrder", targetNamespace =
"http://www.example.org/OrderService/";, className =
"org.example.orderservice.ReviewOrder")
@ResponseWrapper(localName = "reviewOrderResponse", targetNamespace =
"http://www.example.org/OrderService/";, className =
"org.example.orderservice.ReviewOrderResponse")
public void reviewOrder(
@WebParam(name = "myData", targetNamespace = "", mode =
WebParam.Mode.INOUT)
Holder<Order> myData) {
Order order = myData.value;
double total = order.getTotal();
if ( total < 100.0 ) {
order.setStatus( Status.APPROVED );
}
}
{code}
Tuscany, as of version 1.5 supports this input/output Holder pattern. At this
point there is a limitation of only one in/out parameter, and this is only
supported on methods with void return types.
{column}
{section}
---------------------------------------------------------------------
CONFLUENCE INFORMATION
This message is automatically generated by Confluence
Unsubscribe or edit your notifications preferences
http://cwiki.apache.org/confluence/users/viewnotifications.action
If you think it was sent incorrectly contact one of the administrators
http://cwiki.apache.org/confluence/administrators.action
If you want more information on Confluence, or have a bug to report see
http://www.atlassian.com/software/confluence
