diff options
Diffstat (limited to 'site/trunk/site-publish/documentation-2x/sca-java-interfacewsdl.html')
| -rw-r--r-- | site/trunk/site-publish/documentation-2x/sca-java-interfacewsdl.html | 312 |
1 files changed, 312 insertions, 0 deletions
diff --git a/site/trunk/site-publish/documentation-2x/sca-java-interfacewsdl.html b/site/trunk/site-publish/documentation-2x/sca-java-interfacewsdl.html new file mode 100644 index 0000000000..7affdd61d2 --- /dev/null +++ b/site/trunk/site-publish/documentation-2x/sca-java-interfacewsdl.html @@ -0,0 +1,312 @@ + + + + + + +<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" "http://www.w3.org/TR/html4/loose.dtd"> +<HTML> + <HEAD> + <META name="description" content="Apache Tuscany"> + <META name="keywords" content="apache, apache tuscany, tuscany, service, services, fabric, soa, service oriented architecture, sca, service component architecture, das, sdo, csa, ruby, opensource"> + + <LINK type="text/css" rel="stylesheet" href="http://tuscany.apache.org/stylesheets/default.css"> + <LINK rel="SHORTCUT ICON" href="https://cwiki.apache.org/confluence/display/TUSCANYxDOCx2x/$images/favicon.ico"> + <TITLE>SCA Java interface.wsdl : Apache Tuscany</TITLE> + <META http-equiv="Content-Type" content="text/html;charset=UTF-8"></HEAD> + + <STYLE> + .spacetree * ul { + padding-left:0px; + margin-left: 0px; + } + .spacetree * li { + margin-left: 5px; + padding-left:5px; + } + </STYLE> + + <BODY onload="init()"> + <!-- topNav --> + <TABLE border="0" cellpadding="2" cellspacing="0" width="100%"> + <TR class="topBar"> + <TD align="left" valign="middle" class="topBarDiv" align="left" nowrap=""> + <A href="https://cwiki.apache.org/geronimo"> Home</A> > <A href="index.html" title="Apache Tuscany Docs 2.x">Apache Tuscany Docs 2.x</A> > <A href="index.html" title="Index">Index</A> > <A href="sca-java-extensions-guide.html" title="SCA Java Extensions Guide">SCA Java Extensions Guide</A> > <A href="" title="SCA Java interface.wsdl">SCA Java interface.wsdl</A> + </TD> + <TD align="right" valign="middle" nowrap=""> + <FORM name="search" action="http://www.google.com/search" method="get"> + <INPUT type="hidden" name="ie" value="UTF-8"> + <INPUT type="hidden" name="oe" value="UTF-8"> + <INPUT type="hidden" name="domains" value=""> + <INPUT type="hidden" name="sitesearch" value=""> + <INPUT type="text" name="q" maxlength="255" value=""> + <INPUT type="submit" name="btnG" value="Google Search"> + </FORM> + </TD> + </TR> + </TABLE> + + + <TABLE border="0" cellpadding="2" cellspacing="0" width="100%"> + <TR class="topBar"> + <TD align="left" valign="middle" class="topBarDiv" nowrap="true" width="100%"> + <A href="index.html" title="Apache Tuscany Docs 2.x">Apache Tuscany Docs 2.x</A> > <A href="index.html" title="Index">Index</A> > <A href="sca-java-extensions-guide.html" title="SCA Java Extensions Guide">SCA Java Extensions Guide</A> > <A href="" title="SCA Java interface.wsdl">SCA Java interface.wsdl</A> + </TD> + + <TD align="right" valign="middle" class="topBarDiv" align="left" nowrap="true"> + <A href="http://tuscany.apache.org/">Tuscany Home</A> | <A href="http://mail-archives.apache.org/mod_mbox/tuscany-user">User List</A> | <A href="http://mail-archives.apache.org/mod_mbox/tuscany-dev">Dev List</A> | <A href="http://issues.apache.org/jira/browse/Tuscany">Issue Tracker</A> + </TD> + </TR> + </TABLE> + + <TABLE border="0" cellpadding="0" width="100%" bgcolor="#FFFFFF"> + <TR> + <TD valign="top" align="left" width="22%" bgcolor="#F9F9F9" class="noprint"> + <DIV class="tabletitle">Table of Contents</DIV> + <DIV class="spacetree"> + + + </DIV> + </TD> + <TD align="left" valign="top" width="78%"> + <!-- pageContent --> + <DIV id="PageContent"> + <DIV class="pageheader" style="padding: 6px 0px 0px 0px;"> + <!-- We'll enable this once we figure out how to access (and save) the logo resource --> + <!--img src="http://geronimo.apache.org/images/confluence_logo.gif" style="float: left; margin: 4px 4px 4px 10px;" border="0"--> + <DIV style="margin: 0px 10px 0px 10px" class="smalltext">Apache Tuscany Docs 2.x</DIV> + <DIV style="margin: 0px 10px 8px 10px" class="pagetitle">SCA Java interface.wsdl</DIV> + + <DIV class="greynavbar" align="right" style="padding: 2px 10px; margin: 0px;"> +<!-- --> + <A href="https://cwiki.apache.org/confluence/pages/editpage.action?pageId=5964972"> + <IMG src="http://geronimo.apache.org/images/icons/notep_16.gif" height="16" width="16" border="0" align="absmiddle" title="Edit Page"></A> + <A href="https://cwiki.apache.org/confluence/pages/editpage.action?pageId=5964972">Edit Page</A> + + <A href="https://cwiki.apache.org/confluence/pages/listpages.action?key=TUSCANYxDOCx2x"> + <IMG src="http://geronimo.apache.org/images/icons/browse_space.gif" height="16" width="16" border="0" align="absmiddle" title="Browse Space"></A> + <A href="https://cwiki.apache.org/confluence/pages/listpages.action?key=TUSCANYxDOCx2x">Browse Space</A> + + <A href="https://cwiki.apache.org/confluence/pages/createpage.action?spaceKey=TUSCANYxDOCx2x&fromPageId=5964972"> + <IMG src="http://geronimo.apache.org/images/icons/add_page_16.gif" height="16" width="16" border="0" align="absmiddle" title="Add Page"></A> + <A href="https://cwiki.apache.org/confluence/pages/createpage.action?spaceKey=TUSCANYxDOCx2x&fromPageId=5964972">Add Page</A> + + <A href="https://cwiki.apache.org/confluence/pages/createblogpost.action?spaceKey=TUSCANYxDOCx2x&fromPageId=5964972"> + <IMG src="http://geronimo.apache.org/images/icons/add_blogentry_16.gif" height="16" width="16" border="0" align="absmiddle" title="Add News"></A> + <A href="https://cwiki.apache.org/confluence/pages/createblogpost.action?spaceKey=TUSCANYxDOCx2x&fromPageId=5964972">Add News</A> +<!-- --> + </DIV> + </DIV> + + <DIV class="pagecontent"> + <DIV class="wiki-content"> + +<H3><A name="SCAJavainterface.wsdl-%3Cinterface.wsdl%3E"></A><interface.wsdl></H3> + +<P>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 <B>wsimport</B>. The <B>wsimport</B> tool generates a skeleton of the service interface, along with all associated request and response classes, and any complex data types passed on the interface. The user can augment the skeleton by putting implementation code in the approproate spot.</P> + +<P>The following snippet shows how the WSDL interface and the Java implementation are used in an SCA composite file and publicised as a component.</P> +<DIV class="code panel" style="border-width: 1px;"><DIV class="codeContent panelContent"> +<PRE class="code-java"> + <component name=<SPAN class="code-quote">"OrderServiceComponent"</SPAN>> + <implementation.java class=<SPAN class="code-quote">"org.example.orderservice.OrderServiceImpl"</SPAN> /> + <service name=<SPAN class="code-quote">"OrderService"</SPAN>> + <<SPAN class="code-keyword">interface</SPAN>.wsdl <SPAN class="code-keyword">interface</SPAN>=<SPAN class="code-quote">"http:<SPAN class="code-comment">//www.example.org/OrderService/#wsdl.<SPAN class="code-keyword">interface</SPAN>(OrderService)"</SPAN> /> +</SPAN> <binding.ws uri=<SPAN class="code-quote">"http:<SPAN class="code-comment">//localhost:8085/OrderService"</SPAN>/> +</SPAN> </service> + </component> +</PRE> +</DIV></DIV> + +<H3><A name="SCAJavainterface.wsdl-Examples"></A>Examples</H3> + +<P>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 <A href="http://localhost:8085/OrderService" class="external-link" rel="nofollow">http://localhost:8085/OrderService</A>. (Note that this full sample is available in Tuscany 1.x branch under the samples/holder-ws-service sample).</P> + +<DIV class="code panel" style="border-width: 1px;"><DIV class="codeContent panelContent"> +<PRE class="code-java"> +<composite xmlns=<SPAN class="code-quote">"http:<SPAN class="code-comment">//www.osoa.org/xmlns/sca/1.0"</SPAN> +</SPAN> targetNamespace=<SPAN class="code-quote">"http:<SPAN class="code-comment">//orderservice"</SPAN> +</SPAN> xmlns:hw=<SPAN class="code-quote">"http:<SPAN class="code-comment">//orderservice"</SPAN> +</SPAN> name=<SPAN class="code-quote">"orderws"</SPAN>> + + <component name=<SPAN class="code-quote">"OrderServiceComponent"</SPAN>> + <implementation.java class=<SPAN class="code-quote">"org.example.orderservice.OrderServiceImpl"</SPAN> /> + <service name=<SPAN class="code-quote">"OrderService"</SPAN>> + <<SPAN class="code-keyword">interface</SPAN>.wsdl <SPAN class="code-keyword">interface</SPAN>=<SPAN class="code-quote">"http:<SPAN class="code-comment">//www.example.org/OrderService/#wsdl.<SPAN class="code-keyword">interface</SPAN>(OrderService)"</SPAN> /> +</SPAN> <binding.ws uri=<SPAN class="code-quote">"http:<SPAN class="code-comment">//localhost:8085/OrderService"</SPAN>/> +</SPAN> </service> + </component> + +</composite> +</PRE> +</DIV></DIV> + +<P>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:</P> +<DIV class="code panel" style="border-width: 1px;"><DIV class="codeContent panelContent"> +<PRE class="code-java"> + <wsdl:portType name=<SPAN class="code-quote">"OrderService"</SPAN>> + <wsdl:operation name=<SPAN class="code-quote">"reviewOrder"</SPAN>> + <wsdl:input message=<SPAN class="code-quote">"tns:reviewOrderRequest"</SPAN>/> + <wsdl:output message=<SPAN class="code-quote">"tns:reviewOrderResponse"</SPAN>/> + </wsdl:operation> + </wsdl:portType> + <wsdl:message name=<SPAN class="code-quote">"reviewOrderRequest"</SPAN>> + <wsdl:part element=<SPAN class="code-quote">"tns:reviewOrder"</SPAN> name=<SPAN class="code-quote">"myParameters"</SPAN>/> + </wsdl:message> + <wsdl:message name=<SPAN class="code-quote">"reviewOrderResponse"</SPAN>> + <wsdl:part element=<SPAN class="code-quote">"tns:reviewOrderResponse"</SPAN> name=<SPAN class="code-quote">"myResult"</SPAN>/> + </wsdl:message> + <wsdl:types> + <xsd:schema targetNamespace=<SPAN class="code-quote">"http:<SPAN class="code-comment">//www.example.org/OrderService/"</SPAN>> +</SPAN> <xsd:complexType name=<SPAN class="code-quote">"order"</SPAN>> + <xsd:sequence> + <xsd:element name=<SPAN class="code-quote">"customerId"</SPAN> type=<SPAN class="code-quote">"xsd:string"</SPAN> minOccurs=<SPAN class="code-quote">"0"</SPAN> /> + <xsd:element name=<SPAN class="code-quote">"status"</SPAN> type=<SPAN class="code-quote">"tns:status"</SPAN> minOccurs=<SPAN class="code-quote">"0"</SPAN> /> + <xsd:element name=<SPAN class="code-quote">"total"</SPAN> type=<SPAN class="code-quote">"xsd:<SPAN class="code-object">double</SPAN>"</SPAN> /> + <xsd:element name=<SPAN class="code-quote">"orderId"</SPAN> type=<SPAN class="code-quote">"xsd:<SPAN class="code-object">int</SPAN>"</SPAN> /> + </xsd:sequence> + </xsd:complexType> + + <xsd:simpleType name=<SPAN class="code-quote">"status"</SPAN>> + <xsd:restriction base=<SPAN class="code-quote">"xsd:string"</SPAN>> + <xsd:enumeration value=<SPAN class="code-quote">"Created"</SPAN> /> + <xsd:enumeration value=<SPAN class="code-quote">"Submitted"</SPAN> /> + <xsd:enumeration value=<SPAN class="code-quote">"Approved"</SPAN> /> + <xsd:enumeration value=<SPAN class="code-quote">"Rejected"</SPAN> /> + </xsd:restriction> + </xsd:simpleType> + + <xsd:element name=<SPAN class="code-quote">"reviewOrder"</SPAN>> + <xsd:complexType> + <xsd:sequence> + <xsd:element name=<SPAN class="code-quote">"myData"</SPAN> type=<SPAN class="code-quote">"tns:order"</SPAN> + minOccurs=<SPAN class="code-quote">"1"</SPAN> maxOccurs=<SPAN class="code-quote">"1"</SPAN> /> + </xsd:sequence> + </xsd:complexType> + </xsd:element> + <xsd:element name=<SPAN class="code-quote">"reviewOrderResponse"</SPAN>> + <xsd:complexType> + <xsd:sequence> + <xsd:element name=<SPAN class="code-quote">"myData"</SPAN> type=<SPAN class="code-quote">"tns:order"</SPAN> + minOccurs=<SPAN class="code-quote">"1"</SPAN> maxOccurs=<SPAN class="code-quote">"1"</SPAN> /> + </xsd:sequence> + </xsd:complexType> + </xsd:element> + + </xsd:schema> + </wsdl:types> +</PRE> +</DIV></DIV> + +<P>The Java implementation for this web service can be generated with the Java SDK tool <B>wsimport</B>. Full documentation is in the Java SDK JavaDocs, but basically one specifies the source WSDL and the output directory for generated files.</P> +<DIV class="code panel" style="border-width: 1px;"><DIV class="codeContent panelContent"> +<PRE class="code-java"> + wsimport -d orderservice -keep orderservice.wsdl +</PRE> +</DIV></DIV> + +<P>The generated implementation files can be augmented with code that operates on provided business objects.</P> + +<H3><A name="SCAJavainterface.wsdl-WebServicesHolderPattern"></A>Web Services Holder Pattern</H3> + +<P>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<BR> +on the same interface.</P> + +<P>The advantages of the INOUT mode are:</P> +<UL> + <LI>supports a well known pattern of parameter pass by reference. Normally SCA parameters are always passed by value.</LI> + <LI>saves instantiation and initialization for large or complex objects.</LI> + <LI>simplifies the signature of business interfaces</LI> + <LI>saves the user the cost of boxing and returning multiple return objects.</LI> +</UL> + + +<P>The Holder pattern is created by the Java SDK wsimport tool whenever data type is both input and output to a given operation></P> +<DIV class="code panel" style="border-width: 1px;"><DIV class="codeContent panelContent"> +<PRE class="code-java"> + <xsd:element name=<SPAN class="code-quote">"myOperation"</SPAN>> + <xsd:complexType> + <xsd:sequence> + <xsd:element name=<SPAN class="code-quote">"myData"</SPAN> type=<SPAN class="code-quote">"tns:myDataType"</SPAN> minOccurs=<SPAN class="code-quote">"1"</SPAN> maxOccurs=<SPAN class="code-quote">"1"</SPAN>/> + </xsd:sequence> + </xsd:complexType> + </xsd:element> + <xsd:element name=<SPAN class="code-quote">"myOperationResponse"</SPAN>> + <xsd:complexType> + <xsd:sequence> + <xsd:element name=<SPAN class="code-quote">"myData"</SPAN> type=<SPAN class="code-quote">"tns:myDataType"</SPAN> minOccurs=<SPAN class="code-quote">"1"</SPAN> maxOccurs=<SPAN class="code-quote">"1"</SPAN>/> + </xsd:sequence> + </xsd:complexType> + </xsd:element> +</PRE> +</DIV></DIV> + +<P>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.</P> +<DIV class="code panel" style="border-width: 1px;"><DIV class="codeContent panelContent"> +<PRE class="code-java"> + @WebMethod(action = <SPAN class="code-quote">"http:<SPAN class="code-comment">//www.example.org/OrderService/reviewOrder"</SPAN>) +</SPAN> @RequestWrapper(localName = <SPAN class="code-quote">"reviewOrder"</SPAN>, targetNamespace = <SPAN class="code-quote">"http:<SPAN class="code-comment">//www.example.org/OrderService/"</SPAN>, className = <SPAN class="code-quote">"org.example.orderservice.ReviewOrder"</SPAN>) +</SPAN> @ResponseWrapper(localName = <SPAN class="code-quote">"reviewOrderResponse"</SPAN>, targetNamespace = <SPAN class="code-quote">"http:<SPAN class="code-comment">//www.example.org/OrderService/"</SPAN>, className = <SPAN class="code-quote">"org.example.orderservice.ReviewOrderResponse"</SPAN>) +</SPAN> <SPAN class="code-keyword">public</SPAN> void reviewOrder( + @WebParam(name = <SPAN class="code-quote">"myData"</SPAN>, targetNamespace = "", mode = WebParam.Mode.INOUT) + javax.xml.ws.Holder<Order> myData); +</PRE> +</DIV></DIV> + +<P>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 :</P> +<DIV class="code panel" style="border-width: 1px;"><DIV class="codeContent panelContent"> +<PRE class="code-java"> + @WebMethod(action = <SPAN class="code-quote">"http:<SPAN class="code-comment">//www.example.org/OrderService/reviewOrder"</SPAN>) +</SPAN> @RequestWrapper(localName = <SPAN class="code-quote">"reviewOrder"</SPAN>, targetNamespace = <SPAN class="code-quote">"http:<SPAN class="code-comment">//www.example.org/OrderService/"</SPAN>, className = <SPAN class="code-quote">"org.example.orderservice.ReviewOrder"</SPAN>) +</SPAN> @ResponseWrapper(localName = <SPAN class="code-quote">"reviewOrderResponse"</SPAN>, targetNamespace = <SPAN class="code-quote">"http:<SPAN class="code-comment">//www.example.org/OrderService/"</SPAN>, className = <SPAN class="code-quote">"org.example.orderservice.ReviewOrderResponse"</SPAN>) +</SPAN> <SPAN class="code-keyword">public</SPAN> void reviewOrder( + @WebParam(name = <SPAN class="code-quote">"myData"</SPAN>, targetNamespace = "", mode = WebParam.Mode.INOUT) + Holder<Order> myData) { + Order order = myData.value; + <SPAN class="code-object">double</SPAN> total = order.getTotal(); + <SPAN class="code-keyword">if</SPAN> ( total < 100.0 ) { + order.setStatus( Status.APPROVED ); + } + } +</PRE> +</DIV></DIV> + +<P>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.</P> + </DIV> + + </DIV> + </DIV> + </TD> + </TR> + </TABLE> + + <!-- footer --> + <TABLE border="0" cellpadding="2" cellspacing="0" width="100%"> + <TR> + <TD align="left" valign="middle" class="footer"> + + <IMG src="http://static.delicious.com/img/delicious.small.gif" height="10" width="10" alt="Delicious"> + <A href="http://delicious.com/save" onclick="window.open('http://delicious.com/save?v=5&noui&jump=close&url='+encodeURIComponent(location.href)+'&title='+encodeURIComponent(document.title),'delicious','toolbar=no,width=550,height=550'); return false;">Bookmark this on Delicious</A> + + <IMG src="http://digg.com/img/badges/16x16-digg-guy.gif" width="16" height="16" alt="Digg!"> + <A href="" onclick="window.open('http://digg.com/submit?url='+encodeURIComponent(location.href)+'&title='+encodeURIComponent(document.title)+'&topic=programming');">Digg this</A> + <!-- Slicker, but no text + <script type="text/javascript"> + digg_skin = 'icon'; + digg_window = 'new'; + digg_title = 'Apache Geronimo v2.2 Documentation : SCA Java interface.wsdl'; + digg_topic = 'programming'; + </script> + <script src="http://digg.com/tools/diggthis.js" type="text/javascript"></script> + --> + + </TD> + <TD align="right" valign="middle" class="footer"> + <A href="http://cwiki.apache.org/GMOxPMGT/geronimo-privacy-policy.html">Privacy Policy</A> - + Copyright © 2003-2010, The Apache Software Foundation, Licensed under <A href="http://www.apache.org/licenses/LICENSE-2.0">ASL 2.0.</A> + </TD> + </TR> + </TABLE> + + </BODY> +</HTML>
\ No newline at end of file |