<html><head> <meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1"> <title>JAX-WS Release Documentation</title><link rel="stylesheet" href="style/documentation.css" type="text/css"><meta name="generator" content="DocBook XSL-NS Stylesheets V1.75.2"><script xmlns:fo="http://www.w3.org/1999/XSL/Format" type="text/javascript"> var _gaq = _gaq || []; _gaq.push(['_setAccount', 'UA-2105126-1']); _gaq.push(['_trackPageview']); (function() { var ga = document.createElement('script'); ga.type = 'text/javascript'; ga.async = true; ga.src = ('https:' == document.location.protocol ? 'https://ssl' : 'http://www') + '.google-analytics.com/ga.js'; var s = document.getElementsByTagName('script')[0]; s.parentNode.insertBefore(ga, s); })(); </script></head><body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"><small xmlns:fo="http://www.w3.org/1999/XSL/Format" class="small">Links: <a href="index.html">Table of Contents</a> | <a href="release-documentation.html">Single HTML</a> | <a href="release-documentation.pdf">Single PDF</a></small><div lang="en" class="book" title="JAX-WS Release Documentation" id="user-guide"><div class="titlepage"><div><div><h1 class="title">JAX-WS Release Documentation</h1></div></div><hr></div><div class="toc"><p><b>Table of Contents</b></p><dl><dt><span class="chapter"><a href="#jax-ws-ri-overview">Overview</a></span></dt><dd><dl><dt><span class="section"><a href="#section-159360148062263">1. Documentation</a></span></dt><dt><span class="section"><a href="#section-0073999762824">2. Software Licenses</a></span></dt><dt><span class="section"><a href="#section-302002852812141">3. Useful Links</a></span></dt><dd><dl><dt><span class="section"><a href="#other-links">3.1. Other links</a></span></dt></dl></dd></dl></dd><dt><span class="chapter"><a href="#jax-ws-ri-release-notes">Release Notes</a></span></dt><dd><dl><dt><span class="section"><a href="#overview">1. Overview</a></span></dt><dt><span class="section"><a href="#features-in-this-release">2. Features in this release</a></span></dt><dt><span class="section"><a href="#online-documentation">3. Online Documentation</a></span></dt><dt><span class="section"><a href="#required-software">4. Required Software</a></span></dt><dt><span class="section"><a href="#installation-instructions">5. Installation Instructions</a></span></dt><dt><span class="section"><a href="#running-on-top-of-jdk-6">6. Running on top of JDK 6</a></span></dt><dt><span class="section"><a href="#jar-dependency">7. Jar dependency</a></span></dt><dt><span class="section"><a href="#current-limitations">8. Current Limitations</a></span></dt><dt><span class="section"><a href="#bugs-fixed-in-this-release">9. Bugs Fixed in this release</a></span></dt><dt><span class="section"><a href="#known-bugs-issues">10. Known Bugs/Issues</a></span></dt><dt><span class="section"><a href="#for-more-information">11. For More Information</a></span></dt><dt><span class="section"><a href="#jax-ws-ri-changelog">12. Changelog</a></span></dt><dd><dl><dt><span class="section"><a href="#changes-221-223">12.1. Changes from JAX-WS RI 2.2.1 to JAX-WS RI 2.2.3 </a></span></dt><dt><span class="section"><a href="#changes-22-221">12.2. Changes from JAX-WS RI 2.2 to JAX-WS RI 2.2.1 </a></span></dt><dt><span class="section"><a href="#changes-217-22">12.3. Changes from JAX-WS RI 2.1.7 to JAX-WS RI 2.2 </a></span></dt><dt><span class="section"><a href="#changes-216-217">12.4. Changes from JAX-WS RI 2.1.6 to JAX-WS RI 2.1.7 </a></span></dt><dt><span class="section"><a href="#changes-215-216">12.5. Changes from JAX-WS RI 2.1.5 to JAX-WS RI 2.1.6 </a></span></dt><dt><span class="section"><a href="#changes-214-215">12.6. Changes from JAX-WS RI 2.1.4 to JAX-WS RI 2.1.5 </a></span></dt><dt><span class="section"><a href="#changes-213-214">12.7. Changes from JAX-WS RI 2.1.3 to JAX-WS RI 2.1.4</a></span></dt><dt><span class="section"><a href="#changes-211-213">12.8. Changes from JAX-WS RI 2.1.2 to JAX-WS RI 2.1.3</a></span></dt><dt><span class="section"><a href="#changes-211-212">12.9. Changes from JAX-WS RI 2.1.1 to JAX-WS RI 2.1.2</a></span></dt><dt><span class="section"><a href="#changes-20-21">12.10. Changes from JAX-WS 2.0 RI to JAX-WS RI 2.1.1</a></span></dt></dl></dd></dl></dd><dt><span class="chapter"><a href="#users-guide">Users Guide</a></span></dt><dd><dl><dt><span class="section"><a href="#users-guide-overview">1. Overview</a></span></dt><dd><dl><dt><span class="section"><a href="#introduction">1.1. Introduction</a></span></dt><dt><span class="section"><a href="#features">1.2. Features</a></span></dt><dt><span class="section"><a href="#programming-model">1.3. Programming Model</a></span></dt><dt><span class="section"><a href="#useful-information">1.4. Useful Information</a></span></dt></dl></dd><dt><span class="section"><a href="#users-guide-provider">2. Provider</a></span></dt><dd><dl><dt><span class="section"><a href="#section-3091238697838234">2.1. <code class="literal">Provider<Source></code> and <code class="literal">PAYLOAD</code></a></span></dt><dt><span class="section"><a href="#section-8519606736474974">2.2. <code class="literal">Provider<SOAPMessage></code> and <code class="literal">MESSAGE</code></a></span></dt><dt><span class="section"><a href="#section-7319353703410434">2.3. <code class="literal">Provider<Source></code> and <code class="literal">MESSAGE</code></a></span></dt><dt><span class="section"><a href="#section-674124516240791">2.4. WSDL Customization</a></span></dt><dt><span class="section"><a href="#section-648626808421419">2.5. The <code class="literal">sun-jaxws.xml</code> file</a></span></dt><dt><span class="section"><a href="#section-343591403757231">2.6. Provider and Binding</a></span></dt><dt><span class="section"><a href="#section-330867941262645">2.7. RESTful Provider endpoints</a></span></dt><dt><span class="section"><a href="#section-017933327977469">2.8. Provider and Handlers</a></span></dt></dl></dd><dt><span class="section"><a href="#users-guide-asyncprovider">3. AsyncProvider</a></span></dt><dd><dl><dt><span class="section"><a href="#section-091974998856598">3.1. <code class="literal">AsyncProvider</code> Example</a></span></dt><dt><span class="section"><a href="#section-930633228695613">3.2. <code class="literal">AsyncProvider</code> sample</a></span></dt><dt><span class="section"><a href="#section-5233554712491355">3.3. <code class="literal">AsyncService</code> sample</a></span></dt></dl></dd><dt><span class="section"><a href="#users-guide-dispatch">4. Dispatch</a></span></dt><dd><dl><dt><span class="section"><a href="#section-71379735580733">4.1. Programming Model</a></span></dt><dt><span class="section"><a href="#section-21282255346754875">4.2. Dispatch and Asynchronous Invocations</a></span></dt></dl></dd><dt><span class="section"><a href="#users-guide-asynchronous-client">5. Asynchronous Client</a></span></dt><dd><dl><dt><span class="section"><a href="#section-346120708971664">5.1. Asynchronous Invocation Using Static Stub</a></span></dt><dt><span class="section"><a href="#section-85273158180115">5.2. Asynchronous Invocation Using Dispatch</a></span></dt></dl></dd><dt><span class="section"><a href="#users-guide-handler">6. Handler</a></span></dt><dd><dl><dt><span class="section"><a href="#section-524340464580105">6.1. Handler Types</a></span></dt><dt><span class="section"><a href="#section-276528078695232">6.2. MessageContext</a></span></dt><dt><span class="section"><a href="#section-165423693536683">6.3. Handler Chain Configuration</a></span></dt><dt><span class="section"><a href="#section-8594509924044">6.4. Handler Samples</a></span></dt></dl></dd><dt><span class="section"><a href="#users-guide-mtom-and-swaref">7. MTOM and Swaref</a></span></dt><dd><dl><dt><span class="section"><a href="#mtom-and-xop">7.1. MTOM and XOP</a></span></dt><dt><span class="section"><a href="#mtom-in-jaxws-2-0">7.2. MTOM in JAX-WS 2.0</a></span></dt><dt><span class="section"><a href="#swaref">7.3. swaRef</a></span></dt></dl></dd><dt><span class="section"><a href="#users-guide-soap-1-2">8. SOAP 1.2</a></span></dt><dd><dl><dt><span class="section"><a href="#section-94073181229507">8.1. Introduction</a></span></dt><dt><span class="section"><a href="#section-627071591090577">8.2. SOAP 1.2 Endpoint</a></span></dt><dt><span class="section"><a href="#section-696486497021005">8.3. Client</a></span></dt><dt><span class="section"><a href="#section-7037754311590527">8.4. Samples</a></span></dt></dl></dd><dt><span class="section"><a href="#users-guide-wsdl-customization">9. WSDL Customization</a></span></dt><dd><dl><dt><span class="section"><a href="#declaring-customizations">9.1. Declaring Customizations</a></span></dt><dt><span class="section"><a href="#standard-customizations">9.2. Standard Customizations</a></span></dt></dl></dd><dt><span class="section"><a href="#users-guide-annotations">10. Annotations</a></span></dt><dd><dl><dt><span class="section"><a href="#section-031540603185018">10.1. Overview</a></span></dt><dt><span class="section"><a href="#jsr-181">10.2. JSR 181 (Web Services Metadata) Annotations</a></span></dt><dt><span class="section"><a href="#jsr-224-jax-ws-annotations-outline">10.3. JSR 224 (JAX-WS) Annotations</a></span></dt><dt><span class="section"><a href="#jsr-222-jaxb-annotations-outline">10.4. JSR 222 (JAXB) Annotations</a></span></dt><dt><span class="section"><a href="#jsr-250-common-annotations">10.5. JSR 250 (Common Annotations) Annotations</a></span></dt></dl></dd><dt><span class="section"><a href="#users-guide-why-ws-addressing">11. Why WS-Addressing?</a></span></dt><dd><dl><dt><span class="section"><a href="#what-is-ws-addressing">11.1. What is WS-Addressing?</a></span></dt><dt><span class="section"><a href="#ws-addressing-versions">11.2. WS-Addressing Versions</a></span></dt></dl></dd><dt><span class="section"><a href="#users-guide-ws-addressing">12. WS-Addressing</a></span></dt><dd><dl><dt><span class="section"><a href="#ws-addressing-in">12.1. WS-Addressing in JAX-WS RI</a></span></dt><dt><span class="section"><a href="#why-ws-addressing">12.2. Why WS-Addressing?</a></span></dt><dt><span class="section"><a href="#describing-ws-addressing-in-wsdl">12.3. Describing WS-Addressing in WSDL</a></span></dt><dt><span class="section"><a href="#configuring-addressing-on-endpoint">12.4. Configuring Addressing on Endpoint</a></span></dt><dt><span class="section"><a href="#on-the-client-side">12.5. On the client side</a></span></dt><dt><span class="section"><a href="#when-is-ws-addressing-engaged">12.6. When is WS-Addressing engaged?</a></span></dt><dt><span class="section"><a href="#associating-action-with-an-operation">12.7. Associating Action with an operation</a></span></dt></dl></dd><dt><span class="section"><a href="#users-guide-stateful-webservice">13. Stateful Webservice</a></span></dt><dd><dl><dt><span class="section"><a href="#introduction-1">13.1. Introduction</a></span></dt><dt><span class="section"><a href="#usage">13.2. Usage</a></span></dt><dt><span class="section"><a href="#things-to-consider">13.3. Things To Consider</a></span></dt></dl></dd><dt><span class="section"><a href="#users-guide-catalog">14. Catalog</a></span></dt><dd><dl><dt><span class="section"><a href="#section-529979392543239">14.1. Catalog Support</a></span></dt></dl></dd><dt><span class="section"><a href="#users-guide-war-file-packaging">15. WAR File Packaging</a></span></dt><dd><dl><dt><span class="section"><a href="#section-5694250262578">15.1. The WAR Contents</a></span></dt><dt><span class="section"><a href="#the-sun-jaxws-xml-file">15.2. The <code class="literal">sun-jaxws.xml</code> File</a></span></dt><dt><span class="section"><a href="#section-42577169574826">15.3. The <code class="literal">web.xml</code> File</a></span></dt></dl></dd><dt><span class="section"><a href="#users-guide-interoperability">16. Interoperability</a></span></dt><dd><dl><dt><span class="section"><a href="#section-4101350549640481">16.1. WSDL and Message Level Interoperability</a></span></dt><dt><span class="section"><a href="#section-325661411410258">16.2. .NET 3.5 Interoperability</a></span></dt></dl></dd><dt><span class="section"><a href="#users-guide-endpoint-api">17. Endpoint API</a></span></dt><dd><dl><dt><span class="section"><a href="#section-0499646435494807">17.1. <code class="literal">Endpoint</code></a></span></dt><dt><span class="section"><a href="#section-2491869058427427">17.2. <code class="literal">Endpoint</code> and <code class="literal">Properties</code></a></span></dt><dt><span class="section"><a href="#section-9038221558727715">17.3. <code class="literal">Endpoint</code> and <code class="literal">Binding</code></a></span></dt><dt><span class="section"><a href="#section-091994350952741">17.4. <code class="literal">Endpoint</code> and <code class="literal">metadata</code></a></span></dt></dl></dd></dl></dd><dt><span class="chapter"><a href="#tools">Tools</a></span></dt><dd><dl><dt><span class="section"><a href="#tools-overview">1. Overview</a></span></dt><dd><dl><dt><span class="section"><a href="#apttool">1.1. <span class="command"><strong>apt</strong></span></a></span></dt><dt><span class="section"><a href="#wscompiletool">1.2. <span class="command"><strong>wsimport</strong></span></a></span></dt><dt><span class="section"><a href="#wsdeploytool">1.3. <span class="command"><strong>wsgen</strong></span></a></span></dt><dt><span class="section"><a href="#how">1.4. How do I pick a tool?</a></span></dt></dl></dd><dt><span class="section"><a href="#tools-wsimport">2. <span class="command"><strong>wsimport</strong></span></a></span></dt><dd><dl><dt><span class="section"><a href="#wsimport-overview">2.1. <span class="command"><strong>wsimport</strong></span> Overview</a></span></dt><dt><span class="section"><a href="#launching-wsimport">2.2. Launching <span class="command"><strong>wsimport</strong></span></a></span></dt><dt><span class="section"><a href="#running-wsimport-on-jdk-6">2.3. Running <span class="command"><strong>wsimport</strong></span> on JDK 6</a></span></dt><dt><span class="section"><a href="#wsimport-syntax">2.4. <span class="command"><strong>wsimport</strong></span> Syntax</a></span></dt><dt><span class="section"><a href="#wsimport-example">2.5. <span class="command"><strong>wsimport</strong></span> Example</a></span></dt></dl></dd><dt><span class="section"><a href="#tools-wsimport-ant-task">3. <span class="command"><strong>wsimport</strong></span> Ant Task</a></span></dt><dd><dl><dt><span class="section"><a href="#wsimport-task-overview">3.1. <span class="command"><strong>wsimport</strong></span> Task Overview</a></span></dt><dt><span class="section"><a href="#using-wsimport-task">3.2. Using <span class="command"><strong>wsimport</strong></span> Task</a></span></dt><dt><span class="section"><a href="#running-wsimport-task-on-jdk-6">3.3. Running <span class="command"><strong>wsimport</strong></span> Task on JDK 6</a></span></dt><dt><span class="section"><a href="#examples">3.4. <span class="command"><strong>wsimport</strong></span> Examples</a></span></dt></dl></dd><dt><span class="section"><a href="#tools-wsgen">4. <span class="command"><strong>wsgen</strong></span></a></span></dt><dd><dl><dt><span class="section"><a href="#wsgen-overview">4.1. <span class="command"><strong>wsgen</strong></span> Overview</a></span></dt><dt><span class="section"><a href="#launching-wsgen">4.2. Launching <span class="command"><strong>wsgen</strong></span></a></span></dt><dt><span class="section"><a href="#running-wsgen-on-jdk-6">4.3. Running <span class="command"><strong>wsgen</strong></span> on JDK 6</a></span></dt><dt><span class="section"><a href="#wsgen-syntax">4.4. <span class="command"><strong>wsgen</strong></span> Syntax</a></span></dt><dt><span class="section"><a href="#wsgen-example">4.5. <span class="command"><strong>wsgen</strong></span> Example</a></span></dt></dl></dd><dt><span class="section"><a href="#tools-wsgen-ant-task">5. <span class="command"><strong>wsgen</strong></span> Ant Task</a></span></dt><dd><dl><dt><span class="section"><a href="#wsgen-task-overview">5.1. <span class="command"><strong>wsgen</strong></span> Task Overview</a></span></dt><dt><span class="section"><a href="#wsgen-task-attributes">5.2. <span class="command"><strong>wsgen</strong></span> Task Attributes</a></span></dt><dt><span class="section"><a href="#running-wsgen-task-on-jdk-6">5.3. Running <span class="command"><strong>wsgen</strong></span> Task on JDK 6</a></span></dt><dt><span class="section"><a href="#wsgen-task-example">5.4. <span class="command"><strong>wsgen</strong></span> Task Example</a></span></dt></dl></dd><dt><span class="section"><a href="#tools-apt">6. <span class="command"><strong>apt</strong></span></a></span></dt><dd><dl><dt><span class="section"><a href="#section-8324588054404016">6.1. <span class="command"><strong>apt</strong></span></a></span></dt><dt><span class="section"><a href="#running-apt-on-jdk-6">6.2. Running <span class="command"><strong>apt</strong></span> on JDK 6</a></span></dt><dt><span class="section"><a href="#moztocid408933">6.3. <span class="command"><strong>apt</strong></span> Syntax</a></span></dt></dl></dd><dt><span class="section"><a href="#tools-apt-ant-task">7. <span class="command"><strong>apt</strong></span> Ant Task</a></span></dt><dd><dl><dt><span class="section"><a href="#d0e9860">7.1. <span class="command"><strong>apt</strong></span> Task Overview</a></span></dt><dt><span class="section"><a href="#d0e9870">7.2. <span class="command"><strong>apt</strong></span> Task Attributes</a></span></dt><dt><span class="section"><a href="#running-apt-task-on-jdk-6">7.3. Running <span class="command"><strong>apt</strong></span> Task on JDK 6</a></span></dt><dt><span class="section"><a href="#section-26459256796099617">7.4. <span class="command"><strong>apt</strong></span> Task Examples</a></span></dt></dl></dd></dl></dd><dt><span class="chapter"><a href="#jax-ws-ri-extensions">Extensions</a></span></dt><dd><dl><dt><span class="section"><a href="#jax-ws-ri-extensions-extensions">1. Extensions</a></span></dt><dd><dl><dt><span class="section"><a href="#sending-and-receiving-soap-headers">1.1. Sending and Receiving SOAP Headers</a></span></dt><dt><span class="section"><a href="#message-logging">1.2. Message logging</a></span></dt><dt><span class="section"><a href="#propagation-of-server-side-stacktrace">1.3. Propagation of Server-side Stacktrace</a></span></dt></dl></dd></dl></dd><dt><span class="chapter"><a href="#samples">Samples</a></span></dt><dd><dl><dt><span class="section"><a href="#samples-samples">1. Samples</a></span></dt><dd><dl><dt><span class="section"><a href="#a-1-0">1.1. Directory Structure</a></span></dt><dt><span class="section"><a href="#a-2-0">1.2. Prerequisites</a></span></dt><dt><span class="section"><a href="#a-3-0">1.3. Installing JAX-WS RI 2.2.7</a></span></dt><dt><span class="section"><a href="#a-4-0">1.4. Running the sample</a></span></dt></dl></dd></dl></dd></dl></div><div lang="en" class="chapter" title="Overview" id="jax-ws-ri-overview"><div class="titlepage"><div><div><h2 class="title">Overview</h2></div></div></div><div class="toc"><p><b>Table of Contents</b></p><dl><dt><span class="section"><a href="#section-159360148062263">1. Documentation</a></span></dt><dt><span class="section"><a href="#section-0073999762824">2. Software Licenses</a></span></dt><dt><span class="section"><a href="#section-302002852812141">3. Useful Links</a></span></dt><dd><dl><dt><span class="section"><a href="#other-links">3.1. Other links</a></span></dt></dl></dd></dl></div><p>JAX-WS RI 2.2.7 is a Web Services framework that provides tools and infrastructure to develop Web Services solutions for the end users and middleware developers.</p><p>With JAX-WS RI 2.2.7, clients and web services have a big advantage: the platform independence of the Java programming language.</p><div class="section" title="1. Documentation"><div class="titlepage"><div><div><h2 class="title" style="clear: both" id="section-159360148062263">1. Documentation</h2></div></div></div><p>This release includes the following documentation:</p><div class="itemizedlist"><ul class="itemizedlist" type="disc"><li class="listitem"><p><a class="xref" href="#jax-ws-ri-release-notes" title="Release Notes"><i>Release Notes</i></a></p></li><li class="listitem"><p><a class="xref" href="#users-guide" title="Users Guide"><i>Users Guide</i></a></p></li><li class="listitem"><p><a class="xref" href="#tools" title="Tools"><i>Tools</i></a></p></li><li class="listitem"><p><a class="xref" href="#samples-samples" title="1. Samples">Samples</a></p></li><li class="listitem"><p><a class="link" href="http://jax-ws.java.net/spec-download.html" target="_top">API Documentation</a></p></li></ul></div><p>The documentation/samples included with JAX-WS that is distributed on Java.net describes how to use JAX-WS to develop and deploy your webservices endpoints in a servlet container. The samples discussed in this document and available as part of JAX-WS distribution are tested to work on Glassfish and on Apache Tomcat. The deployment is demonstrated using JAX-WS RI specific proprietary deployment descriptor sun-jaxws.xml. </p><p>If you wish to use JAX-WS in a Java EE container in a portable manner (using JSR 109 deployment descriptors), please refer to the <a class="link" href="http://java.sun.com/javaee/index.jsp" target="_top">Java EE 6</a> or <a class="link" href="http://glassfish.java.net/" target="_top">Glassfish</a> documentation/samples. The majority of the documentation included with JAX-WS is valid with Java EE 6 as well.</p></div><div class="section" title="2. Software Licenses"><div class="titlepage"><div><div><h2 class="title" style="clear: both" id="section-0073999762824">2. Software Licenses</h2></div></div></div><div class="itemizedlist"><ul class="itemizedlist" type="disc"><li class="listitem"><p><a class="link" href="Copyright.txt" target="_top">2010 Oracle Corporation and/or its affiliates. All rights reserved.</a></p></li><li class="listitem"><p>JAX-WS 2.2.7 is covered by <a class="link" href="http://glassfish.java.net/public/CDDL+GPL.html" target="_top">CDDL v1.1 and GPL v2</a></p></li><li class="listitem"><p><a class="link" href="ThirdPartyLicense.txt" target="_top">3rd Party License README</a></p></li></ul></div></div><div class="section" title="3. Useful Links"><div class="titlepage"><div><div><h2 class="title" style="clear: both" id="section-302002852812141">3. Useful Links</h2></div></div></div><p>Please use the <a class="link" href="http://www.java.net/forums/glassfish/metro-and-jaxb" target="_top">Metro and JAXB</a> forum for feedback.</p><p>JAX-WS has a project page on Java.net: <a class="link" href="http://jax-ws.java.net" target="_top">http://jax-ws.java.net</a>.</p><div class="section" title="3.1. Other links"><div class="titlepage"><div><div><h3 class="title" id="other-links">3.1. Other links</h3></div></div></div><p><a class="link" href="http://java.net/projects/jax-ws/lists" target="_top">Mailing List</a></p><p><a class="link" href="mailto:users@jax-ws.java.net" target="_top">User Feedback</a></p><p><a class="link" href="http://jax-ws.java.net/faq/index.html" target="_top">FAQ</a></p><p><a class="link" href="http://jax-ws.java.net/roadmap/jaxws-roadmap.html" target="_top">RoadMap</a></p><p><a class="link" href="http://java.net/jira/browse/JAX_WS" target="_top">Issue Tracker</a></p></div></div></div><div lang="en" class="chapter" title="Release Notes" id="jax-ws-ri-release-notes"><div class="titlepage"><div><div><h2 class="title">Release Notes</h2></div></div></div><div class="toc"><p><b>Table of Contents</b></p><dl><dt><span class="section"><a href="#overview">1. Overview</a></span></dt><dt><span class="section"><a href="#features-in-this-release">2. Features in this release</a></span></dt><dt><span class="section"><a href="#online-documentation">3. Online Documentation</a></span></dt><dt><span class="section"><a href="#required-software">4. Required Software</a></span></dt><dt><span class="section"><a href="#installation-instructions">5. Installation Instructions</a></span></dt><dt><span class="section"><a href="#running-on-top-of-jdk-6">6. Running on top of JDK 6</a></span></dt><dt><span class="section"><a href="#jar-dependency">7. Jar dependency</a></span></dt><dt><span class="section"><a href="#current-limitations">8. Current Limitations</a></span></dt><dt><span class="section"><a href="#bugs-fixed-in-this-release">9. Bugs Fixed in this release</a></span></dt><dt><span class="section"><a href="#known-bugs-issues">10. Known Bugs/Issues</a></span></dt><dt><span class="section"><a href="#for-more-information">11. For More Information</a></span></dt><dt><span class="section"><a href="#jax-ws-ri-changelog">12. Changelog</a></span></dt><dd><dl><dt><span class="section"><a href="#changes-221-223">12.1. Changes from JAX-WS RI 2.2.1 to JAX-WS RI 2.2.3 </a></span></dt><dt><span class="section"><a href="#changes-22-221">12.2. Changes from JAX-WS RI 2.2 to JAX-WS RI 2.2.1 </a></span></dt><dt><span class="section"><a href="#changes-217-22">12.3. Changes from JAX-WS RI 2.1.7 to JAX-WS RI 2.2 </a></span></dt><dt><span class="section"><a href="#changes-216-217">12.4. Changes from JAX-WS RI 2.1.6 to JAX-WS RI 2.1.7 </a></span></dt><dt><span class="section"><a href="#changes-215-216">12.5. Changes from JAX-WS RI 2.1.5 to JAX-WS RI 2.1.6 </a></span></dt><dt><span class="section"><a href="#changes-214-215">12.6. Changes from JAX-WS RI 2.1.4 to JAX-WS RI 2.1.5 </a></span></dt><dt><span class="section"><a href="#changes-213-214">12.7. Changes from JAX-WS RI 2.1.3 to JAX-WS RI 2.1.4</a></span></dt><dt><span class="section"><a href="#changes-211-213">12.8. Changes from JAX-WS RI 2.1.2 to JAX-WS RI 2.1.3</a></span></dt><dt><span class="section"><a href="#changes-211-212">12.9. Changes from JAX-WS RI 2.1.1 to JAX-WS RI 2.1.2</a></span></dt><dt><span class="section"><a href="#changes-20-21">12.10. Changes from JAX-WS 2.0 RI to JAX-WS RI 2.1.1</a></span></dt></dl></dd></dl></div><div class="section" title="1. Overview"><div class="titlepage"><div><div><h2 class="title" style="clear: both" id="overview">1. Overview</h2></div></div></div><p>JAX-WS RI 2.2.7 is a Web Services framework that provides tools and infrastructure to develop Web Services solutions for the end users and middleware developers.</p></div><div class="section" title="2. Features in this release"><div class="titlepage"><div><div><h2 class="title" style="clear: both" id="features-in-this-release">2. Features in this release</h2></div></div></div><div class="itemizedlist"><ul class="itemizedlist" type="disc"><li class="listitem"><p>Reference Implementation (RI) of JAX-WS 2.2 API. Full <a class="link" href="http://jcp.org/en/jsr/detail?id=224" target="_top">JAX-WS 2.2</a> compliance</p></li><li class="listitem"><p>Development Tools </p><div class="itemizedlist"><ul class="itemizedlist" type="circle"><li class="listitem"><p>WSDL to Java generator </p><div class="itemizedlist"><ul class="itemizedlist" type="square"><li class="listitem"><p><a class="xref" href="#tools-wsimport" title="2. wsimport"><span class="command"><strong>wsimport</strong></span></a>, <a class="xref" href="#tools-wsimport-ant-task" title="3. wsimport Ant Task"><span class="command"><strong>wsimport</strong></span> Ant Task</a> and <a class="link" href="http://jax-ws-commons.java.net/jaxws-maven-plugin/" target="_top">Maven2 plugin</a></p></li></ul></div></li><li class="listitem"><p>Java to WSDL generator </p><div class="itemizedlist"><ul class="itemizedlist" type="square"><li class="listitem"><p><a class="xref" href="#tools-wsgen" title="4. wsgen"><span class="command"><strong>wsgen</strong></span></a>, <a class="xref" href="#tools-wsgen-ant-task" title="5. wsgen Ant Task"><span class="command"><strong>wsgen</strong></span> Ant Task</a> and <a class="link" href="http://jax-ws-commons.java.net/jaxws-maven-plugin/" target="_top">Maven2 plugin</a></p></li></ul></div></li></ul></div></li><li class="listitem"><p>Standards </p><div class="itemizedlist"><ul class="itemizedlist" type="circle"><li class="listitem"><p>Web Services Addressing 1.0 - Core</p></li><li class="listitem"><p>Web Services Addressing 1.0 - SOAP Binding</p></li><li class="listitem"><p>Web Services Addressing 1.0 - Metadata</p></li><li class="listitem"><p>Web Services Addressing 1.0 - WSDL Binding (RI specific support)</p></li><li class="listitem"><p>WS-Addressing - Member Submission</p></li><li class="listitem"><p>SOAP 1.1 and 1.2</p></li><li class="listitem"><p>REST and XML/HTTP</p></li><li class="listitem"><p>WS-I Basic Profile 1.2 and 2.0</p></li><li class="listitem"><p>WS-I Simple SOAP Binding Profile 1.0</p></li><li class="listitem"><p>WS-I Attachment Profile 1.0</p></li><li class="listitem"><p>MTOM</p></li></ul></div></li><li class="listitem"><p>Extensions (May not be final unless says so) </p><div class="itemizedlist"><ul class="itemizedlist" type="circle"><li class="listitem"><p>Web Services Interoperable Technologies (<a class="link" href="http://wsit.java.net/jax-ws-ri-overview#downloads" target="_top">WSIT</a>) - enables .NET 3.x interoperability </p><div class="itemizedlist"><ul class="itemizedlist" type="square"><li class="listitem"><p>WS-ReliableMessaging</p></li><li class="listitem"><p>WS-Policy</p></li><li class="listitem"><p>WS-MEX</p></li><li class="listitem"><p>WS-Security/WS-Security Policy</p></li><li class="listitem"><p>WS-Trust/WS-Secure Conversation</p></li><li class="listitem"><p>WS-AT/WS-Tx (Supported only on Glassfish v2)</p></li><li class="listitem"><p>SOAP/TCP</p></li></ul></div></li><li class="listitem"><p><a class="link" href="http://jax-ws-commons.java.net/spring/" target="_top">Spring support</a></p></li><li class="listitem"><p><a class="link" href="http://jax-ws.java.net/transport.html" target="_top">Pluggable Transport</a> </p><div class="itemizedlist"><ul class="itemizedlist" type="square"><li class="listitem"><p>In-VM transport</p></li><li class="listitem"><p>Servlet transport (bundled with the RI)</p></li><li class="listitem"><p><a class="link" href="http://jms-ws-transport.java.net/" target="_top">JMS transport</a></p></li><li class="listitem"><p>SOAP over TCP transport (part of <a class="link" href="http://wsit.java.net" target="_top">WSIT</a>)</p></li></ul></div></li><li class="listitem"><p><a class="link" href="http://fi.java.net/" target="_top">FastInfoset</a> (bundled with JAX-WS RI 2.2.7)</p><div class="itemizedlist"><ul class="itemizedlist" type="square"><li class="listitem"><p><a class="link" href="http://www.itu.int/rec/T-REC-X.891-200505-I/e" target="_top">ITU-T Rec. X.891 | ISO/IEC 24824-1</a></p></li></ul></div></li><li class="listitem"><p>JBI Service Engine and Binding Component(part of Glassfish v2)</p></li><li class="listitem"><p><a class="link" href="http://www.glassfishwiki.org/jbiwiki/Wiki.jsp?page=HTTPBC" target="_top">HTTP Binding Component</a>, used by <a class="link" href="http://open-jbi-components.java.net/" target="_top">Open JBI component</a></p></li></ul></div></li><li class="listitem"><p>Data binding - <a class="link" href="http://jaxb.java.net/2.2/" target="_top">JAXB RI 2.2.3 u1</a></p></li><li class="listitem"><p>Server Side Asynchrony - <a class="link" href="http://jax-ws.java.net/nonav/21/docs/asyncusers-guide-provider" target="_top">AsyncProvider</a></p></li><li class="listitem"><p><a class="link" href="http://jax-ws.java.net/nonav/21/docs/users-guide-stateful-webservice" target="_top">Stateful Web Services</a></p></li><li class="listitem"><p>Support for <a class="link" href="http://weblogs.java.net/blog/ramapulavarthi/archive/2007/01/extending_jaxws.html" target="_top">custom WebServiceFeature</a></p></li><li class="listitem"><p><a class="link" href="http://jax-ws-architecture-document.java.net/nonav/doc21/jax-ws-ri-overview?com/sun/xml/ws/api/server/package-summary.html" target="_top">Hosting API</a> </p><div class="itemizedlist"><ul class="itemizedlist" type="circle"><li class="listitem"><p>These APIs can be used b y a J2EE application server to integrate JAX-WS RI 2.2.7 for hosting JAX-WS services</p></li></ul></div></li><li class="listitem"><p>Endpoint Deployment </p><div class="itemizedlist"><ul class="itemizedlist" type="circle"><li class="listitem"><p><a class="link" href="http://glassfish.java.net" target="_top">Glassfish v3</a> </p><div class="itemizedlist"><ul class="itemizedlist" type="square"><li class="listitem"><p>Tightly integrated with Glassfish</p></li><li class="listitem"><p>Supports EJB and Web endpoints</p></li><li class="listitem"><p>109 based deployment support for better portability</p></li><li class="listitem"><p>JAX-WS RI specific deployment descriptor support</p></li></ul></div></li><li class="listitem"><p><a class="link" href="http://www.sun.com/software/products/appsrvr_pe/index.xml" target="_top">Sun One Application Server 9.0 ur1</a></p></li><li class="listitem"><p>Light weight HTTP server </p><div class="itemizedlist"><ul class="itemizedlist" type="square"><li class="listitem"><p>Bundled with JDK 6</p></li></ul></div></li><li class="listitem"><p>Any other container that supports Servlet 2.4, such as Tomcat, Jetty, Geronimo, JBoss, Resin, ... You name it!</p></li></ul></div></li></ul></div><p>This release brings in the highly pluggable framework through abstractions such as <a class="link" href="http://jax-ws-architecture-document.java.net/nonav/doc21/com/sun/xml/ws/api/pipe/Tube.html" target="_top">Tube</a> and <a class="link" href="http://jax-ws-architecture-document.java.net/nonav/doc21/com/sun/xml/ws/api/message/Message.html" target="_top">Message</a>. This architecture document is a glorified javadoc which includes all the JAX-WS RI specific APIs. JAX-WS RI 2.2.7 has many bug fixes made for interoperability with .NET 3.0. This is made mostly possible due to WSIT, which uses JAX-WS plugabble architecture to plug in support for WS-Metadata, WS-Policy, WS-ReliableMessaging, WS-Transaction, WS-SecureConversation and WS-Security.</p><p>If you wish to use JAX-WS RI 2.2.7 in a Java EE container in a Java EE portable manner you need to use the standard Java EE 6 deployment descriptor; please refer to the <a class="link" href="http://java.sun.com/javaee/index.jsp" target="_top">Java EE 6</a> or <a class="link" href="http://glassfish.java.net/" target="_top">Glassfish</a> documentation/samples. The majority of the documentation included with JAX-WS is valid with Java EE 6 as well.</p></div><div class="section" title="3. Online Documentation"><div class="titlepage"><div><div><h2 class="title" style="clear: both" id="online-documentation">3. Online Documentation</h2></div></div></div><p>The documentation for JAX-WS RI 2.2.7 as well as the sample applications will be periodically updated in the JAX-WS <a class="link" href="http://jax-ws.java.net" target="_top">project</a>.</p><p>The architecture document describing the latest JAX-WS RI 2.2.7 can be found <a class="link" href="http://jax-ws-architecture-document.java.net/nonav/doc21/?jaxws/package-summary.html" target="_top">here</a> .</p><p>Please go to <a class="link" href="http://jax-ws.java.net/" target="_top">http://jax-ws.java.net</a> for the latest documentation and samples.</p></div><div class="section" title="4. Required Software"><div class="titlepage"><div><div><h2 class="title" style="clear: both" id="required-software">4. Required Software</h2></div></div></div><div class="itemizedlist"><ul class="itemizedlist" type="disc"><li class="listitem"><p>Requires <a class="link" href="http://java.sun.com/products/archive/j2se/5.0_02/jax-ws-ri-overview" target="_top">JDK 5.0 Update 2</a> or later</p></li><li class="listitem"><p>Requires <a class="link" href="http://ant.apache.org/bindownload.cgi" target="_top">Ant 1.6.2</a> or later</p></li><li class="listitem"><p>Tested to work with GlassFish v3.1 and Apache Tomcat 5.5.x</p></li></ul></div></div><div class="section" title="5. Installation Instructions"><div class="titlepage"><div><div><h2 class="title" style="clear: both" id="installation-instructions">5. Installation Instructions</h2></div></div></div><p>The following applies to the JAX-WS standalone bundles.</p><div class="itemizedlist"><ul class="itemizedlist" type="disc"><li class="listitem"><p>Extract JAX-WS RI 2.2.7 bundle</p></li><li class="listitem"><p>To install on GlassFish v2 </p><div class="itemizedlist"><ul class="itemizedlist" type="circle"><li class="listitem"><p>If you want to use the JAX-WS RI 2.2.7 overriding the one with Glassfish v2, Download Metro 2.1 bundle from http://metro.java.net and follow the instructions in that bundle</p></li></ul></div></li><li class="listitem"><p>To use with GlassFish v3.1 </p><div class="itemizedlist"><ul class="itemizedlist" type="circle"><li class="listitem"><p>GlassFish v3.1 has JAX-WS RI 2.2.7, so there is no installation step.</p></li></ul></div></li><li class="listitem"><p>To install on Tomcat </p><div class="itemizedlist"><ul class="itemizedlist" type="circle"><li class="listitem"><p>Set <code class="literal">CATALINA_HOME</code> to your Tomcat installation.</p></li><li class="listitem"><p>Run </p><pre class="programlisting">ant install</pre><p>This essentially copies <code class="filename">lib/*.jar</code> from the root of JAX-WS RI extracted bundle to <code class="literal">$CATALINA_HOME/shared/lib</code></p></li><li class="listitem"><p>If you are running on top of JDK6, run </p><pre class="programlisting">ant install-api</pre><p>or use </p><pre class="programlisting">ant -help</pre><p> for detailed information.</p></li></ul></div></li></ul></div><p>If you intend to only invoke an already existing Web service, then alternatively you can use the <span class="command"><strong>wsimport</strong></span> and <span class="command"><strong>wsgen</strong></span> scripts in the <code class="literal">bin</code> directory of the JAX-WS RI 2.2.7 bundle.</p></div><div class="section" title="6. Running on top of JDK 6"><div class="titlepage"><div><div><h2 class="title" style="clear: both" id="running-on-top-of-jdk-6">6. Running on top of JDK 6</h2></div></div></div><p>JDK 6u4 includes JAX-WS 2.1 and JAXB 2.1 API and RI. JAX-WS RI 2.2.7 includes RI of JAX-WS/JAXB 2.2. In order to run JAX-WS RI 2.2.7 you would need to specify ONLY <code class="filename">jaxws-api.jar</code>, and <code class="filename">jaxb-api.jar</code> jars using the <a class="link" href="http://java.sun.com/javase/6/docs/technotes/guides/standards/jax-ws-ri-overview" target="_top">Java Endorsed Standards Override Mechanism</a></p></div><div class="section" title="7. Jar dependency"><div class="titlepage"><div><div><h2 class="title" style="clear: both" id="jar-dependency">7. Jar dependency</h2></div></div></div><div class="table"><a name="d0e455"></a><p class="title"><b>Table 1. Jar dependencies summary</b></p><div class="table-contents"><table summary="Jar dependencies summary" border="1"><colgroup><col width="20%"><col width="80%"></colgroup><tbody><tr><td><p>Runtime Jars</p></td><td><p><code class="filename">FastInfoset.jar</code>, <code class="filename">jaxb-api.jar</code>, <code class="filename">jaxb-impl.jar</code>, <code class="filename">jaxws-api.jar</code>, <code class="filename">jaxws-rt.jar</code>, <code class="filename">jsr181-api.jar</code>, <code class="filename">javax.annotation.jar</code>, <code class="filename">mimepull.jar</code>, <code class="filename">saaj-api.jar</code>, <code class="filename">saaj-impl.jar *</code>, <code class="filename">stax2-api.jar</code>, <code class="filename">woodstox-core-asl.jar</code>, <code class="filename">stax-ex.jar</code>, <code class="filename">streambuffer.jar</code>, <code class="filename">policy.jar</code>, <code class="filename">gmbal-api-only.jar</code>, <code class="filename">management-api.jar</code>, <code class="filename">ha-api.jar</code></p></td></tr><tr><td><p>Tooltime Jars</p></td><td><p>All the runtime jars + <code class="filename">jaxb-xjc.jar</code>, <code class="filename">jaxws-tools.jar</code></p></td></tr></tbody></table></div></div><br class="table-break"><p>If you run JAX-WS RI 2.2.7 with IBM JDK, there are two options: </p><div class="itemizedlist"><ul class="itemizedlist" type="disc"><li class="listitem"><p>to add Oracles's JAXP implementation jars along</p></li><li class="listitem"><p>to remove the saaj-impl.jar from the libraries in order IBM SAAJ implementation to be used</p></li></ul></div><p> First approach is recommended. </p></div><div class="section" title="8. Current Limitations"><div class="titlepage"><div><div><h2 class="title" style="clear: both" id="current-limitations">8. Current Limitations</h2></div></div></div><div class="itemizedlist"><ul class="itemizedlist" type="disc"><li class="listitem"><p>The <code class="literal">java.util.Collection</code> classes cannot be used with rpc/literal or document/literal <code class="literal">BARE</code> style due to a limitation in JAXB. However, they do work in the default document/literal <code class="literal">WRAPPED</code> style.</p></li></ul></div></div><div class="section" title="9. Bugs Fixed in this release"><div class="titlepage"><div><div><h2 class="title" style="clear: both" id="bugs-fixed-in-this-release">9. Bugs Fixed in this release</h2></div></div></div><div class="itemizedlist"><ul class="itemizedlist" type="disc"><li class="listitem"><p><a class="link" href="http://java.net/jira/secure/IssueNavigator.jspa?mode=hide&requestId=10284" target="_top">Bug fixes</a></p></li></ul></div></div><div class="section" title="10. Known Bugs/Issues"><div class="titlepage"><div><div><h2 class="title" style="clear: both" id="known-bugs-issues">10. Known Bugs/Issues</h2></div></div></div><div class="itemizedlist"><ul class="itemizedlist" type="disc"><li class="listitem"><p>Although JAX-WS customizations are portable across implementations, the names of WSDL and schema files generated are not specified. Therefore each vendor may and most likely will generate different names. Therefore, when switching between implementations of JAX-WS, it may be necessary to modify your customization files to reflect different WSDL and schema file names.</p></li><li class="listitem"><p>This holds true for different releases of the JAX-WS RI. The JAX-WS RI may in each release change these file names to resolve bugs. If and when this does occur, a developer would need to change the filenames in their customization files to match the new file names.</p></li><li class="listitem"><p>A <a class="link" href="https://jax-ws.dev.java.net/issues/show_bug.cgi?id=647" target="_top">bug in <span class="command"><strong>apt</strong></span> ant task</a> makes it not work by default. Workaround is to use <code class="literal">fork="true"</code> option in the <span class="command"><strong>apt</strong></span> task.</p></li></ul></div></div><div class="section" title="11. For More Information"><div class="titlepage"><div><div><h2 class="title" style="clear: both" id="for-more-information">11. For More Information</h2></div></div></div><p>Go to <a class="link" href="http://jax-ws.java.net/" target="_top">http://jax-ws.java.net</a>.</p><p>Send your feedback to <a class="link" href="mailto:users@metro.java.net" target="_top">users@metro.java.net</a> or use the <a class="link" href="http://forums.java.net/jive/forum.jspa?forumID=46&start=0" target="_top">Metro and JAXB Forum</a></p></div><div lang="en" class="section" title="12. Changelog"><div class="titlepage"><div><div><h2 class="title" style="clear: both" id="jax-ws-ri-changelog">12. Changelog</h2></div></div></div><div class="section" title="12.1. Changes from JAX-WS RI 2.2.1 to JAX-WS RI 2.2.3 "><div class="titlepage"><div><div><h3 class="title" id="changes-221-223">12.1. Changes from JAX-WS RI 2.2.1 to JAX-WS RI 2.2.3 </h3></div></div></div><div class="itemizedlist"><ul class="itemizedlist" type="disc"><li class="listitem"><p><a class="link" href="http://java.net/jira/browse/JAX_WS-871" target="_top">Add -clientjar option for <span class="command"><strong>wsimport</strong></span></a></p></li><li class="listitem"><p><a class="link" href="http://java.net/jira/browse/JAX_WS-872" target="_top">Add support for Async Servlet Transport using Servlet 3.0 api</a></p></li><li class="listitem"><p><a class="link" href="http://java.net/jira/secure/IssueNavigator.jspa?mode=hide&requestId=10284" target="_top">Bug fixes</a></p></li></ul></div></div><div class="section" title="12.2. Changes from JAX-WS RI 2.2 to JAX-WS RI 2.2.1 "><div class="titlepage"><div><div><h3 class="title" id="changes-22-221">12.2. Changes from JAX-WS RI 2.2 to JAX-WS RI 2.2.1 </h3></div></div></div><div class="itemizedlist"><ul class="itemizedlist" type="disc"><li class="listitem"><p><a class="link" href="https://jax-ws.dev.java.net/issues/show_bug.cgi?id=85" target="_top">wsgen can inline schemas in a generated wsdl using a switch</a></p></li><li class="listitem"><p><a class="link" href="https://jax-ws.dev.java.net/issues/show_bug.cgi?id=777" target="_top">Schema Validation support is enhanced</a></p></li><li class="listitem"><p><a class="link" href="https://jax-ws.dev.java.net/issues/buglist.cgi?issue_type=DEFECT&issue_type=ENHANCEMENT&issue_type=FEATURE&issue_type=TASK&issue_type=PATCH&component=jax-ws&issue_status=RESOLVED&issue_status=VERIFIED&issue_status=CLOSED&resolution=FIXED&target_milestone=2.2.1&email1=&emailtype1=exact&emailassigned_to1=1&email2=&emailtype2=exact&emailreporter2=1&issueidtype=include&issue_id=&changedin=&votes=&chfieldfrom=&chfieldto=Now&chfieldvalue=&short_desc=&short_desc_type=fulltext&long_desc=&long_desc_type=fulltext&issue_file_loc=&issue_file_loc_type=fulltext&status_whiteboard=&status_whiteboard_type=fulltext&keywords=&keywords_type=anytokens&field0-0-0=noop&type0-0-0=noop&value0-0-0=&cmdtype=doit&newqueryname=&order=Reuse+same+sort+as+last+time&Submit+query=Submit+query" target="_top">Bug fixes</a></p></li></ul></div></div><div class="section" title="12.3. Changes from JAX-WS RI 2.1.7 to JAX-WS RI 2.2 "><div class="titlepage"><div><div><h3 class="title" id="changes-217-22">12.3. Changes from JAX-WS RI 2.1.7 to JAX-WS RI 2.2 </h3></div></div></div><div class="itemizedlist"><ul class="itemizedlist" type="disc"><li class="listitem"><p>Add WS-Addressing 1.0 Metadata support as per 2.2 spec</p></li><li class="listitem"><p>Support for <code class="literal">@XmlElement</code> on SEI's wrapper parameter</p></li><li class="listitem"><p>Support for <code class="literal">@XmlType</code> on exception classes</p></li><li class="listitem"><p>Implement HTTP SPI</p></li><li class="listitem"><p>Implement Endpoint API with features</p></li><li class="listitem"><p><a class="link" href="http://java.net/jira/browse/JAX_WS-818" target="_top">Generate new constructors in the generated Service class(service level features, wsdllocation)</a></p></li><li class="listitem"><p><a class="link" href="http://java.net/jira/browse/JAX_WS-726" target="_top">Add support for customizing wrapper <code class="literal">wsdl:part</code> names as defined in 2.2</a></p></li><li class="listitem"><p><a class="link" href="http://java.net/jira/browse/JAX_WS-727" target="_top">Add support for customizing <code class="literal">wsdl:message</code> name using <code class="literal">@WebFault</code> as defined in 2.2</a></p></li><li class="listitem"><p><a class="link" href="http://java.net/jira/browse/JAX_WS-728" target="_top">Fault customization should accept fully qualified name of the exception class to be generated</a></p></li><li class="listitem"><p><a class="link" href="http://java.net/jira/browse/JAX_WS-729" target="_top">Customization of Service should accept fully qualified class name</a></p></li><li class="listitem"><p><a class="link" href="http://java.net/jira/browse/JAX_WS-360" target="_top">Add Xnocompile option for <span class="command"><strong>wsgen</strong></span> similar to <span class="command"><strong>wsimport</strong></span></a></p></li><li class="listitem"><p><a class="link" href="http://java.net/jira/browse/JAX_WS-576" target="_top">XPath expressions in jax-ws customization can now select multiple nodes</a></p></li><li class="listitem"><p><a class="link" href="http://java.net/jira/browse/JAX_WS-761" target="_top">Disable server-side exception stacktrace for service specific exceptions</a></p></li><li class="listitem"><p><a class="link" href="http://java.net/jira/browse/JAX_WS-648" target="_top">Optimzation of LogicalMessage implementation</a></p></li><li class="listitem"><p><a class="link" href="http://java.net/jira/browse/JAX_WS-305" target="_top">wsimport now handles URL redirection of imported wsdls correctly</a></p></li><li class="listitem"><p><a class="link" href="https://jax-ws.dev.java.net/issues/buglist.cgi?issue_type=DEFECT&issue_type=ENHANCEMENT&issue_type=FEATURE&issue_type=TASK&issue_type=PATCH&component=jax-ws&issue_status=RESOLVED&issue_status=VERIFIED&issue_status=CLOSED&resolution=FIXED&target_milestone=2.2&email1=&emailtype1=exact&emailassigned_to1=1&email2=&emailtype2=exact&emailreporter2=1&issueidtype=include&issue_id=&changedin=&votes=&chfieldfrom=&chfieldto=Now&chfieldvalue=&short_desc=&short_desc_type=fulltext&long_desc=&long_desc_type=fulltext&issue_file_loc=&issue_file_loc_type=fulltext&status_whiteboard=&status_whiteboard_type=fulltext&keywords=&keywords_type=anytokens&field0-0-0=noop&type0-0-0=noop&value0-0-0=&cmdtype=doit&newqueryname=&order=Reuse+same+sort+as+last+time&Submit+query=Submit+query" target="_top">Bug fixes</a></p></li></ul></div></div><div class="section" title="12.4. Changes from JAX-WS RI 2.1.6 to JAX-WS RI 2.1.7 "><div class="titlepage"><div><div><h3 class="title" id="changes-216-217">12.4. Changes from JAX-WS RI 2.1.6 to JAX-WS RI 2.1.7 </h3></div></div></div><div class="itemizedlist"><ul class="itemizedlist" type="disc"><li class="listitem"><p><a class="link" href="https://jax-ws.dev.java.net/issues/buglist.cgi?Submit+query=Submit+query&issue_type=DEFECT&issue_type=ENHANCEMENT&component=jax-ws&issue_status=RESOLVED&issue_status=VERIFIED&resolution=FIXED&target_milestone=2.1.7&email1=&emailtype1=exact&emailassigned_to1=1&email2=&emailtype2=exact&emailreporter2=1&issueidtype=include&issue_id=&changedin=&votes=&chfieldfrom=&chfieldto=Now&chfieldvalue=&short_desc=&short_desc_type=fulltext&long_desc=&long_desc_type=fulltext&issue_file_loc=&issue_file_loc_type=fulltext&status_whiteboard=&status_whiteboard_type=fulltext&keywords=&keywords_type=anytokens&field0-0-0=noop&type0-0-0=noop&value0-0-0=&cmdtype=doit&namedcmd=as91only&newqueryname=&order=Reuse+same+sort+as+last+time" target="_top">Bug fixes</a></p></li></ul></div></div><div class="section" title="12.5. Changes from JAX-WS RI 2.1.5 to JAX-WS RI 2.1.6 "><div class="titlepage"><div><div><h3 class="title" id="changes-215-216">12.5. Changes from JAX-WS RI 2.1.5 to JAX-WS RI 2.1.6 </h3></div></div></div><div class="itemizedlist"><ul class="itemizedlist" type="disc"><li class="listitem"><p><a class="link" href="https://jax-ws.dev.java.net/issues/show_bug.cgi?id=741" target="_top">Supportfor transport attribute for bindings like SOAP/JMS binding</a></p></li><li class="listitem"><p><a class="link" href="https://jax-ws.dev.java.net/issues/buglist.cgi?Submit+query=Submit+query&issue_type=DEFECT&issue_type=ENHANCEMENT&component=jax-ws&issue_status=RESOLVED&issue_status=VERIFIED&resolution=FIXED&target_milestone=2.1.6&email1=&emailtype1=exact&emailassigned_to1=1&email2=&emailtype2=exact&emailreporter2=1&issueidtype=include&issue_id=&changedin=&votes=&chfieldfrom=&chfieldto=Now&chfieldvalue=&short_desc=&short_desc_type=fulltext&long_desc=&long_desc_type=fulltext&issue_file_loc=&issue_file_loc_type=fulltext&status_whiteboard=&status_whiteboard_type=fulltext&keywords=&keywords_type=anytokens&field0-0-0=noop&type0-0-0=noop&value0-0-0=&cmdtype=doit&namedcmd=as91only&newqueryname=&order=Reuse+same+sort+as+last+time" target="_top">Bug fixes</a></p></li></ul></div></div><div class="section" title="12.6. Changes from JAX-WS RI 2.1.4 to JAX-WS RI 2.1.5 "><div class="titlepage"><div><div><h3 class="title" id="changes-214-215">12.6. Changes from JAX-WS RI 2.1.4 to JAX-WS RI 2.1.5 </h3></div></div></div><div class="itemizedlist"><ul class="itemizedlist" type="disc"><li class="listitem"><p><a class="link" href="https://jax-ws.dev.java.net/issues/show_bug.cgi?id=607" target="_top">Allowing HTTP response code to be set via MessageContext property</a></p></li><li class="listitem"><p><a class="link" href="https://jax-ws.dev.java.net/issues/show_bug.cgi?id=282" target="_top">New feature: UsesJAXBContextFeature, to control JAXBContext creation</a></p></li><li class="listitem"><p><a class="link" href="https://jax-ws.dev.java.net/issues/show_bug.cgi?id=289" target="_top">New <span class="command"><strong>wsimport</strong></span> option: -XdisableSSLHostnameVerfication, to disable SSL Hostname verification</a></p></li><li class="listitem"><p><a class="link" href="https://jax-ws.dev.java.net/issues/show_bug.cgi?id=490" target="_top">Wsimport ant task accepts nested args for specifying additional options</a></p></li><li class="listitem"><p><a class="link" href="https://jax-ws.dev.java.net/issues/buglist.cgi?Submit+query=Submit+query&issue_type=DEFECT&issue_type=ENHANCEMENT&component=jax-ws&issue_status=RESOLVED&issue_status=VERIFIED&resolution=FIXED&target_milestone=2.1.5&email1=&emailtype1=exact&emailassigned_to1=1&email2=&emailtype2=exact&emailreporter2=1&issueidtype=include&issue_id=&changedin=&votes=&chfieldfrom=&chfieldto=Now&chfieldvalue=&short_desc=&short_desc_type=fulltext&long_desc=&long_desc_type=fulltext&issue_file_loc=&issue_file_loc_type=fulltext&status_whiteboard=&status_whiteboard_type=fulltext&keywords=&keywords_type=anytokens&field0-0-0=noop&type0-0-0=noop&value0-0-0=&cmdtype=doit&namedcmd=as91only&newqueryname=&order=Reuse+same+sort+as+last+time" target="_top">Bug fixes</a></p></li></ul></div></div><div class="section" title="12.7. Changes from JAX-WS RI 2.1.3 to JAX-WS RI 2.1.4"><div class="titlepage"><div><div><h3 class="title" id="changes-213-214">12.7. Changes from JAX-WS RI 2.1.3 to JAX-WS RI 2.1.4</h3></div></div></div><div class="itemizedlist"><ul class="itemizedlist" type="disc"><li class="listitem"><p><a class="link" href="http://weblogs.java.net/blog/jitu/archive/2008/03/alternative_to_1.html" target="_top">Simplified "Starting from Java Programming model" through dynamic generation of request and response wrappers</a></p></li><li class="listitem"><p><a class="xref" href="#samples-samples" title="1. Samples">Samples</a></p></li><li class="listitem"><p><a class="link" href="https://jax-ws.dev.java.net/issues/buglist.cgi?Submit+query=Submit+query&issue_type=DEFECT&issue_type=ENHANCEMENT&component=jax-ws&issue_status=RESOLVED&issue_status=VERIFIED&resolution=FIXED&target_milestone=2.1.4&email1=&emailtype1=exact&emailassigned_to1=1&email2=&emailtype2=exact&emailreporter2=1&issueidtype=include&issue_id=&changedin=&votes=&chfieldfrom=&chfieldto=Now&chfieldvalue=&short_desc=&short_desc_type=fulltext&long_desc=&long_desc_type=fulltext&issue_file_loc=&issue_file_loc_type=fulltext&status_whiteboard=&status_whiteboard_type=fulltext&keywords=&keywords_type=anytokens&field0-0-0=noop&type0-0-0=noop&value0-0-0=&cmdtype=doit&namedcmd=as91only&newqueryname=&order=Reuse+same+sort+as+last+time" target="_top">Bug fixes</a></p></li></ul></div></div><div class="section" title="12.8. Changes from JAX-WS RI 2.1.2 to JAX-WS RI 2.1.3"><div class="titlepage"><div><div><h3 class="title" id="changes-211-213">12.8. Changes from JAX-WS RI 2.1.2 to JAX-WS RI 2.1.3</h3></div></div></div><div class="itemizedlist"><ul class="itemizedlist" type="disc"><li class="listitem"><p><a class="link" href="https://jax-ws.dev.java.net/issues/show_bug.cgi?id=231" target="_top">Authentication support in <span class="command"><strong>wsimport</strong></span></a></p></li><li class="listitem"><p><a class="link" href="https://jax-ws.dev.java.net/issues/show_bug.cgi?id=263" target="_top">Additional header support</a></p></li><li class="listitem"><p><a class="link" href="https://jax-ws.dev.java.net/issues/show_bug.cgi?id=29" target="_top">Large and Streaming attachment support</a></p></li><li class="listitem"><p><a class="link" href="https://jax-ws.dev.java.net/issues/show_bug.cgi?id=239" target="_top">XML Schema validation support for SOAP message</a></p></li><li class="listitem"><p><a class="link" href="https://jax-ws.dev.java.net/issues/show_bug.cgi?id=473" target="_top">Expose the -Xnocompile as an Ant task option</a></p></li><li class="listitem"><p><a class="link" href="https://jax-ws.dev.java.net/issues/show_bug.cgi?id=437" target="_top">Additional WSDL object methods for policy</a></p></li><li class="listitem"><p><a class="link" href="https://jax-ws.dev.java.net/issues/show_bug.cgi?id=456" target="_top">Wsimport should be able to handle redirects and see Others</a></p></li><li class="listitem"><p><a class="link" href="https://jax-ws.dev.java.net/issues/show_bug.cgi?id=54" target="_top">Remove SJSXP and SAAJ RI dependency</a></p></li><li class="listitem"><p><a class="link" href="https://jax-ws.dev.java.net/issues/show_bug.cgi?id=387" target="_top">Wsimport should write to passed OutputStream</a></p></li><li class="listitem"><p><a class="link" href="https://jax-ws.dev.java.net/issues/show_bug.cgi?id=482" target="_top">Efficient Handler using Handler<Message> support</a></p></li><li class="listitem"><p><a class="link" href="https://jax-ws.dev.java.net/issues/buglist.cgi?Submit+query=Submit+query&issue_type=DEFECT&component=jax-ws&issue_status=RESOLVED&resolution=FIXED&target_milestone=2.1.3&email1=&emailtype1=exact&emailassigned_to1=1&email2=&emailtype2=exact&emailreporter2=1&issueidtype=include&issue_id=&changedin=&votes=&chfieldfrom=&chfieldto=Now&chfieldvalue=&short_desc=&short_desc_type=fulltext&long_desc=&long_desc_type=fulltext&issue_file_loc=&issue_file_loc_type=fulltext&status_whiteboard=&status_whiteboard_type=fulltext&keywords=&keywords_type=anytokens&field0-0-0=noop&type0-0-0=noop&value0-0-0=&cmdtype=doit&namedcmd=as91only&newqueryname=&order=Reuse+same+sort+as+last+time" target="_top">Bug fixes</a></p></li></ul></div></div><div class="section" title="12.9. Changes from JAX-WS RI 2.1.1 to JAX-WS RI 2.1.2"><div class="titlepage"><div><div><h3 class="title" id="changes-211-212">12.9. Changes from JAX-WS RI 2.1.1 to JAX-WS RI 2.1.2</h3></div></div></div><div class="itemizedlist"><ul class="itemizedlist" type="disc"><li class="listitem"><p>JMX Agent for the server side</p></li><li class="listitem"><p>Mtom Interop with .NET 2.0/WSE 3.0</p></li><li class="listitem"><p><a class="link" href="https://jax-ws.dev.java.net/issues/buglist.cgi?resort=1&issue_type=DEFECT;issue_type=ENHANCEMENT;issue_type=FEATURE;issue_type=TASK;component=jax-ws;issue_status=RESOLVED;resolution=FIXED;priority=P1;priority=P2;priority=P3;priority=P4;email1=;emailtype1=" target="_top">Bug fixes</a></p></li></ul></div></div><div class="section" title="12.10. Changes from JAX-WS 2.0 RI to JAX-WS RI 2.1.1"><div class="titlepage"><div><div><h3 class="title" id="changes-20-21">12.10. Changes from JAX-WS 2.0 RI to JAX-WS RI 2.1.1</h3></div></div></div><div class="itemizedlist"><ul class="itemizedlist" type="disc"><li class="listitem"><p>JAXB 2.1 RI Integration</p></li><li class="listitem"><p>JAX-WS 2.1 MR (JSR 224) implementation</p></li><li class="listitem"><p>Type substitution support</p></li><li class="listitem"><p>WS-Addressing - W3C and Memeber Submission</p></li><li class="listitem"><p>APIs to create EPR and use it to invoke endpoint</p></li><li class="listitem"><p>Support for enabling/disabling features, such as WS-Addressing/MTOM</p></li><li class="listitem"><p>Asynchronous server</p></li><li class="listitem"><p>Tubes and Fiber for asynchronous message processing</p></li><li class="listitem"><p>Dispatch<Message> and Provider<Message></p></li><li class="listitem"><p>Stateful Webservice support</p></li><li class="listitem"><p><a class="link" href="https://jax-ws.dev.java.net/issues/buglist.cgi?resort=1&issue_type=DEFECT;issue_type=ENHANCEMENT;issue_type=FEATURE;issue_type=TASK;component=jax-ws;issue_status=RESOLVED;resolution=FIXED;priority=P1;priority=P2;priority=P3;priority=P4;email1=;emailtype1=" target="_top">Bug fixes</a></p></li></ul></div></div></div></div><div lang="en" class="chapter" title="Users Guide" id="users-guide"><div class="titlepage"><div><div><h2 class="title">Users Guide</h2></div></div></div><div class="toc"><p><b>Table of Contents</b></p><dl><dt><span class="section"><a href="#users-guide-overview">1. Overview</a></span></dt><dd><dl><dt><span class="section"><a href="#introduction">1.1. Introduction</a></span></dt><dt><span class="section"><a href="#features">1.2. Features</a></span></dt><dt><span class="section"><a href="#programming-model">1.3. Programming Model</a></span></dt><dt><span class="section"><a href="#useful-information">1.4. Useful Information</a></span></dt></dl></dd><dt><span class="section"><a href="#users-guide-provider">2. Provider</a></span></dt><dd><dl><dt><span class="section"><a href="#section-3091238697838234">2.1. <code class="literal">Provider<Source></code> and <code class="literal">PAYLOAD</code></a></span></dt><dt><span class="section"><a href="#section-8519606736474974">2.2. <code class="literal">Provider<SOAPMessage></code> and <code class="literal">MESSAGE</code></a></span></dt><dt><span class="section"><a href="#section-7319353703410434">2.3. <code class="literal">Provider<Source></code> and <code class="literal">MESSAGE</code></a></span></dt><dt><span class="section"><a href="#section-674124516240791">2.4. WSDL Customization</a></span></dt><dt><span class="section"><a href="#section-648626808421419">2.5. The <code class="literal">sun-jaxws.xml</code> file</a></span></dt><dt><span class="section"><a href="#section-343591403757231">2.6. Provider and Binding</a></span></dt><dt><span class="section"><a href="#section-330867941262645">2.7. RESTful Provider endpoints</a></span></dt><dt><span class="section"><a href="#section-017933327977469">2.8. Provider and Handlers</a></span></dt></dl></dd><dt><span class="section"><a href="#users-guide-asyncprovider">3. AsyncProvider</a></span></dt><dd><dl><dt><span class="section"><a href="#section-091974998856598">3.1. <code class="literal">AsyncProvider</code> Example</a></span></dt><dt><span class="section"><a href="#section-930633228695613">3.2. <code class="literal">AsyncProvider</code> sample</a></span></dt><dt><span class="section"><a href="#section-5233554712491355">3.3. <code class="literal">AsyncService</code> sample</a></span></dt></dl></dd><dt><span class="section"><a href="#users-guide-dispatch">4. Dispatch</a></span></dt><dd><dl><dt><span class="section"><a href="#section-71379735580733">4.1. Programming Model</a></span></dt><dt><span class="section"><a href="#section-21282255346754875">4.2. Dispatch and Asynchronous Invocations</a></span></dt></dl></dd><dt><span class="section"><a href="#users-guide-asynchronous-client">5. Asynchronous Client</a></span></dt><dd><dl><dt><span class="section"><a href="#section-346120708971664">5.1. Asynchronous Invocation Using Static Stub</a></span></dt><dt><span class="section"><a href="#section-85273158180115">5.2. Asynchronous Invocation Using Dispatch</a></span></dt></dl></dd><dt><span class="section"><a href="#users-guide-handler">6. Handler</a></span></dt><dd><dl><dt><span class="section"><a href="#section-524340464580105">6.1. Handler Types</a></span></dt><dt><span class="section"><a href="#section-276528078695232">6.2. MessageContext</a></span></dt><dt><span class="section"><a href="#section-165423693536683">6.3. Handler Chain Configuration</a></span></dt><dt><span class="section"><a href="#section-8594509924044">6.4. Handler Samples</a></span></dt></dl></dd><dt><span class="section"><a href="#users-guide-mtom-and-swaref">7. MTOM and Swaref</a></span></dt><dd><dl><dt><span class="section"><a href="#mtom-and-xop">7.1. MTOM and XOP</a></span></dt><dt><span class="section"><a href="#mtom-in-jaxws-2-0">7.2. MTOM in JAX-WS 2.0</a></span></dt><dt><span class="section"><a href="#swaref">7.3. swaRef</a></span></dt></dl></dd><dt><span class="section"><a href="#users-guide-soap-1-2">8. SOAP 1.2</a></span></dt><dd><dl><dt><span class="section"><a href="#section-94073181229507">8.1. Introduction</a></span></dt><dt><span class="section"><a href="#section-627071591090577">8.2. SOAP 1.2 Endpoint</a></span></dt><dt><span class="section"><a href="#section-696486497021005">8.3. Client</a></span></dt><dt><span class="section"><a href="#section-7037754311590527">8.4. Samples</a></span></dt></dl></dd><dt><span class="section"><a href="#users-guide-wsdl-customization">9. WSDL Customization</a></span></dt><dd><dl><dt><span class="section"><a href="#declaring-customizations">9.1. Declaring Customizations</a></span></dt><dt><span class="section"><a href="#standard-customizations">9.2. Standard Customizations</a></span></dt></dl></dd><dt><span class="section"><a href="#users-guide-annotations">10. Annotations</a></span></dt><dd><dl><dt><span class="section"><a href="#section-031540603185018">10.1. Overview</a></span></dt><dt><span class="section"><a href="#jsr-181">10.2. JSR 181 (Web Services Metadata) Annotations</a></span></dt><dt><span class="section"><a href="#jsr-224-jax-ws-annotations-outline">10.3. JSR 224 (JAX-WS) Annotations</a></span></dt><dt><span class="section"><a href="#jsr-222-jaxb-annotations-outline">10.4. JSR 222 (JAXB) Annotations</a></span></dt><dt><span class="section"><a href="#jsr-250-common-annotations">10.5. JSR 250 (Common Annotations) Annotations</a></span></dt></dl></dd><dt><span class="section"><a href="#users-guide-why-ws-addressing">11. Why WS-Addressing?</a></span></dt><dd><dl><dt><span class="section"><a href="#what-is-ws-addressing">11.1. What is WS-Addressing?</a></span></dt><dt><span class="section"><a href="#ws-addressing-versions">11.2. WS-Addressing Versions</a></span></dt></dl></dd><dt><span class="section"><a href="#users-guide-ws-addressing">12. WS-Addressing</a></span></dt><dd><dl><dt><span class="section"><a href="#ws-addressing-in">12.1. WS-Addressing in JAX-WS RI</a></span></dt><dt><span class="section"><a href="#why-ws-addressing">12.2. Why WS-Addressing?</a></span></dt><dt><span class="section"><a href="#describing-ws-addressing-in-wsdl">12.3. Describing WS-Addressing in WSDL</a></span></dt><dt><span class="section"><a href="#configuring-addressing-on-endpoint">12.4. Configuring Addressing on Endpoint</a></span></dt><dt><span class="section"><a href="#on-the-client-side">12.5. On the client side</a></span></dt><dt><span class="section"><a href="#when-is-ws-addressing-engaged">12.6. When is WS-Addressing engaged?</a></span></dt><dt><span class="section"><a href="#associating-action-with-an-operation">12.7. Associating Action with an operation</a></span></dt></dl></dd><dt><span class="section"><a href="#users-guide-stateful-webservice">13. Stateful Webservice</a></span></dt><dd><dl><dt><span class="section"><a href="#introduction-1">13.1. Introduction</a></span></dt><dt><span class="section"><a href="#usage">13.2. Usage</a></span></dt><dt><span class="section"><a href="#things-to-consider">13.3. Things To Consider</a></span></dt></dl></dd><dt><span class="section"><a href="#users-guide-catalog">14. Catalog</a></span></dt><dd><dl><dt><span class="section"><a href="#section-529979392543239">14.1. Catalog Support</a></span></dt></dl></dd><dt><span class="section"><a href="#users-guide-war-file-packaging">15. WAR File Packaging</a></span></dt><dd><dl><dt><span class="section"><a href="#section-5694250262578">15.1. The WAR Contents</a></span></dt><dt><span class="section"><a href="#the-sun-jaxws-xml-file">15.2. The <code class="literal">sun-jaxws.xml</code> File</a></span></dt><dt><span class="section"><a href="#section-42577169574826">15.3. The <code class="literal">web.xml</code> File</a></span></dt></dl></dd><dt><span class="section"><a href="#users-guide-interoperability">16. Interoperability</a></span></dt><dd><dl><dt><span class="section"><a href="#section-4101350549640481">16.1. WSDL and Message Level Interoperability</a></span></dt><dt><span class="section"><a href="#section-325661411410258">16.2. .NET 3.5 Interoperability</a></span></dt></dl></dd><dt><span class="section"><a href="#users-guide-endpoint-api">17. Endpoint API</a></span></dt><dd><dl><dt><span class="section"><a href="#section-0499646435494807">17.1. <code class="literal">Endpoint</code></a></span></dt><dt><span class="section"><a href="#section-2491869058427427">17.2. <code class="literal">Endpoint</code> and <code class="literal">Properties</code></a></span></dt><dt><span class="section"><a href="#section-9038221558727715">17.3. <code class="literal">Endpoint</code> and <code class="literal">Binding</code></a></span></dt><dt><span class="section"><a href="#section-091994350952741">17.4. <code class="literal">Endpoint</code> and <code class="literal">metadata</code></a></span></dt></dl></dd></dl></div><div lang="en" class="section" title="1. Overview"><div class="titlepage"><div><div><h2 class="title" style="clear: both" id="users-guide-overview">1. Overview</h2></div></div></div><div class="section" title="1.1. Introduction"><div class="titlepage"><div><div><h3 class="title" id="introduction">1.1. Introduction</h3></div></div></div><p>This document describes the new features available in this release of the JAX-WS RI. The main focus of this document is to describe the tools used to develop JAX-WS RI 2.2.7 web service endpoints and clients. Readers of this document should be familiar with web services <a class="link" href="http://www.w3.org/TR/2000/REC-xml-20001006" target="_top">XML</a>, <a class="link" href="http://www.w3.org/TR/2001/REC-xmlschema-1-20010502/" target="_top">XML Schema</a> and <a class="link" href="http://www.w3.org/TR/2001/NOTE-wsdl-20010315" target="_top">WSDL</a>. Familiarity with <a class="link" href="http://jcp.org/en/jsr/detail?id=101" target="_top">JAX-RPC 1.1</a> may also be beneficial but is not necessary.</p><p>The documentation/samples discusses how to use JAX-WS in a non-Java EE 5 servlet container using a proprietary deployment descriptor <code class="literal">sun-jaxws.xml</code> and servlet <code class="literal">com.sun.xml.ws.transport.http.servlet.WSServlet</code>. This means that you can run JAX-WS RI applications in any servlet container that has been enabled with the JAX-WS RI. Applications that use the proprietary DD and servlet will run in a JAX-WS RI enabled Java EE 5 servlet container, but they will be non-portable. If you wish to use JAX-WS in a Java EE container in a Java EE portable manner you need to use the standard Java EE 5 deployment descriptor; please refer to the <a class="link" href="http://java.sun.com/javaee/index.jsp" target="_top">Java EE 5</a> or <a class="link" href="http://glassfish.java.net/" target="_top">Glassfish</a> documentation/samples. The majority of the documentation included with JAX-WS is valid with Java EE 5 as well.</p></div><div class="section" title="1.2. Features"><div class="titlepage"><div><div><h3 class="title" id="features">1.2. Features</h3></div></div></div><div class="section" title="1.2.1. JAX-WS 2.2 API"><div class="titlepage"><div><div><h4 class="title" id="jax-ws-api">1.2.1. JAX-WS 2.2 API</h4></div></div></div><p>JAX-WS 2.2 is a Maintainence Release of JAXWS 2.0 API.</p><p>JAX-WS 2.2 has the following new features from JAX-WS 2.1 specification:</p><div class="itemizedlist"><ul class="itemizedlist" type="disc"><li class="listitem"><p>Support for JAXB 2.2 APIs (JSR 222)</p></li><li class="listitem"><p>Support for WS-Addressing 1.0 - Metadata specification</p></li><li class="listitem"><p>Support for <code class="literal">@XmlElement</code> on SEI's wrapper parameter</p></li><li class="listitem"><p>Support for <code class="literal">@XmlType</code> on exception classes</p></li><li class="listitem"><p>HTTP SPI</p></li><li class="listitem"><p>Provide API to create Endpoint with features</p></li></ul></div><p>JAX-WS 2.1 has the following new features from JAX-WS 2.0 specification:</p><div class="itemizedlist"><ul class="itemizedlist" type="disc"><li class="listitem"><p>WS-Addressing support</p></li><li class="listitem"><p>APIs for EndpointReference </p><div class="itemizedlist"><ul class="itemizedlist" type="circle"><li class="listitem"><p>Creation </p><div class="itemizedlist"><ul class="itemizedlist" type="square"><li class="listitem"><p><code class="literal">BindingProvider.getEndpointReference()</code></p></li><li class="listitem"><p><code class="literal">Endpoint.getEndpointReference()</code></p></li><li class="listitem"><p><code class="literal">MessageContext.getEndpointReference()</code></p></li></ul></div></li><li class="listitem"><p>EPR Propagation </p><div class="itemizedlist"><ul class="itemizedlist" type="square"><li class="listitem"><p>Using JAXB 2.1 bind W3C EPR to <code class="literal">W3CEndpointReference</code> class</p></li><li class="listitem"><p>Marshall/Unmarshall <code class="literal">W3CEndpointReference</code> class using JAXB</p></li></ul></div></li></ul></div></li><li class="listitem"><p>User friendly APIs to enable/disable features, such as MTOM and Addressing</p></li></ul></div><p>JAX-RPC users should note that JAX-WS is a completely different technology than JAX-RPC and thus cannot run JAX-RPC applications on top of JAX-WS. If you have an existing JAX-RPC application it must be converted to work with JAX-WS.</p></div><div class="section" title="1.2.2. Fully Dynamic Runtime"><div class="titlepage"><div><div><h4 class="title" id="fully-dynamic-runtime">1.2.2. Fully Dynamic Runtime</h4></div></div></div><p>In JAX-WS, all artifacts generated by <span class="command"><strong>apt</strong></span>, <span class="command"><strong>wsimport</strong></span> and <span class="command"><strong>wsgen</strong></span> are portable. JAX-WS uses the annotations within the SEI to aid in marshalling/unmarshalling messages. Because we no longer generated non-portable artifacts, we were able to get rid of tools like JAX-RPC's <span class="command"><strong>wsdeploy</strong></span>. The user now can create their own deployable WAR file. To learn more about creating a WAR file and the deployment descriptor, see <a class="xref" href="#users-guide-war-file-packaging" title="15. WAR File Packaging">WAR File Packaging</a>. It should also be noted that JAX-RPC's <span class="command"><strong>wscompile</strong></span> tool has been replaced by two new tools: <span class="command"><strong>wsimport</strong></span> and <span class="command"><strong>wsgen</strong></span>. <span class="command"><strong>wsimport</strong></span> is used for importing WSDLs and generating the portable artifacts. <span class="command"><strong>wsgen</strong></span> processes a compiled SEI and generates the portable artifacts. Unlike JAX-RPC's <span class="command"><strong>wscompile</strong></span> JAX-WS's <span class="command"><strong>wsgen</strong></span> does not generate WSDL at tool-time, the WSDL is now generated when the endpoint is deployed. There however is an option on <span class="command"><strong>wsgen</strong></span> to generate the WSDL for developement purposes.</p></div><div class="section" title="1.2.3. MTOM & swaRef"><div class="titlepage"><div><div><h4 class="title" id="mtom-amp-swaref">1.2.3. MTOM & swaRef</h4></div></div></div><p>MTOM and swaRef support was added in JAX-WS 2.0 RI FCS release. MTOM and swaref support is required by the JAX-WS 2.0 specification. This means that the MTOM or swaref solution developed with JAX-WS RI will be fully portable with any JAX-WS 2.0 compliant implementation.</p><p>MTOM implementation was completely re-written to allow streaming attachment support and just like rest of the JAX-WS RI runtime its written for better performance. This implementation was released as part of JAX-WS 2.0.1 M1 release.</p><p>JAX-WS 2.2 brings in support for optimized transmission of binary data as specified by <a class="link" href="http://www.w3.org/TR/soap12-mtom/" target="_top">MTOM</a> (SOAP Message Transmission Optimization Mechanism)/ <a class="link" href="http://www.w3.org/TR/xop10/" target="_top">XOP</a> (XML Binary Optimized Packaing) and <a class="link" href="http://www.ws-i.org/Profiles/AttachmentsProfile-1.0-2004-08-24.html#Referencing_Attachments_from_the_SOAP_Envelope" target="_top">swaRef</a> (SOAP Attachment References specified by WS-I Attachment Profile 1.0).</p><div class="itemizedlist"><ul class="itemizedlist" type="disc"><li class="listitem"><p>MTOM allows optimized transmission of binary data - any <code class="literal">xs:base64Binary</code> or <code class="literal">xs:hexBinary</code> schema type can be send as attachment following rules defined by XOP encoding and MTOM specification.</p></li></ul></div><div class="itemizedlist"><ul class="itemizedlist" type="disc"><li class="listitem"><p>In swaRef, an XML element of <a class="link" href="http://ws-i.org/profiles/basic/1.1/xsd/" target="_top"><code class="literal">wsi:swaRef</code></a> type (defined by WS-I Attachment Profile 1.0) is send as attachment and a referenced based on CID URL schema is put in place of the content of the element.</p></li></ul></div><p>For details on MTOM and swaRef features refer to <a class="xref" href="#users-guide-mtom-and-swaref" title="7. MTOM and Swaref">MTOM and Swaref</a>.</p></div><div class="section" title="1.2.4. SOAP 1.2"><div class="titlepage"><div><div><h4 class="title" id="soap-1-2">1.2.4. SOAP 1.2</h4></div></div></div><p>SOAP 1.2 support is added to JAX-WS 2.2. For details refer to <a class="xref" href="#users-guide-soap-1-2" title="8. SOAP 1.2">SOAP 1.2</a>.</p></div><div class="section" title="1.2.5. XML/HTTP Binding"><div class="titlepage"><div><div><h4 class="title" id="xml-http-binding">1.2.5. XML/HTTP Binding</h4></div></div></div><p>Support for XML/HTTP binding is added to JAX-WS 2.0. One can directly send XML over HTTP using <a class="xref" href="#users-guide-provider" title="2. Provider">Provider</a> and <a class="xref" href="#users-guide-dispatch" title="4. Dispatch">Dispatch</a> implementations. This enables support for REST style Web Services in JAX-WS. For details refer to restful sample.</p></div><div class="section" title="1.2.6. JAXB 2.2"><div class="titlepage"><div><div><h4 class="title" id="jaxb-2-0">1.2.6. JAXB 2.2</h4></div></div></div><p>JAX-WS RI 2.2.7 uses JAXB 2.2 for data-binding between Java and XML which enables features such as separate compilation, type substitution and other improvements.</p><div class="section" title="1.2.6.1. Type Substitution using @XmlSeeAlso"><div class="titlepage"><div><div><h5 class="title" id="type-substitution">1.2.6.1. Type Substitution using <code class="literal">@XmlSeeAlso</code></h5></div></div></div><p>JAXB 2.1 defines <code class="literal">@XmlSeeAlso</code> annotation which can be used to tell JAXB to use the classes mentioned with this annotation. This allows type substitution to takes place. See the <a class="link" href="../samples/type_substitution/src/type_substitution/server/CarDealer.java" target="_top">sample</a> that demonstrates it.</p><p><span class="command"><strong>wsimport</strong></span> tool, generates <code class="literal">@XmlSeeAlso</code> with all the classes that are not directly referenced by the WSDL operations. To capture all such classes <span class="command"><strong>wsimport</strong></span> generates <code class="literal">@XmlSeeAlso(ObjectFactory.class)</code> on the generated Service Endpoint Interface.</p></div><div class="section" title="1.2.6.2. @XmlElement on web service SEI parameters"><div class="titlepage"><div><div><h5 class="title" id="xmlelement-on-sei-parameters">1.2.6.2. <code class="literal">@XmlElement</code> on web service SEI parameters</h5></div></div></div><p>JAX-WS 2.2 spec allows <code class="literal">@XmlElement</code> on web service SEI parameters, which enables better control of XML representation. For this support, JAX-WS relies on JAXB 2.2 API which allows the <code class="literal">@XmlElement</code> annotation on parameters.</p></div></div><div class="section" title="1.2.7. WS-Addressing"><div class="titlepage"><div><div><h4 class="title" id="ws-addressing">1.2.7. WS-Addressing</h4></div></div></div><p>JAX-WS RI 2.2.7 supports for W3C <a class="link" href="http://www.w3.org/TR/ws-addr-core" target="_top">Core</a>, <a class="link" href="http://www.w3.org/TR/ws-addr-soap" target="_top">SOAP Binding</a> and <a class="link" href="http://www.w3.org/TR/2007/REC-ws-addr-metadata-20070904" target="_top">Addressing 1.0 - Metadata</a> specifications and defines standard API and annotations to enable/disable W3C WS-Addressing on the client and service endpoint. In addition to that, JAX-WS RI also supports <a class="link" href="http://www.w3.org/Submission/ws-addressing/" target="_top">Member Submission</a> version of WS-Addressing. The member submission version is supported in an implementation specific way. For compatility with JAX-WS 2.1 behavior, JAX-WS RI 2.2 also supports wsdls conforming to <a class="link" href="http://www.w3.org/TR/ws-addr-wsdl" target="_top">WSDL Binding</a> specification.</p><p>Refer to <a class="xref" href="#users-guide-ws-addressing" title="12. WS-Addressing">WS-Addressing</a> for more details. See WS-Addressing samples <span class="bold"><strong>fromjava-wsaddressing</strong></span>, <span class="bold"><strong>fromwsdl-wsaddressing-policy</strong></span> and <span class="bold"><strong>fromwsdl-wsaddressing</strong></span> with the JAX-WS RI 2.2.7 for details on the WS-Addressing programming model.</p></div><div class="section" title="1.2.8. Annotations"><div class="titlepage"><div><div><h4 class="title" id="annotations">1.2.8. Annotations</h4></div></div></div><p>JAX-WS 2.2 relies heavily on the use of annotations as provided by <span class="emphasis"><em>A Metadata Facility for the Java Programming Language</em></span> <a class="link" href="http://jcp.org/en/jsr/detail?id=175" target="_top">(JSR 175)</a> and and <span class="emphasis"><em>Web Services Metadata for the Java Platform</em></span> <a class="link" href="http://jcp.org/en/jsr/detail?id=181." target="_top">(JSR 181)</a> as well as additional annotations defined by JAX-WS 2.2. These annotations are used to customize the mapping from Java to XML schema/WSDL and are used at runtime to alleviate the need for non-portable serializers/deserializers that were generated in JAX-RPC 1.x.</p><p>The JAX-WS RI utilizes an <span class="command"><strong>apt</strong></span> (annotation processing tool) that was introduced in J2SDK 5.0. <span class="command"><strong>apt</strong></span> allows the SI to process Java source files directly to generate the portable artifacts specified by the JAX-WS 2.0 specification. <span class="command"><strong>apt</strong></span> will be covered in more detail in section <a class="xref" href="#tools-apt" title="6. apt">6</a>.</p><p>For more information on the annotations used by JAX-WS 2.0 please refer to <a class="xref" href="#users-guide-annotations" title="10. Annotations">Annotations</a>.</p></div><div class="section" title="1.2.9. Customizations"><div class="titlepage"><div><div><h4 class="title" id="customizations">1.2.9. Customizations</h4></div></div></div><p>JAX-WS RI 2.2.7 carries forward customization support introduced in JAX-WS 2.0 RI.</p><div class="itemizedlist"><ul class="itemizedlist" type="disc"><li class="listitem"><p>Define a package where Java artifacts mapped from a WSDL file will be generated</p></li><li class="listitem"><p>Package customization for value classes mapped from the imported XML schemas by the WSDL document</p></li><li class="listitem"><p>Handler chain customization</p></li></ul></div><p>JAX-WS 2.0 specification defines standard XML based customization for a WSDL file to Java mapping and to control certain features. These customizations, or <span class="emphasis"><em>binding declarations,</em></span> can customize almost all WSDL components that can be mapped to Java, such as the service endpoint interface class, method name, parameter name, exception class, etc. The other important thing you can do with these binding declarations is to control certain features, such as asynchrony, provider, wrapper style, and additional headers. For example, a client application can enable asynchrony for a particular operation in a portType, all operations in a <code class="literal">portType</code>, or all <code class="literal">portType</code> operations defined in the WSDL file.</p><p>These binding declarations can be inlined in a WSDL file or can live outside as an external file. The binding declarations closely align with the JAXB binding declarations. An application importing a WSDL file can inline JAXB bindings inside JAX-WS binding declarations to customize the inlined schema declared in the WSDL file. Schema files that are imported from a WSDL file can be customized using JAXB binding files and can be passed to <span class="command"><strong>wscompile</strong></span> using the <code class="option">-b</code> option switch.</p><p>These are the main customization features:</p><div class="itemizedlist"><ul class="itemizedlist" type="disc"><li class="listitem"><p>Scoped binding declarations. An XPath expression is used to specify the target node of the WSDL file on which customization should be applied.</p></li><li class="listitem"><p>Close alignment with JAXB bindings. JAXB binding declarations can be inlined in an external JAX-WS binding file.</p></li><li class="listitem"><p>Feature Control. Features such as asynchrony, wrapper style, additional header mapping, and provider interfaces can be enabled or disabled.</p></li><li class="listitem"><p>Handler chain customization (not yet specified by the 2.0 specification)</p></li></ul></div><p>The following WSDL component's mapped Java names can be modified:</p><div class="itemizedlist"><ul class="itemizedlist" type="disc"><li class="listitem"><p>generated service endpoint interface class</p></li><li class="listitem"><p>method</p></li><li class="listitem"><p>method parameter</p></li><li class="listitem"><p>generated exception class (for WSDL fault and header fault exceptions)</p></li><li class="listitem"><p>header parameter</p></li><li class="listitem"><p>generated service class</p></li><li class="listitem"><p>port accessor methods in the generated service class</p></li></ul></div><p>XML Schema Java mapping can be customized using standard JAXB customizations.</p><p>For more information on the customizations used by JAX-WS 2.0 please refer to <a class="xref" href="#users-guide-wsdl-customization" title="9. WSDL Customization">WSDL Customization</a>.</p></div><div class="section" title="1.2.10. Improved Handler Framework"><div class="titlepage"><div><div><h4 class="title" id="improved-handler-framework">1.2.10. Improved Handler Framework</h4></div></div></div><p>JAX-WS 2.0 specification defines two types of handlers: logical and protocol handlers. While protocol handlers have access to an entire message such as a SOAP message, logical handlers deal only with the payload of a message and are independent of the protocol being used. Handler chains can now be configured on a per-port, per-protocol, or per-service basis. A new framework of context objects has been added to allow client code to share information easily with handlers.</p><p>For more information on the handler framework in JAX-WS RI 2.2.7 please refer to <a class="xref" href="#users-guide-handler" title="6. Handler">Handler</a>.</p></div><div class="section" title="1.2.11. Provider"><div class="titlepage"><div><div><h4 class="title" id="provider">1.2.11. Provider</h4></div></div></div><p>Web service endpoints may choose to work at the XML message level by implementing the <code class="literal">Provider</code> interface. Here the endpoints access messages or message payloads using this low level, generic API.</p><p>For more information on providers in JAX-WS RI 2.2.7 please refer to <a class="xref" href="#users-guide-provider" title="2. Provider">Provider</a>.</p></div><div class="section" title="1.2.12. Dispatch"><div class="titlepage"><div><div><h4 class="title" id="dispatch">1.2.12. Dispatch</h4></div></div></div><p>The Dispatch API is intended for advanced XML developers who prefer to use XML constructs at the <code class="literal">java.lang.transform.Source</code> or <code class="literal">javax.xml.soap.SOAPMessage</code> level. For added convenience use of the <code class="literal">Dispatch</code> API with JAXB data-bound objects is supported. The <code class="literal">Dispatch</code> API can be used in both <code class="literal">Message</code> and <code class="literal">Payload</code> modes.</p><p>For more information on the <code class="literal">Dispatch</code> please refer to <a class="xref" href="#users-guide-dispatch" title="4. Dispatch">Dispatch</a>.</p></div><div class="section" title="1.2.13. Asynchronous Client Operations"><div class="titlepage"><div><div><h4 class="title" id="asynchronous-client-operations">1.2.13. Asynchronous Client Operations</h4></div></div></div><p>For more information on asynchronous clients in JAX-WS RI 2.2.7 please refer to <a class="xref" href="#users-guide-asynchronous-client" title="5. Asynchronous Client">Asynchronous Client</a>.</p></div></div><div class="section" title="1.3. Programming Model"><div class="titlepage"><div><div><h3 class="title" id="programming-model">1.3. Programming Model</h3></div></div></div><p>This section of the documentation will focus on the programming model for both developing and publishing a web service endpoint, and writing a web service client. A web service endpoint is the implementation of a web service. A web service client is an application that accesses a web service.</p><div class="section" title="1.3.1. Server"><div class="titlepage"><div><div><h4 class="title" id="server">1.3.1. Server</h4></div></div></div><p>When developing a web service endpoint, a developer may either start from a Java endpoint implementation class or from a WSDL file. A WSDL (Web Services Description Language) document describes the contract between the web service endpoint and the client. A WSDL document may include and/or import XML schema files used to describe the data types used by the web service. When starting from a Java class, the tools generate any portable artifacts as mandated by the spec. When starting from a WSDL file and schemas, the tools generate a service endpoint interface.</p><p>There is a trade-off when starting from a Java class or from a WSDL file. If you start from a Java class, you can make sure that the endpoint implementation class has the desirable Java data types, but the developer has less control of the generated XML schema. When starting from a WSDL file and schema, the developer has total control over what XML schema is used, but has less control over what the generated service endpoint and the classes it uses will contain.</p><div class="section" title="1.3.1.1. Starting from Java"><div class="titlepage"><div><div><h5 class="title" id="starting-from-java">1.3.1.1. Starting from Java</h5></div></div></div><p>The basic process for deploying a web service from a Java class consists of two steps.</p><div class="orderedlist"><ol class="orderedlist" type="1"><li class="listitem"><p>Generate portable artifacts.</p></li><li class="listitem"><p>Create a WAR file to deploy</p></li></ol></div></div><div class="section" title="1.3.1.2. Generate Portable Artifacts"><div class="titlepage"><div><div><h5 class="title" id="generate-portable-artifacts">1.3.1.2. Generate Portable Artifacts</h5></div></div></div><p>Portable artifacts generated by JAX-WS RI 2.2.7 include zero or more JavaBean classes to aide in the marshaling of method invocations and responses, as well as service-specific exceptions.</p><p>In document/literal wrapped mode, two JavaBeans are generated for each operation in the web service. One bean is for invoking the other for the response. In all modes (rpc/literal and both document/literal modes), one JavaBean is generated for each service-specific exception.</p><p>When starting from Java the developer must provide the JAX-WS tools with a valid endpoint implementation class. This implementation class is the class that implements the desired web service. JAX-WS has a number of restrictions on endpoint implementation classes. A valid endpoint implementation class must meet the following requirements:</p><div class="itemizedlist"><ul class="itemizedlist" type="disc"><li class="listitem"><p>It <span class="emphasis"><em>must</em></span> carry a javax.jws.WebService annotation (see JSR 181).</p></li><li class="listitem"><p>Any of its methods <span class="emphasis"><em>may</em></span> carry a javax.jws.WebMethod annotation (see 7.5.2).</p></li><li class="listitem"><p>All of its methods <span class="emphasis"><em>may</em></span> throw java.rmi.RemoteException in addition to any service-specific exceptions.</p></li><li class="listitem"><p>All method parameters and return types <span class="emphasis"><em>must</em></span> be compatible with the JAXB 2.0 Java to XML Schema mapping definition.</p></li><li class="listitem"><p>A method parameter or return value type <span class="emphasis"><em>must not</em></span> implement the java.rmi.Remote interface either directly or indirectly.</p></li></ul></div><p>Here is an example of a a simple endpoint implementation class <code class="code"> <a class="link" href="../samples/fromjava/src/fromjava/server/AddNumbersImpl.java" target="_top">AddNumbersImpl.java</a> </code> from the <span class="application">fromjava</span> sample:</p><div class="informalexample"><pre class="programlisting"><span class="ReservedWord">package</span> fromjava.server; <span class="ReservedWord">import</span> javax.jws.WebService; <span class="Annotation">@WebService</span> <span class="ReservedWord">public</span> <span class="ReservedWord">class</span> AddNumbersImpl { <span class="Comment">/** * @param number1 * @param number2 * @return The sum * @throws AddNumbersException if any of the numbers to be added is * negative. */</span> <span class="ReservedWord">public</span> <span class="ReservedWord">int</span> addNumbers(<span class="ReservedWord">int</span> number1, <span class="ReservedWord">int</span> number2) <span class="ReservedWord">throws</span> AddNumbersException { <span class="ReservedWord">if</span> (number1 < <span class="Numeric">0</span> || number2 < <span class="Numeric">0</span>) { <span class="ReservedWord">throw</span> <span class="ReservedWord">new</span> AddNumbersException(<span class="String">"Negative number cant be "</span> + <span class="String">"added!"</span>, <span class="String">"Numbers: "</span> + number1 + <span class="String">", "</span> + number2); } <span class="ReservedWord">return</span> number1 + number2; } }</pre></div><p>If you are familiar with JAX-RPC 1.1, you will notice that this implementation class does not implement a service endpoint interface. In JAX-WS RI 2.2.7 a service endpoint interface is no longer required.</p><p>When starting from a Java endpoint implementation class, it is recommended that the portable artifacts be generated from source using <span class="command"><strong>apt</strong></span>. This because the JAX-WS tools will then have full access to the source code and will be able to utilize parameter names that are otherwise not available through the Java reflection APIs. If the source for the endpoint implementation class is not available, the portable artifacts can be generated using <span class="command"><strong>wscompile</strong></span>. Here is a sample <span class="command"><strong>apt</strong></span> Ant task from the samples:</p><div class="informalexample"><pre class="programlisting"><span class="ReservedWord"><apt</span> <span class="Identifier">debug</span>=<span class="String">"${debug}"</span> <span class="Identifier">verbose</span>=<span class="String">"${verbose}"</span> <span class="Identifier">destdir</span>=<span class="String">"${build.classes.home}"</span> <span class="Identifier">sourcedestdir</span>=<span class="String">"${build.classes.home}"</span> <span class="Identifier">sourcepath</span>=<span class="String">"${basedir}/src"</span><span class="ReservedWord">></span> <span class="ReservedWord"><classpath</span> <span class="Identifier">refid</span>=<span class="String">"jax-ws.classpath"</span><span class="ReservedWord">/></span> <span class="ReservedWord"><option</span> <span class="Identifier">key</span>=<span class="String">"r"</span> <span class="Identifier">value</span>=<span class="String">"${build.home}"</span><span class="ReservedWord">/></span> <span class="ReservedWord"><source</span> <span class="Identifier">dir</span>=<span class="String">"${basedir}/src"</span><span class="ReservedWord">></span> <span class="ReservedWord"><include</span> <span class="Identifier">name</span>=<span class="String">"**/server/*.java"</span><span class="ReservedWord">/></span> <span class="ReservedWord"></source></span> <span class="ReservedWord"></apt></span></pre></div><p>More information about the <span class="command"><strong>apt</strong></span> Ant task can be found <a class="xref" href="#tools-apt" title="6. apt"><span class="command"><strong>apt</strong></span></a>. If this task is run on the fromjava sample, the output would include:</p><div class="informalexample"><pre class="programlisting">AddNumbers.class AddNumbers.java AddNumbersExceptionBean.class AddNumbersExceptionBean.java AddNumbersResponse.class AddNumbersResponse.java</pre></div><p>The <code class="filename">AddNumbersImplService.wsdl</code> file describes the web service. The <code class="filename">schema1.xsd</code> file is imported by the <code class="filename">AddNumbersImplService.wsdl</code> and contains the datatypes used by the web service. The <code class="filename">AddNumbers.class</code>/<code class="filename">AddNumbers.java</code> files contain the a bean used by a JAXB to marshall/unmarshall the <code class="literal">addNumbers</code> request. The <code class="filename">AddNumbersExceptionBean.class</code>/<code class="filename">AddNumbersExceptionBean.java</code> file is a bean used by JAXB to marshall the contents of the <code class="literal">AddNumbersException</code> class. The <code class="filename">AddNumbersResponse.class</code>/<code class="filename">AddNumbersResponse.java</code> files represent the response bean used by JAXB to marshall/unmarshall the <code class="literal">addNumbers</code> response.</p></div><div class="section" title="1.3.1.3. Create a WAR file to deploy"><div class="titlepage"><div><div><h5 class="title" id="create-a-war-file-to-deploy">1.3.1.3. Create a WAR file to deploy</h5></div></div></div><p>Creating a WAR file is nothing more than packaging the service endpoint interface (if there is one), service endpoint implementation, Java classes used by the endpoint implementation and a deployment descriptor in WAR format. For the fromjava sample the <code class="literal">AddNumbersImpl</code> and <code class="literal">AddNumbersException</code> classes in the <span class="package">fromjava.server</span> package, and the deployment descriptor are bundled together to make a raw WAR file. To learn more about creating a WAR file and the deployment descriptor, see <a class="xref" href="#users-guide-war-file-packaging" title="15. WAR File Packaging">WAR File Packaging</a>. The deployment descriptor used in <span class="application">fromjava</span> sample is given below and can be found <a class="link" href="../samples/fromjava/etc/sun-jaxws.xml" target="_top">here</a>:</p><div class="informalexample"><pre class="programlisting"><span class="hl-directive" style="color: maroon"><?xml version="1.0" encoding="UTF-8"?></span> <span class="ReservedWord"><endpoints</span> <span class="Identifier">xmlns</span>=<span class="String">'http://java.sun.com/xml/ns/jax-ws/ri/runtime'</span> <span class="Identifier">version</span>=<span class="String">'2.0'</span><span class="ReservedWord">></span> <span class="ReservedWord"><endpoint</span> <span class="Identifier">name</span>=<span class="String">'fromjava'</span> <span class="Identifier">implementation</span>=<span class="String">'fromjava.server.AddNumbersImpl'</span> <span class="Identifier">url-pattern</span>=<span class="String">'/addnumbers'</span><span class="ReservedWord">/></span> <span class="ReservedWord"></endpoints></span></pre></div><p>The attributes of the <code class="literal"><endpoint></code> element are described below:</p><div class="itemizedlist"><ul class="itemizedlist" type="disc"><li class="listitem"><p>name is simply an identifier for this endpoint</p></li><li class="listitem"><p>implementation is used to specify the endpoint implementation class</p></li><li class="listitem"><p>urlpattern is used to URL pattern used to access this endpoint.</p></li></ul></div><p>The structure of the raw WAR file is shown below:</p><div class="informalexample"><pre class="programlisting">META-INF/MANIFEST.MF WEB-INF/sun-jaxws.xml WEB-INF/web.xml WEB-INF/classes/fromjava/server/AddNumbersException.class WEB-INF/classes/fromjava/server/AddNumbersImpl.class WEB-INF/classes/fromjava/server/jaxws/AddNumbers.class WEB-INF/classes/fromjava/server/jaxws/AddNumbersExceptionBean.class WEB-INF/classes/fromjava/server/jaxws/AddNumbersResponse.class</pre></div><p>The WAR file created can now be published on a JAX-WS RI enabled servlet container such as the <a class="link" href="http://java.sun.com/j2ee/1.4/download.html" target="_top">Sun Java System Application Server Platform Edition 8.2</a></p></div><div class="section" title="1.3.1.4. Starting from a WSDL File"><div class="titlepage"><div><div><h5 class="title" id="starting-from-a-wsdl-file">1.3.1.4. Starting from a WSDL File</h5></div></div></div><p>The basic process for deploying a web service when starting from a WSDL document consists of the following four steps:</p><div class="orderedlist"><ol class="orderedlist" type="1"><li class="listitem"><p>Generate a service endpoint interface.</p></li><li class="listitem"><p>Implement the service endpoint interface.</p></li><li class="listitem"><p>Create a WAR file to deploy.</p></li></ol></div></div><div class="section" title="1.3.1.5. Generate a Service Endpoint Interface"><div class="titlepage"><div><div><h5 class="title" id="generate-a-service-endpoint-interface">1.3.1.5. Generate a Service Endpoint Interface</h5></div></div></div><p>This step involves compiling or importing the WSDL file to generate a service endpoint interface and value classes mapped from imported XML schemas.</p><p>Below is a sample <span class="command"><strong>wsimport</strong></span> Ant target:</p><div class="informalexample"><pre class="programlisting"><span class="ReservedWord"><wsimport</span> <span class="Identifier">debug</span>=<span class="String">"${debug}"</span> <span class="Identifier">verbose</span>=<span class="String">"${verbose}"</span> <span class="Identifier">keep</span>=<span class="String">"${keep}"</span> <span class="Identifier">destdir</span>=<span class="String">"${build.classes.home}"</span> <span class="Identifier">wsdl</span>=<span class="String">"${server.wsdl}"</span><span class="ReservedWord">></span> <span class="ReservedWord"><binding</span> <span class="Identifier">dir</span>=<span class="String">"${basedir}/etc"</span> <span class="Identifier">includes</span>=<span class="String">"${server.binding}"</span><span class="ReservedWord">/></span> <span class="ReservedWord"></wsimport></span></pre></div><p>Its commandline equivalent is:</p><div class="informalexample"><pre class="programlisting">wsimport.sh etc/AddNumbers.wsdl -b custom-server.xml</pre></div><p>Lets look at the excerpt of <a class="link" href="../samples/fromwsdl/etc/AddNumbers.wsdl" target="_top">AddNumbers.wsdl</a> from the sample <span class="application">fromwsdl</span>:</p><p>The generated service endpoint interface looks as follows:</p><div class="informalexample"><pre class="programlisting"><span class="ReservedWord">package</span> fromwsdl.server; <span class="Annotation">@javax.jws.WebService( name = "AddNumbersPortType", serviceName = "AddNumbersService", targetNamespace = "http://duke.example.org")</span> <span class="Annotation">@javax.jws.soap.SOAPBinding( style = javax.jws.soap.SOAPBinding.Style.DOCUMENT, use = javax.jws.soap.SOAPBinding.Use.LITERAL, parameterStyle = javax.jws.soap.SOAPBinding.ParameterStyle.WRAPPED)</span> <span class="ReservedWord">public</span> <span class="ReservedWord">interface</span> AddNumbersPortType <span class="ReservedWord">extends</span> java.rmi.Remote { <span class="Annotation">@javax.jws.WebMethod(operationName = "addNumbers")</span> <span class="Annotation">@javax.jws.WebResult(name = "return")</span> <span class="ReservedWord">public</span> <span class="ReservedWord">int</span> addNumbers(<span class="Annotation">@javax.jws.WebParam(name = "arg0")</span> <span class="ReservedWord">int</span> arg0, <span class="Annotation">@javax.jws.WebParam(name = "arg1")</span> <span class="ReservedWord">int</span> arg1) <span class="ReservedWord">throws</span> fromwsdl.server.AddNumbersFault_Exception, java.rmi.RemoteException; }</pre></div><p>The generated service endpoint interface has annotations that can be used by the future versions of JAX-WS 2.0 to do dynamic binding and serialization/deserialization at runtime. Alternatively this service endpoint interface can be used to generate a WSDL and schema file. Please note that round-tripping is not guaranteed in this case. So the generated WSDL file and schema may not be the same as the one the service endpoint interface was generated from.</p></div><div class="section" title="1.3.1.6. Implement the Service Endpoint Interface"><div class="titlepage"><div><div><h5 class="title" id="implement-the-service-endpoint-interface">1.3.1.6. Implement the Service Endpoint Interface</h5></div></div></div><p>The next thing to do will be to provide the implementation of the service endpoint interface generated in the previous step. When you implement the service endpoint interface it is necessary to provide a <code class="literal">@WebService</code> annotation on the implementation class with a endpointInteface element specifying the qualified name of the endpoint interface class. Let's look at the implementation class <a class="link" href="../samples/fromwsdl/src/fromwsdl/server/AddNumbersImpl.java" target="_top">fromwsdl.server.AddNumbersImpl.java</a> from the sample application <span class="application">fromwsdl</span>:</p><div class="informalexample"><pre class="programlisting"><span class="ReservedWord">package</span> fromwsdl.server; <span class="Annotation">@WebService(endpointInterface = "fromwsdl.server.AddNumbersPortType")</span> <span class="ReservedWord">public</span> <span class="ReservedWord">class</span> AddNumbersImpl <span class="ReservedWord">implements</span> AddNumbersPortType { <span class="Comment">/** * @param number1 * @param number2 * @return The sum * @throws AddNumbersException if any of the numbers to be added is * negative. */</span> <span class="ReservedWord">public</span> <span class="ReservedWord">int</span> addNumbers(<span class="ReservedWord">int</span> number1, <span class="ReservedWord">int</span> number2) <span class="ReservedWord">throws</span> AddNumbersFault_Exception { ... } }</pre></div></div><div class="section" title="1.3.1.7. Create a WAR"><div class="titlepage"><div><div><h5 class="title" id="create-a-war">1.3.1.7. Create a WAR</h5></div></div></div><p>This step is similar to the one described above in <a class="xref" href="#create-a-war-file-to-deploy" title="1.3.1.3. Create a WAR file to deploy">Create a WAR file to deploy</a> .</p><p>Here the service endpoint interface implementation class from previous step, together with a deployment descriptor file sun-jaxws.xml, and <code class="filename">web.xml</code> should be bundled together with the service endpoint interface, value classes generated in the first step mentioned in <a class="xref" href="#generate-a-service-endpoint-interface" title="1.3.1.5. Generate a Service Endpoint Interface">Generate a Service Endpoint Interface</a>.</p><p>Let's look at <a class="link" href="../samples/fromwsdl/etc/sun-jaxws.xml" target="_top">sun-jaxws.xml</a> from the sample application <span class="application">fromwsdl</span>:</p><div class="informalexample"><pre class="programlisting"><span class="hl-directive" style="color: maroon"><?xml version="1.0" encoding="UTF-8"?></span> <span class="ReservedWord"><endpoints</span> <span class="Identifier">xmlns</span>=<span class="String">"http://java.sun.com/xml/ns/jax-ws/ri/runtime"</span> <span class="Identifier">version</span>=<span class="String">"2.0"</span><span class="ReservedWord">></span> <span class="ReservedWord"><endpoint</span> <span class="Identifier">name</span>=<span class="String">"fromwsdl"</span> <span class="Identifier">interface</span>=<span class="String">"fromwsdl.server.AddNumbersPortType"</span> <span class="Identifier">implementation</span>=<span class="String">"fromwsdl.server.AddNumbersImpl"</span> <span class="Identifier">wsdl</span>=<span class="String">"WEB-INF/wsdl/AddNumbers.wsdl"</span> <span class="Identifier">service</span>=<span class="String">"{http://duke.example.org}AddNumbersService"</span> <span class="Identifier">port</span>=<span class="String">"{http://duke.example.org}AddNumbersPort"</span> <span class="Identifier">url-pattern</span>=<span class="String">"/addnumbers"</span><span class="ReservedWord">/></span> <span class="ReservedWord"></endpoints></span></pre></div><p>It defines the deployment-related configuration information for the <span class="application">fromwsdl</span> endpoint. You will notice that this deployment descriptor contains additional attributes than the deployment descriptor described in <a class="xref" href="#create-a-war-file-to-deploy" title="1.3.1.3. Create a WAR file to deploy">Create a WAR file to deploy</a>. The interface attribute references the service endpoint interface generated in step 1. The wsdl attribute also points at the WSDL that was imported by <span class="command"><strong>wsimport</strong></span>. The service attribute references which service in the WSDL this endpoint is from and the port is the name of the port in that service for this endpoint.</p><p>To learn more about creating a WAR file and the deployment descriptor, see <a class="xref" href="#users-guide-war-file-packaging" title="15. WAR File Packaging">WAR File Packaging</a>.</p><p>The WAR file created can now be published on a JAX-WS RI enabled servlet container such as the <a class="link" href="http://java.sun.com/j2ee/1.4/download.html" target="_top">Sun Java System Application Server Platform Edition 8.2</a></p></div><div class="section" title="1.3.1.8. J2SE Endpoints"><div class="titlepage"><div><div><h5 class="title" id="j2se-endpoints">1.3.1.8. J2SE Endpoints</h5></div></div></div><p>Endpoints can be created and published programmatically using <code class="literal">javax.xml.ws.Endpoint</code> API in J2SE. To learn more about these endpoints, see <a class="xref" href="#users-guide-endpoint-api" title="17. Endpoint API">Endpoint API</a>.</p></div></div><div class="section" title="1.3.2. Client"><div class="titlepage"><div><div><h4 class="title" id="client">1.3.2. Client</h4></div></div></div><p>A client application can access a remote web service endpoint in one of two ways: port and dispatch.</p><div class="section" title="1.3.2.1. Dynamic Proxy"><div class="titlepage"><div><div><h5 class="title" id="dynamic-proxy">1.3.2.1. Dynamic Proxy</h5></div></div></div><p>In this approach client side invokes Web services via a dynamic proxy. The proxies for the Web Service are created from the generated Service and service endpoint interfaces. Once the proxies are created. the client application can invoke methods on those proxies just like a standard implementation of those interfaces. The sections below describe this process more detail.</p></div><div class="section" title="1.3.2.2. Generate Client Artifacts"><div class="titlepage"><div><div><h5 class="title" id="generate-client-artifacts">1.3.2.2. Generate Client Artifacts</h5></div></div></div><p>The <span class="command"><strong>wsimport</strong></span> tool is used to generate the service endpoint interface and the service interface classes. Below is the sample <span class="command"><strong>wsimport</strong></span> Ant target:</p><div class="informalexample"><pre class="programlisting"><span class="ReservedWord"><wsimport</span> <span class="Identifier">debug</span>=<span class="String">"${debug}"</span> <span class="Identifier">verbose</span>=<span class="String">"${verbose}"</span> <span class="Identifier">keep</span>=<span class="String">"${keep}"</span> <span class="Identifier">destdir</span>=<span class="String">"${build.classes.home}"</span> <span class="Identifier">wsdl</span>=<span class="String">"${client.wsdl}"</span><span class="ReservedWord">></span> <span class="ReservedWord"><classpath></span> <span class="ReservedWord"><path</span> <span class="Identifier">refid</span>=<span class="String">"jax-ws.classpath"</span><span class="ReservedWord">/></span> <span class="ReservedWord"><pathelement</span> <span class="Identifier">location</span>=<span class="String">"${build.classes.home}"</span><span class="ReservedWord">/></span> <span class="ReservedWord"></classpath></span> <span class="ReservedWord"><binding</span> <span class="Identifier">dir</span>=<span class="String">"${basedir}/etc"</span> <span class="Identifier">includes</span>=<span class="String">"${client.binding}"</span><span class="ReservedWord">/></span> <span class="ReservedWord"></wsimport></span></pre></div><p>The command line equivalent of this Ant target is:</p><div class="informalexample"><pre class="programlisting">wsimport.sh -classpath client_classpath -d dest_dir -s src_dir \ -b custom-client.xml http://localhost:8080/jax-ws-fromwsdl/addnumbers?WSDL</pre></div><p>For more details see the <a class="xref" href="#tools-wsimport" title="2. wsimport"><span class="command"><strong>wsimport</strong></span></a> documentation.</p><p>Here is the excerpt from <a class="link" href="../samples/fromwsdl/src/fromwsdl/client/AddNumbersClient.java" target="_top">fromwsdl.client.AddNumbersClient.java</a> in the <span class="application">fromjava</span> sample application:</p><div class="informalexample"><pre class="programlisting"><span class="Comment">//get the port</span> AddNumbersPortType port = <span class="ReservedWord">new</span> AddNumbersService().getAddNumbersPort(); <span class="Comment">//invoke the remote method</span> <span class="ReservedWord">int</span> result = port.addNumbers(<span class="Numeric">10</span>, <span class="Numeric">20</span>);</pre></div></div><div class="section" title="1.3.2.3. Dispatch"><div class="titlepage"><div><div><h5 class="title" id="dispatch-1">1.3.2.3. Dispatch</h5></div></div></div><p>The <code class="literal">Dispatch</code> API is intended for advanced XML developers who prefer using XML constructs at the <code class="literal">java.lang.transform.Source</code> or <code class="literal">javax.xml.soap.SOAPMessage</code> level. For added convenience use of <code class="literal">Dispatch</code> with JAXB data binding object is supported. With the <code class="literal">XML/HTTP</code> binding a <code class="literal">javax.activation.DataSource</code> can also be used. The <code class="literal">Dispatch</code> APIs can be used in both <code class="literal">Message</code> and <code class="literal">Payload</code> modes. The <code class="literal">Dispatch</code> API client with an <code class="literal">XML/HTTP</code> binding can be used with REST Web Services. Please see the restful sample program for more information.</p><p>For more information on <code class="literal">Dispatch</code> in JAX-WS RI 2.2.7 please refer to <a class="xref" href="#users-guide-dispatch" title="4. Dispatch">Dispatch</a>.</p></div></div></div><div class="section" title="1.4. Useful Information"><div class="titlepage"><div><div><h3 class="title" id="useful-information">1.4. Useful Information</h3></div></div></div><p><a class="link" href="http://docs.oracle.com/javase/6/docs/technotes/guides/apt/index.html" target="_top">Annotation Processing Tool (apt)</a> – http://docs.oracle.com/javase/6/docs/technotes/guides/apt/index.html.</p><p>Please use the <a class="link" href="http://forums.java.net/jive/forum.jspa?forumID=46&start=0" target="_top">JAXB and JAX-WS</a> forum for feedback.</p><p>The JAX-WS project on Java.net is: <a class="link" href="http://jax-ws.java.net/" target="_top">http://jax-ws.java.net</a>.</p></div></div><div lang="en" class="section" title="2. Provider"><div class="titlepage"><div><div><h2 class="title" style="clear: both" id="users-guide-provider">2. Provider</h2></div></div></div><p>Web Service endpoints may choose to work at the XML message level by implementing the <code class="literal">Provider</code> interface. This is achieved by implementing either <code class="literal">Provider<Source></code> or <code class="literal">Provider<SOAPMessage></code> or <code class="literal">Provider<DataSource></code>. The endpoint accesses the message or message payload using this low-level, generic API. All the Provider endpoints must have <code class="literal">@WebServiceProvider</code> annotation. The <code class="literal">@ServiceMode</code> annotation is used to convey whether the endpoint wants to access the message ( <code class="literal">Service.Mode.MESSAGE</code>) or payload ( <code class="literal">Service.Mode.PAYLOAD</code>). If there is no <code class="literal">@ServiceMode</code> annotation on the endpoint, payload is the default value. The endpoint communicates with handlers using <code class="literal">WebServiceContext resource like any other normal endpoint</code>. Provider endpoints can start from java or WSDL. When the provider endpoints start from a WSDL file, <code class="literal"><provider></code> WSDL customization can be used to mark a port as a provider.</p><div class="section" title="2.1. Provider<Source> and PAYLOAD"><div class="titlepage"><div><div><h3 class="title" id="section-3091238697838234">2.1. <code class="literal">Provider<Source></code> and <code class="literal">PAYLOAD</code></h3></div></div></div><p>An endpoint can access only the payload of a request using <code class="literal">Service.Mode.PAYLOAD</code> in the <code class="literal">@ServiceMode</code> annotation. This is the default behaviour, if the annotation is missing.</p><p>For example:</p><div class="informalexample"><pre class="programlisting"><span class="Annotation">@WebServiceProvider</span> <span class="ReservedWord">public</span> <span class="ReservedWord">class</span> ProviderImpl <span class="ReservedWord">implements</span> Provider<Source> { <span class="ReservedWord">public</span> Source invoke(Source source) { <span class="Comment">// do request processing Source</span> response = ...; <span class="ReservedWord">return</span> response; } }</pre></div></div><div class="section" title="2.2. Provider<SOAPMessage> and MESSAGE"><div class="titlepage"><div><div><h3 class="title" id="section-8519606736474974">2.2. <code class="literal">Provider<SOAPMessage></code> and <code class="literal">MESSAGE</code></h3></div></div></div><p>An endpoint can access an entire SOAP request as a <code class="literal">SOAPMessage</code>. <code class="literal">Service.Mode.MESSAGE</code> in the <code class="literal">@ServiceMode</code> annotation is used to convey the intent.</p><p>For example:</p><div class="informalexample"><pre class="programlisting"><span class="Annotation">@WebServiceProvider</span> <span class="Annotation">@ServiceMode(value = Service.Mode.MESSAGE)</span> <span class="ReservedWord">public</span> <span class="ReservedWord">class</span> ProviderImpl <span class="ReservedWord">implements</span> Provider<SOAPMessage> { <span class="ReservedWord">public</span> SOAPMessage invoke(SOAPMessage msg) { <span class="Comment">// do request processing</span> SOAPMessage response =...; <span class="ReservedWord">return</span> response; } }</pre></div></div><div class="section" title="2.3. Provider<Source> and MESSAGE"><div class="titlepage"><div><div><h3 class="title" id="section-7319353703410434">2.3. <code class="literal">Provider<Source></code> and <code class="literal">MESSAGE</code></h3></div></div></div><p>An endpoint can access a request as a <code class="literal">Source</code>. If the request is a <code class="literal">SOAPMessage</code>, only the <code class="literal">SOAPPart</code> (no attachments) of the message is passed as <code class="literal">Source</code> to the <code class="literal">invoke</code> method. If the returned response is null, it is considered a one way MEP.</p><p>For example:</p><div class="informalexample"><pre class="programlisting"><span class="Annotation">@ServiceMode(value = Service.Mode.MESSAGE)</span> <span class="ReservedWord">public</span> <span class="ReservedWord">class</span> ProviderImpl <span class="ReservedWord">implements</span> Provider<Source> { <span class="ReservedWord">public</span> Source invoke(Source source) { <span class="Comment">// do request processing</span> using source <span class="Comment">// return null to indicate oneway return null;</span> } }</pre></div></div><div class="section" title="2.4. WSDL Customization"><div class="titlepage"><div><div><h3 class="title" id="section-674124516240791">2.4. WSDL Customization</h3></div></div></div><p>If the provider endpoint starts with a WSDL file, a port can be customized to a provider endpoint using the <code class="literal"><provider></code> customization. <span class="command"><strong>wsimport</strong></span> won't generate any artifacts for that port.</p><p>For example:</p><div class="informalexample"><pre class="programlisting"><span class="hl-directive" style="color: maroon"><?xml version="1.0" encoding="UTF-8" standalone="yes"?></span> <span class="ReservedWord"><bindings</span> <span class="Identifier">...</span> <span class="Identifier">wsdlLocaption</span>=<span class="String">"AddNumbers.wsdl"</span><span class="Identifier">xmlns</span>=<span class="String">"http://java.sun.com/xml/ns/jaxws"</span><span class="ReservedWord">></span> <span class="ReservedWord"><bindings</span> <span class="Identifier">node</span>=<span class="String">"wsdl:definitions"</span><span class="ReservedWord">></span> <span class="ReservedWord"><package</span> <span class="Identifier">name</span>=<span class="String">"provider.server"</span><span class="ReservedWord">/></span> <span class="ReservedWord"><provider></span>true<span class="ReservedWord"></provider></span> <span class="ReservedWord"></bindings></span> <span class="ReservedWord"></bindings></span></pre></div></div><div class="section" title="2.5. The sun-jaxws.xml file"><div class="titlepage"><div><div><h3 class="title" id="section-648626808421419">2.5. The <code class="literal">sun-jaxws.xml</code> file</h3></div></div></div><p>The attributes of provider endpoint in sun-jaxws.xml: name, implementation, wsdl, service, port override the attributes provided through <code class="literal">@WebServiceProvider</code> annotation. For SOAP1.2 binding, one needs to specify binding attribute.</p><p>For example:</p><div class="informalexample"><pre class="programlisting"><span class="hl-directive" style="color: maroon"><?xml version="1.0" encoding="UTF-8"?></span> <span class="ReservedWord"><endpoints</span> <span class="Identifier">xmlns</span>=<span class="String">'http://java.sun.com/xml/ns/jax-ws/ri/runtime'</span> <span class="Identifier">version</span>=<span class="String">'2.0'</span><span class="ReservedWord">></span> <span class="ReservedWord"><endpoint</span> <span class="Identifier">name</span>=<span class="String">'AddNumbers'</span> <span class="Identifier">implementation</span>=<span class="String">'provider.server.AddNumbersImpl'</span> <span class="Identifier">wsdl</span>=<span class="String">'WEB-INF/wsdl/AddNumbers.wsdl'</span> <span class="Identifier">service</span>=<span class="String">'{http://duke.example.org}AddNumbersService'</span> <span class="Identifier">port</span>=<span class="String">'{http://duke.example.org}AddNumbersPort'</span> <span class="Identifier">url-pattern</span>=<span class="String">'/addnumbers'</span><span class="ReservedWord">/></span> <span class="ReservedWord"></endpoints></span></pre></div><p>If the wsdl, service, port are not specified in sun-jaxws.xml, then should be declared in the <code class="literal">@WebServiceProvider</code> annotation in implementation class.</p></div><div class="section" title="2.6. Provider and Binding"><div class="titlepage"><div><div><h3 class="title" id="section-343591403757231">2.6. Provider and Binding</h3></div></div></div><p>Provider endpoint can be configured for different bindings using binding ids. These binding ids are defined in JAX-WS API and endpoint can be configured by specifying <code class="literal">@BindingType</code> annotation or using binding attribute in sun-jaxws.xml. sun-jaxws.xml overwrites binding defined by <code class="literal">@BindingType</code> annotation. If the binding is not specified using <code class="literal">@BindingType</code> or in <code class="filename">sun-jaxws.xml</code>, the default binding is SOAP1.1/HTTP.</p><p>For example: To specify <code class="literal">XML/HTTP</code> binding using <code class="literal">@BindingType</code> annotation</p><div class="informalexample"><pre class="programlisting"><span class="Annotation">@ServiceMode(value = Service.Mode.MESSAGE)</span> <span class="Annotation">@BindingType(value = HTTPBinding.HTTP_BINDING)</span> <span class="ReservedWord">public</span> <span class="ReservedWord">class</span> ProviderImpl <span class="ReservedWord">implements</span> Provider<Source> { <span class="ReservedWord">public</span> Source invoke(Source source) { <span class="Comment">// ...</span> } }</pre></div><p>For example: To specify <code class="literal">XML/HTTP</code> binding in <code class="filename">sun-jaxws.xml</code></p><div class="informalexample"><pre class="programlisting"><span class="hl-directive" style="color: maroon"><?xml version="1.0" encoding="UTF-8"?></span> <span class="ReservedWord"><endpoints</span> <span class="Identifier">xmlns</span>=<span class="String">'http://java.sun.com/xml/ns/jax-ws/ri/runtime'</span> <span class="Identifier">version</span>=<span class="String">'2.0'</span><span class="ReservedWord">></span> <span class="ReservedWord"><endpoint</span> <span class="Identifier">...</span> <span class="Identifier">binding</span>=<span class="String">"http://www.w3.org/2004/08/wsdl/http"</span><span class="ReservedWord">/></span> <span class="ReservedWord"></endpoints></span></pre></div></div><div class="section" title="2.7. RESTful Provider endpoints"><div class="titlepage"><div><div><h3 class="title" id="section-330867941262645">2.7. RESTful Provider endpoints</h3></div></div></div><p>RESTful Web Services can be built using <code class="literal">XML/HTTP</code> binding based <code class="literal">Provider</code> endpoints. In this case, even HTTP GET requests are passed to the endpoint. <code class="literal">Endpoint</code> can get necessary HTTP request query string and path information using standard <code class="literal">MessageContext.QUERY_STRING</code> and <code class="literal">MessageContext.PATH_INFO</code>. For more details on endpoint implementation, see the <a class="link" href="../samples/restful/src/restful/server/AddNumbersImpl.java" target="_top">restful</a> sample. If the endpoint expects GET requests to contain extra path after the endpoint address, then <code class="literal">url-pattern</code> should have "<code class="literal">/*</code>" at the end in both <code class="filename">sun-jaxws.xml</code> and <code class="filename">web.xml</code>.</p><p>For example: <code class="filename">sun-jaxws.xml</code></p><div class="informalexample"><pre class="programlisting"><span class="hl-directive" style="color: maroon"><?xml version="1.0" encoding="UTF-8"?></span> <span class="ReservedWord"><endpoints</span> <span class="Identifier">xmlns</span>=<span class="String">'http://java.sun.com/xml/ns/jax-ws/ri/runtime'</span> <span class="Identifier">version</span>=<span class="String">'2.0'</span><span class="ReservedWord">></span> <span class="ReservedWord"><endpoint</span> <span class="Identifier">...</span> <span class="Identifier">binding</span>=<span class="String">"http://www.w3.org/2004/08/wsdl/http"</span> <span class="Identifier">url-pattern</span>=<span class="String">"/addnumbers/*"</span><span class="ReservedWord">/></span> <span class="ReservedWord"></endpoints></span></pre></div><p>For example: <code class="filename">web.xml</code></p><div class="informalexample"><pre class="programlisting"><span class="ReservedWord"><web-app></span> ... <span class="ReservedWord"><servlet-mapping></span> <span class="ReservedWord"><servlet-name></span>provider<span class="ReservedWord"></servlet-name></span> <span class="ReservedWord"><url-pattern></span>/addnumbers/*<span class="ReservedWord"></url-pattern></span> <span class="ReservedWord"></servlet-mapping></span> ... <span class="ReservedWord"></web-app></span></pre></div></div><div class="section" title="2.8. Provider and Handlers"><div class="titlepage"><div><div><h3 class="title" id="section-017933327977469">2.8. Provider and Handlers</h3></div></div></div><p>Handlers can be configured with Provider endpoints in <code class="filename">sun-jaxws.xml</code> descriptor or by putting <code class="literal">@HandlerChain</code> on the <code class="literal">Provider</code> implementation. For more information, see <a class="link" href="jaxws-war.html" target="_top">handler config</a>.</p><p>For example:</p><div class="informalexample"><pre class="programlisting"><span class="hl-directive" style="color: maroon"><?xml version="1.0" encoding="UTF-8"?></span> <span class="ReservedWord"><endpoints</span> <span class="Identifier">xmlns</span>=<span class="String">'http://java.sun.com/xml/ns/jax-ws/ri/runtime'</span> <span class="Identifier">xmlns:javaee</span>=<span class="String">"http://java.sun.com/xml/ns/javaee"</span> <span class="Identifier">version</span>=<span class="String">'2.0'</span><span class="ReservedWord">></span> <span class="ReservedWord"><endpoint</span> <span class="Identifier">name</span>=<span class="String">'AddNumbers'</span> <span class="Identifier">implementation</span>=<span class="String">'provider.server.AddNumbersImpl'</span> <span class="Identifier">wsdl</span>=<span class="String">'WEB-INF/wsdl/AddNumbers.wsdl'</span> <span class="Identifier">service</span>=<span class="String">'{http://duke.example.org}AddNumbersService'</span> <span class="Identifier">port</span>=<span class="String">'{http://duke.example.org}AddNumbersPort'</span> <span class="Identifier">url-pattern</span>=<span class="String">'/addnumbers'</span><span class="ReservedWord">/></span> <span class="ReservedWord"><javaee:handler-chain></span> <span class="ReservedWord"><javaee:handler-chain-name></span>my handler<span class="ReservedWord"></javaee:handler-chain-name></span> <span class="ReservedWord"><javaee:handler></span> <span class="ReservedWord"><javaee:handler-name></span>MyHandler<span class="ReservedWord"></javaee:handler-name></span> <span class="ReservedWord"><javaee:handler-class></span>provider.server.MyHandler <span class="ReservedWord"></javaee:handler-class></span> <span class="ReservedWord"></javaee:handler></span> <span class="ReservedWord"></javaee:handler-chain></span> <span class="ReservedWord"></endpoints></span></pre></div></div></div><div lang="en" class="section" title="3. AsyncProvider"><div class="titlepage"><div><div><h2 class="title" style="clear: both" id="users-guide-asyncprovider">3. AsyncProvider</h2></div></div></div><p>Web Service endpoints may choose to work at the XML message level by implementing the <code class="literal">Provider</code> interface. The related information about <code class="literal">Provider</code> endpoints is documented in <a class="xref" href="#users-guide-provider" title="2. Provider">Provider</a> page. However <code class="literal">Provider</code> endpoints are synchronous i.e. they receive XML requests and they return XML responses synchronously in <code class="literal">invoke()</code> method. If the endpoint wants to spawn a thread to process the request, it would block the jax-ws runtime thread and has to manage all the low details synchronizing the threads when the response is available. Also blocking a thread doesn't really scale well especially when the underlying transport is capable of handling asynchronous request and responses. RI provides an implemention specific solution to this problem by introducing <code class="literal">AsyncProvider.</code> This is similar to <code class="literal">Provider</code> endpoints but the difference is that the endpoint implementations have to implement <code class="literal">AsyncProvider</code> interface.</p><div class="section" title="3.1. AsyncProvider Example"><div class="titlepage"><div><div><h3 class="title" id="section-091974998856598">3.1. <code class="literal">AsyncProvider</code> Example</h3></div></div></div><p>The following example shows an <code class="literal">AsyncProvider</code> example that accesses the payload of the request.</p><div class="informalexample"><pre class="programlisting"><span class="Annotation">@WebServiceProvider</span> <span class="ReservedWord">public</span> <span class="ReservedWord">class</span> AsyncProviderImpl <span class="ReservedWord">implements</span> AsyncProvider<Source> { <span class="ReservedWord">public</span> <span class="ReservedWord">void</span> invoke(Source source, AsyncProviderCallback cbak, WebServiceContext ctxt) { <span class="Comment">// ...</span> } }</pre></div></div><div class="section" title="3.2. AsyncProvider sample"><div class="titlepage"><div><div><h3 class="title" id="section-930633228695613">3.2. <code class="literal">AsyncProvider</code> sample</h3></div></div></div><p>See a <a class="link" href="../samples/asyncprovider/Readme.txt" target="_top">sample</a> that illustrates <code class="literal">AsyncProvider</code> endpoints.</p></div><div class="section" title="3.3. AsyncService sample"><div class="titlepage"><div><div><h3 class="title" id="section-5233554712491355">3.3. <code class="literal">AsyncService</code> sample</h3></div></div></div><p>See another <a class="link" href="../samples/asyncservice/Readme.txt" target="_top">sample</a> that illustrates <code class="literal">AsyncProvider</code> endpoint that uses asynchronous servlet as the transport to bring true asynchronity on the server-side. See <a class="link" href="http://weblogs.java.net/blog/ramapulavarthi/archive/2010/08/18/new-asynchronous-servlet-transport-jax-ws-ri" target="_top">New Asynchronous Servlet Transport in JAX-WS RI</a> for mroe details on this feature.</p></div></div><div lang="en" class="section" title="4. Dispatch"><div class="titlepage"><div><div><h2 class="title" style="clear: both" id="users-guide-dispatch">4. Dispatch</h2></div></div></div><p>Web service client applications may choose to work at the XML message level by using the <code class="literal">Dispatch<T></code> APIs. The <code class="literal">javax.xml.ws.Dispatch<T></code> interface provides support for the dynamic invocation of service endpoint operations.</p><p>Four Message Exchange Protocols(MEP) are supported: request-response, one way, asynchronous polling, and callback. Each of these invocation MEPs are required with JAXB data bound <code class="literal">java.lang.Object</code>, <code class="literal">javax.xml.transform.Source</code>, <code class="literal">javax.xml.soap.SOAPMessage</code> and <code class="literal">javax.activation.DataSource</code> object requests.</p><p>The <code class="literal">javax.xml.ws.Service</code> acts as a factory for the creation of <code class="literal">Dispatch<T></code> instances. In addition, a <code class="literal">Dispatch<T></code> instance is created in either <code class="literal">Service.Mode.PAYLOAD</code> or <code class="literal">Service.Mode.MESSAGE</code> modes. A <code class="literal">javax.xml.soap.SOAPMessage</code> request can only be used with a <code class="literal">Dispatch<T></code> instance of <code class="literal">Service.Mode.MESSAGE</code> and using the SOAP Binding. A <code class="literal">javax.activation.DataSource</code> request can only be used with a <code class="literal">Dispatch<T></code> instance of <code class="literal">Service.Mode.MESSAGE</code> and using the XML/HTTP Binding.</p><p>Note that the <code class="literal">Dispatch<T></code> instance simply acts as a conduit for the request. No validation of the message is required to be performed by the implementation, though some may catch errors during request processing. It is up to the client program to supply well-formed XML requests.</p><div class="section" title="4.1. Programming Model"><div class="titlepage"><div><div><h3 class="title" id="section-71379735580733">4.1. Programming Model</h3></div></div></div><div class="section" title="4.1.1. Create a dynamic Service."><div class="titlepage"><div><div><h4 class="title" id="section-441203977673228">4.1.1. Create a dynamic <code class="literal">Service</code>.</h4></div></div></div><p>The <code class="literal">javax.xml.ws.Service</code> acts as a factory for the creation of a dynamic <code class="literal">Service</code>. When created for use with <code class="literal">Dispatch<T></code> APIs the <code class="literal">Service</code> created can be either a <code class="literal">Service</code> that has knowledge of the binding information of a known <code class="literal">Service</code> or no knowledge of any specific <code class="literal">Service</code>.</p><p>That is, when the <code class="literal">Service</code> is created with a WSDL file the port(s) binding ID, QName, and endpoint address are known to the <code class="literal">Service</code>.</p><p>The methods to create a dynamic <code class="literal">Service</code> are shown here:</p><div class="informalexample"><pre class="programlisting">Service service = Service.create(QName serviceQName); Service service = Service.create(URL wsdlLocation, QName serviceQName);</pre></div><p>A <code class="literal">Dispatch<T></code> instance must be bound to a specific port and endpoint before use. The service has an <code class="literal">addPort(QName portName, URI bindingID, String endpointAddress)</code> method that the client program can invoke for <code class="literal">Dispatch<T></code> objects. Ports created using this method can only be used with <code class="literal">Dispatch<T></code> instances.</p><p>If the <code class="literal">Service</code> has been created with WSDL binding information the the port need not be added as the <code class="literal">Dispatch<T></code> instance will be created specific for the binding information provided in the supplied WSDL file.</p><p>Developers who have used web service applications in the past are familiar with the port <code class="literal">QName</code> and endpoint address parameters of this method. JAX-WS RI 2.2.7 supports three <code class="literal">Binding</code> URI's, that of the SOAP 1.1, the SOAP 1.2 and XML/HTTP Binding. For more information on SOAP 1.2 support please refer to the SOAP 1.2 documents. For the XML/HTTP binding please see chapter 11 of the JAX-WS 2.0 PFD Specification.</p><p>The addition of the SOAP 1.1 port using the <code class="literal">Service</code> API is shown here:</p><div class="informalexample"><pre class="programlisting">service.addPort(QName portName, String SOAPBinding.SOAP11HTTP_BINDING, String endpointAddress);</pre></div><p>SOAP 1.2 support has been implemented for <code class="literal">Dispatch</code>. This requires only one change in the programming model. The addition of the SOAP 1.2 port using the <code class="literal">Service</code> API is shown here:</p><div class="informalexample"><pre class="programlisting">service.addPort(QName portName, String SOAPBinding.SOAP12HTTP_BINDING, String endpointAddress);</pre></div><p>XML/HTTP binding support has been implemented for <code class="literal">Dispatch</code>. The creation of the XML/HTTP port using the <code class="literal">Service</code> API is shown here:</p><div class="informalexample"><pre class="programlisting">service.addPort(QName portName, String HTTPBinding.HTTP_BINDING, String endpointAddress);</pre></div></div><div class="section" title="4.1.2. Create a Dispatch<T> instance."><div class="titlepage"><div><div><h4 class="title" id="section-7295163740787236">4.1.2. Create a <code class="literal">Dispatch<T></code> instance.</h4></div></div></div><p>The <code class="literal">Dispatch<T></code> object can be created using either of these two <code class="literal">Service</code> methods:</p><div class="informalexample"><pre class="programlisting">Dispatch dispatch = service.createDispatch(QName portName, Class clazz, Service.Mode mode); Dispatch dispatch = service.createDispatch(QName portName, JAXBContext jaxbcontext, Service.Mode mode);</pre></div><p>For a <code class="literal">javax.xml.transform.Source</code> and JAXB data binding <code class="literal">java.lang.Object</code> <code class="literal">Dispatch<T></code> can be created in both <code class="literal">Service.Mode.PAYLOAD</code> and <code class="literal">Service.Mode.MESSAGE</code> modes. A <code class="literal">javax.xml.soap.SOAPMessage</code> can only be created in <code class="literal">Service.Mode.MESSAGE</code> mode. The first form of the <code class="literal">createDispatch</code> method is used to create a <code class="literal">javax.xml.transform.Source</code> or <code class="literal">javax.xml.soap.SOAPMessage</code> specific to the <code class="literal">Dispatch<T></code> instance.</p><p>A JAXB object-specific instance can only be created using the second method listed above.</p><p>It is important to note that once the <code class="literal">Dispatch<T></code> instance is created it is static. That is, its <code class="literal">Service.Mode</code> or request type can not be changed. The instance can be reused given the caveat that if it is a JAXB-specific <code class="literal">Dispatch<T></code> it must be reused with objects known to the same <code class="literal">JAXBContext</code>.</p></div><div class="section" title="4.1.3. Set the context Map<String, Object> for the request."><div class="titlepage"><div><div><h4 class="title" id="section-568116144017489">4.1.3. Set the context <code class="literal">Map<String, Object></code> for the request.</h4></div></div></div><p>The <code class="literal">Dispatch<T></code> interface extends the <code class="literal">javax.xml.ws.BindingProvider</code> interface. The <code class="literal">BindingProvider</code> interface defines accessor methods for the request and response context maps. Standard <code class="literal">BindingProvider</code> properties are defined by the JAX-WS 2.0 specification and the client program may set and get these properties. The application may also define application-specific properties, but the specification discourages this for portability reasons.</p></div><div class="section" title="4.1.4. Prepare the message request."><div class="titlepage"><div><div><h4 class="title" id="section-14558813271967286">4.1.4. Prepare the message request.</h4></div></div></div><p>This is the client developer's responsibility. For examples of how to prepare specific request types refer to the <code class="literal">Dispatch<T></code> sample applications.</p></div><div class="section" title="4.1.5. Invoke the web service request."><div class="titlepage"><div><div><h4 class="title" id="section-628591767064064">4.1.5. Invoke the web service request.</h4></div></div></div><p>Four types of invocation MEPs are supported using the methods below. In methods that produce a response, the type of <code class="literal">Object</code> returned will be of the same type as the request. For example, a <code class="literal">SOAPMessage</code> request will return a <code class="literal">SOAPMessage</code> response.</p><div class="informalexample"><pre class="programlisting">Object response = dispatch.invoke(T); dispatch.invokeOneway(T); Response<T> response = dispatch.invokeAsync(T); Future<?> response = dispatch.invokeAsync(T, AsyncHandler);</pre></div></div></div><div class="section" title="4.2. Dispatch and Asynchronous Invocations"><div class="titlepage"><div><div><h3 class="title" id="section-21282255346754875">4.2. Dispatch and Asynchronous Invocations</h3></div></div></div><p>Asynchronous invocations require special consideration. The first form of the <code class="literal">invokeAsync</code> method is a polling method. The response, <code class="literal">Response<T></code>,returns to the user immediately and may be polled for completion. In the meantime, the client program can do other work.</p><p>The <code class="literal">javax.xml.ws.Response<T></code> implements the <code class="literal">java.util.concurrent.Future<T></code> interface that is included in J2SE 5.0. The <code class="literal">Response<T></code> object returns the actual response via its <code class="literal">get</code> method, which blocks if the response is not ready to be returned.</p><p>The <code class="literal">Future<T></code> interface also has a <code class="literal">cancel</code> method that will attempt to cancel the request invocation if the request is being invoked.</p><p>Faults returned from the service or exceptions thrown during the invocation are returned when the <code class="literal">Response<T></code> <code class="literal">get</code> method is called. Because the execution doesn't occur in the main thread, the exception or fault returned is wrapped in an <code class="literal">java.util.concurrent.ExecutionException</code>. To obtain the actual cause use the <code class="literal">getCause</code> method of <code class="literal">ExecutionException</code>.</p><p>For more information on the <code class="literal">java.util.concurrent.Future<?></code> interface see the J2SE 5.0 documentation.</p><div class="informalexample"><pre class="programlisting"><span class="ReservedWord">public</span> <span class="ReservedWord">interface</span> Response<T> <span class="ReservedWord">extends</span> java.util.concurrent.Future<T> { Map<String, Object> getContext(); }</pre></div><p>The second form of the <code class="literal">invokeAsync</code> method has a second parameter of type <code class="literal">javax.xml.ws.AsyncHandler</code>. The purpose of the <code class="literal">AsyncHandler</code> is to get and handle the the response or any fault thrown in an application-specific way. The <code class="literal">AsyncHandler</code> has a method <code class="literal">handleResponse(Response<T>)</code> that takes a <code class="literal">javax.xml.ws.Response<T></code> parameter. This method gets the response or any faults and processes them according to behavior defined in the application. Note that it is the responsibility of the client program to implement the asynchronous handler.</p><div class="informalexample"><pre class="programlisting"><span class="ReservedWord">class</span> ResponseHandler <span class="ReservedWord">implements</span> javax.xml.ws.AsyncHandler { <span class="ReservedWord">public</span> handleResponse(Response<T>); }</pre></div><p>This form of the asynchronous invocation method returns a <code class="literal">Future<?></code> object with wildcard type. As in the asynchronous poll invocation, the <code class="literal">Future<T></code> object can be polled to see if the response is ready. However, calling the <code class="literal">get</code> method will not return the response of the invocation, but an object of indeterminate type.</p><p>Examples of synchronous and asynchronous invocations are shown in the <code class="literal">Dispatch<T></code> samples. For convenience an example of <code class="literal">Response<T></code> usage is display here:</p><div class="informalexample"><pre class="programlisting">Response<Source> response = dispatch.invokeAsync(Source); <span class="ReservedWord">while</span> (!response.isDone()) { <span class="Comment">//go off and do some work</span> } <span class="ReservedWord">try</span> { <span class="Comment">//get the actual result</span> Source result = (javax.xml.transform.Source) response.get(); <span class="Comment">//do something with the result</span> } <span class="ReservedWord">catch</span> (ExecutionException ex) { <span class="Comment">//get the actual cause</span> Throwable cause = ex.getCause(); } <span class="ReservedWord">catch</span> (InterupptedException ie) { <span class="Comment">//note interruptions</span> System.out.println(<span class="String">"Operation invocation interrupted"</span>); }</pre></div></div></div><div lang="en" class="section" title="5. Asynchronous Client"><div class="titlepage"><div><div><h2 class="title" style="clear: both" id="users-guide-asynchronous-client">5. Asynchronous Client</h2></div></div></div><p>This document describes how a client application can invoke a remote web service asynchronously. It can do so either by generating a static stub or using the Dispatch API.</p><div class="section" title="5.1. Asynchronous Invocation Using Static Stub"><div class="titlepage"><div><div><h3 class="title" id="section-346120708971664">5.1. Asynchronous Invocation Using Static Stub</h3></div></div></div><p>Client application should apply <code class="literal">jaxws:enableAsyncMapping</code> binding declaration to the WSDL file to generate asynchronous method in the service endpoint interface. Please refer to <a class="xref" href="#asynchrony" title="9.2.4. Asynchrony">Asynchrony</a> for details on how this can be applied to the WSDL file.</p><p>Lets look at the following WSDL excerpt:</p><div class="informalexample"><pre class="programlisting"><span class="ReservedWord"><definitions</span> <span class="Identifier">name</span>=<span class="String">"AddNumbers"</span> <span class="Identifier">targetNamespace</span>=<span class="String">"http://duke.example.org"</span> <span class="Identifier">xmlns:tns</span>=<span class="String">"http://duke.example.org"</span> <span class="Identifier">xmlns</span>=<span class="String">"http://schemas.xmlsoap.org/wsdl/"</span> <span class="Identifier">xmlns:xsd</span>=<span class="String">"http://www.w3.org/2001/XMLSchema"</span> <span class="Identifier">xmlns:soap</span>=<span class="String">"http://schemas.xmlsoap.org/wsdl/soap/"</span><span class="ReservedWord">></span> ... <span class="ReservedWord"><portType</span> <span class="Identifier">name</span>=<span class="String">"AddNumbersImpl"</span><span class="ReservedWord">></span> <span class="ReservedWord"><operation</span> <span class="Identifier">name</span>=<span class="String">"addNumbers"</span><span class="ReservedWord">></span> <span class="ReservedWord"><input</span> <span class="Identifier">message</span>=<span class="String">"tns:addNumbers"</span><span class="ReservedWord">/></span> <span class="ReservedWord"><output</span> <span class="Identifier">message</span>=<span class="String">"tns:addNumbersResponse"</span><span class="ReservedWord">/></span> <span class="ReservedWord"></operation></span> <span class="ReservedWord"></portType></span> <span class="ReservedWord"><binding</span> <span class="Identifier">name</span>=<span class="String">"AddNumbersImplBinding"</span> <span class="Identifier">type</span>=<span class="String">"tns:AddNumbersImpl"</span><span class="ReservedWord">></span> <span class="ReservedWord"><soap:binding</span> <span class="Identifier">transport</span>=<span class="String">"http://schemas.xmlsoap.org/soap/http"</span> <span class="Identifier">style</span>=<span class="String">"document"</span><span class="ReservedWord">/></span> <span class="ReservedWord"><operation</span> <span class="Identifier">name</span>=<span class="String">"addNumbers"</span><span class="ReservedWord">></span> <span class="ReservedWord"><soap:operation</span> <span class="Identifier">soapAction</span>=<span class="String">""</span><span class="ReservedWord">/></span> <span class="ReservedWord"><input></span> <span class="ReservedWord"><soap:body</span> <span class="Identifier">use</span>=<span class="String">"literal"</span><span class="ReservedWord">/></span> <span class="ReservedWord"></input></span> <span class="ReservedWord"><output></span> <span class="ReservedWord"><soap:body</span> <span class="Identifier">use</span>=<span class="String">"literal"</span><span class="ReservedWord">/></span> <span class="ReservedWord"></output></span> <span class="ReservedWord"></operation></span> <span class="ReservedWord"></binding></span> ... <span class="ReservedWord"></definitions></span></pre></div><p>In order to generate a service endpoint interface with asynchronous methods the following binding declaration file will be passed to <span class="command"><strong>wsimport</strong></span>:</p><div class="informalexample"><pre class="programlisting"><span class="ReservedWord"><bindings</span> <span class="Identifier">xmlns:xsd</span>=<span class="String">"http://www.w3.org/2001/XMLSchema"</span> <span class="Identifier">xmlns:wsdl</span>=<span class="String">"http://schemas.xmlsoap.org/wsdl/"</span> <span class="Identifier">wsdlLocaption</span>=<span class="String">"http://localhost:8080/jaxws-async/addnumbers?WSDL"</span> <span class="Identifier">xmlns</span>=<span class="String">"http://java.sun.com/xml/ns/jaxws"</span><span class="ReservedWord">></span> <span class="ReservedWord"><bindings</span> <span class="Identifier">node</span>=<span class="String">"wsdl:definitions"</span><span class="ReservedWord">></span> <span class="ReservedWord"><package</span> <span class="Identifier">name</span>=<span class="String">"async.client"</span><span class="ReservedWord">/></span> <span class="ReservedWord"><enableAsyncMapping></span>true<span class="ReservedWord"></enableAsyncMapping></span> <span class="ReservedWord"></bindings></span> <span class="ReservedWord"></bindings></span></pre></div><p>It produces the following service endpoint interface (annotations are removed from the synchronous method for better readability):</p><div class="informalexample"><pre class="programlisting">//synchronous method public int addNumbers(int number1, int number2) throws java.rmi.RemoteException; //async polling Method public Response<AddNumbersResponse> addNumbers(int number1, int number2); //async callback Method public Future<?> addNumbers(int number1, int number2, AsyncHandler<AddNumbersResponse>);</pre></div><div class="section" title="5.1.1. Async Polling"><div class="titlepage"><div><div><h4 class="title" id="section-449139041763976">5.1.1. Async Polling</h4></div></div></div><div class="informalexample"><pre class="programlisting">//async polling Method public Response<AddNumbersResponse> addNumbers(int number1, int number2);</pre></div><p>Typically a client application will invoke the async polling operation on the stub and check for a response on the returned <code class="literal">Response</code> object. The response is available when <code class="literal">Response.isDone</code> returns true.</p><div class="informalexample"><pre class="programlisting">javax.xml.ws.Response<AddNumbersResponse> resp = port .addNumbersAsync(<span class="Numeric">10</span>, <span class="Numeric">20</span>); <span class="ReservedWord">while</span> (!resp.isDone()) { <span class="Comment">//do something</span> } System.out.println(<span class="String">"The sum is: "</span> + resp.get().getReturn()); ...</pre></div></div><div class="section" title="5.1.2. Async Callback"><div class="titlepage"><div><div><h4 class="title" id="section-73214284296898">5.1.2. Async Callback</h4></div></div></div><div class="informalexample"><pre class="programlisting">//async callback Method public Future<?> addNumbers(int number1, int number2, AsyncHandler<AddNumbersResponse>);</pre></div><p>Here the client application provides an <code class="literal">AsyncHandler</code> by implementing the <code class="literal">javax.xml.ws.AsyncHandler<T></code> interface.</p><div class="informalexample"><pre class="programlisting"><span class="Comment">/** * Async callback handler */</span> <span class="ReservedWord">class</span> AddNumbersCallbackHandler <span class="ReservedWord">implements</span> AsyncHandler<AddNumbersResponse> { <span class="ReservedWord">private</span> AddNumbersResponse output; <span class="Comment">/** * @see javax.xml.ws.AsyncHandler#handleResponse(javax.xml.ws.Response) */</span> <span class="ReservedWord">public</span> <span class="ReservedWord">void</span> handleResponse(Response<AddNumbersResponse> response) { <span class="ReservedWord">try</span> { output = response.get(); } <span class="ReservedWord">catch</span> (ExecutionException e) { e.printStackTrace(); } <span class="ReservedWord">catch</span> (InterruptedException e) { e.printStackTrace(); } } AddNumbersResponse getResponse() { <span class="ReservedWord">return</span> output; } }</pre></div><p>The async handler is then passed as the last parameter of the async callback method:</p><div class="informalexample"><pre class="programlisting"><span class="Comment">//instantiates the callback handler</span> AddNumbersCallbackHandler callbackHandler = <span class="ReservedWord">new</span> AddNumbersCallbackHandler(); <span class="Comment">//invoke the async callback method</span> Future<?> resp = port.addNumbersAsync(number1, number2, callbackHandler); <span class="ReservedWord">while</span> (!resp.isDone()) { <span class="Comment">//do something</span> } System.out.println(<span class="String">"The sum is: "</span> + callbackHandler.getResponse().getReturn());</pre></div></div></div><div class="section" title="5.2. Asynchronous Invocation Using Dispatch"><div class="titlepage"><div><div><h3 class="title" id="section-85273158180115">5.2. Asynchronous Invocation Using Dispatch</h3></div></div></div><p>For information on the Dispatch API and asynchronous invocations see <a class="xref" href="#users-guide-dispatch" title="4. Dispatch">Dispatch</a></p></div></div><div lang="en" class="section" title="6. Handler"><div class="titlepage"><div><div><h2 class="title" style="clear: both" id="users-guide-handler">6. Handler</h2></div></div></div><div class="section" title="6.1. Handler Types"><div class="titlepage"><div><div><h3 class="title" id="section-524340464580105">6.1. Handler Types</h3></div></div></div><p>JAX-WS 2.0 defines a <code class="literal">Handler</code> interface, with subinterfaces <code class="literal">LogicalHandler</code> and <code class="literal">SOAPHandler</code>. The <code class="literal">Handler</code> interface contains <code class="literal">handleMessage(C context)</code> and <code class="literal">handleFault(C context)</code> methods, where <code class="literal">C</code> extends <code class="literal">MessageContext</code>. A property in the <code class="literal">MessageContext</code> object is used to determine if the message is inbound or outbound. <code class="literal">SOAPHandler</code> objects have access to the full soap message including headers. Logical handlers are independent of protocol and have access to the payload of the message.</p><p>The new handler types can now be written without casting the message context object that is passed to them. For instance:</p><div class="informalexample"><pre class="programlisting"><span class="ReservedWord">public</span> <span class="ReservedWord">class</span> MyLogicalHandler <span class="ReservedWord">implements</span> LogicalHandler<LogicalMessageContext> { <span class="ReservedWord">public</span> <span class="ReservedWord">boolean</span> handleMessage(LogicalMessageContext messageContext) { LogicalMessage msg = messageContext.getMessage(); <span class="ReservedWord">return</span> true; } <span class="Comment">// other methods</span> }</pre></div><div class="informalexample"><pre class="programlisting"><span class="ReservedWord">public</span> <span class="ReservedWord">class</span> MySOAPHandler <span class="ReservedWord">implements</span> SOAPHandler<SOAPMessageContext> { <span class="ReservedWord">public</span> <span class="ReservedWord">boolean</span> handleMessage(SOAPMessageContext messageContext) { SOAPMessage msg = messageContext.getMessage(); <span class="ReservedWord">return</span> true; } <span class="Comment">// other methods</span> }</pre></div><p>A <code class="literal">close(C context)</code> method has been added that is called on the handlers at the conclusion of a message exchange pattern. This allows handlers to clean up any resources that were used for the processing of a request-only or request/response exchange.</p><p>The <code class="literal">init()</code> and <code class="literal">destroy()</code> methods of the handler lifecycle no longer exist. Instead, a method may be annotated with the <code class="literal">@PostConstruct</code> annotation to be called after the handler is created or the <code class="literal">@PreDestroy</code> annotation to be called before the handler is destroyed. Note that the annotated methods must return <code class="literal">void</code> and take no arguments:</p><div class="informalexample"><pre class="programlisting"><span class="ReservedWord">import</span> javax.annotation.PostConstruct; <span class="ReservedWord">import</span> javax.annotation.PreDestroy; <span class="ReservedWord">public</span> <span class="ReservedWord">class</span> MyLogicalHandler <span class="ReservedWord">implements</span> LogicalHandler<LogicalMessageContext> { <span class="Annotation">@PostConstruct</span> <span class="ReservedWord">public</span> <span class="ReservedWord">void</span> methodA() { } <span class="Annotation">@PreDestroy</span> <span class="ReservedWord">public</span> <span class="ReservedWord">void</span> methodB() { } <span class="Comment">// other methods</span> }</pre></div></div><div class="section" title="6.2. MessageContext"><div class="titlepage"><div><div><h3 class="title" id="section-276528078695232">6.2. MessageContext</h3></div></div></div><p>In the examples above, the <code class="literal">LogicalMessage</code> object allows a handler to get and set the message payload either as a JAXB object or as a <code class="literal">javax.xml.transform.Source</code>. The <code class="literal">SOAPMessage</code> object allows access to headers and the SOAP body of the message.</p><p>Both context objects extend <code class="literal">MessageContext</code>, which holds properties that the handlers can use to communicate with each other. A standard property <code class="literal">MessageContext.MESSAGE_OUTBOUND_PROPERTY</code> holds a <code class="literal">Boolean</code> that is used to determine the direction of a message. For example, during a request, the property would be <code class="literal">Boolean.TRUE</code> when seen by a client handler and <code class="literal">Boolean.FALSE</code> when seen by a server handler.</p><p>The message context object can also hold properties set by the client or provider. For instance, port proxy and dispatch objects both extend <code class="literal">BindingProvider</code>. A message context object can be obtained from both to represent the request or response context. Properties set in the request context can be read by the handlers, and the handlers may set properties on the message context objects passed to them. If these properties are set with the scope <code class="literal">MessageContext.Scope.APPLICATION</code> then they will be available in the response context to the client. On the server end, a context object is passed into the <code class="literal">invoke</code> method of a <code class="literal">Provider</code>.</p></div><div class="section" title="6.3. Handler Chain Configuration"><div class="titlepage"><div><div><h3 class="title" id="section-165423693536683">6.3. Handler Chain Configuration</h3></div></div></div><div class="section" title="6.3.1. Handler Files"><div class="titlepage"><div><div><h4 class="title" id="section-404105458093083">6.3.1. Handler Files</h4></div></div></div><p>Starting from a WSDL file, handler chain configuration is through WSDL customizations as defined by <a class="link" href="http://jcp.org/en/jsr/detail?id=109" target="_top">JSR 109</a>. A <code class="literal"><handler-chains></code> element is added to the customization file. The following is a simple handler chain with one handler (customization may be on server or client side):</p><div class="informalexample"><pre class="programlisting"><span class="ReservedWord"><--</span> <span class="Identifier">excerpt</span> <span class="Identifier">from</span> <span class="Identifier">customization</span> <span class="Identifier">file</span> <span class="Identifier">--></span> <span class="Identifier"><bindings</span> <span class="Identifier">xmlns</span>=<span class="String">"http://java.sun.com/xml/ns/jaxws"</span><span class="ReservedWord">></span> <span class="ReservedWord"><handler-chains</span> <span class="Identifier">xmlns</span>=<span class="String">"http://java.sun.com/xml/ns/javaee"</span><span class="ReservedWord">></span> <span class="ReservedWord"><handler-chain></span> <span class="ReservedWord"><handler></span> <span class="ReservedWord"><handler-class></span>fromwsdl.handler_simple.common.TestHandler <span class="ReservedWord"></handler-class></span> <span class="ReservedWord"></handler></span> <span class="ReservedWord"></handler-chain></span> <span class="ReservedWord"></handler-chains></span> <span class="ReservedWord"></bindings></span></pre></div><p>Multiple <code class="literal">handler-chain</code> elements may exist within the <code class="literal">handler-chains</code> element. These may optionally use a service name, port name, or protocol pattern in their description to apply some chains to certain ports and protocols and not to others. For instance (note the wildcard character used in the service name):</p><div class="informalexample"><pre class="programlisting"><span class="ReservedWord"><--</span> <span class="Identifier">excerpt</span> <span class="Identifier">--></span> <span class="Identifier"><handler-chains</span> <span class="Identifier">xmlns</span>=<span class="String">"http://java.sun.com/xml/ns/javaee"</span><span class="ReservedWord">></span> <span class="ReservedWord"><handler-chain></span> <span class="ReservedWord"><service-name-pattern</span> <span class="Identifier">xmlns:ns1</span>=<span class="String">"urn:namespace"</span><span class="ReservedWord">></span>ns1:My*Service <span class="ReservedWord"></service-name-pattern></span> <span class="ReservedWord"><handler></span>...<span class="ReservedWord"></handler></span> <span class="ReservedWord"></handler-chain></span> <span class="ReservedWord"><handler-chain></span> <span class="ReservedWord"><port-name-pattern</span> <span class="Identifier">xmlns:ns1</span>=<span class="String">"urn:namespace"</span><span class="ReservedWord">></span>ns1:HelloPort <span class="ReservedWord"></port-name-pattern></span> <span class="ReservedWord"><handler></span>...<span class="ReservedWord"></handler></span> <span class="ReservedWord"></handler-chain></span> <span class="ReservedWord"><handler-chain></span> <span class="ReservedWord"><protocol-bindings></span>##SOAP11_HTTP<span class="ReservedWord"></protocol-bindings></span> <span class="ReservedWord"><handler></span>...<span class="ReservedWord"></handler></span> <span class="ReservedWord"></handler-chain></span> <span class="ReservedWord"></handler-chains></span></pre></div><p>Handlers will appear in the final handler chain in the order that they are included in the customization file. However, logical handlers will be sorted out and called before protocol handlers during execution.</p><p>Starting from a Java class, annotations are used to describe the handler chain as defined by <a class="link" href="http://jcp.org/en/jsr/detail?id=181" target="_top">JSR 181</a>. The following example uses the <code class="literal">@HandlerChain</code> annotation to refer to a file describing the chain.</p><div class="informalexample"><pre class="programlisting"><span class="ReservedWord">import</span> javax.jws.HandlerChain; <span class="ReservedWord">import</span> javax.jws.WebService; <span class="Annotation">@WebService</span> <span class="Annotation">@HandlerChain(file = "handlers.xml")</span> <span class="ReservedWord">public</span> <span class="ReservedWord">class</span> MyServiceImpl { <span class="Comment">// implementation of class</span> }</pre></div><p>An example <code class="literal">handlers.xml</code> file is shown below. The schema is the same that is used for the customization.</p><div class="informalexample"><pre class="programlisting"><span class="hl-directive" style="color: maroon"><?xml version="1.0" encoding="UTF-8"?></span> <span class="ReservedWord"><jws:handler-chains</span> <span class="Identifier">xmlns:jws</span>=<span class="String">"http://java.sun.com/xml/ns/javaee"</span><span class="ReservedWord">></span> <span class="ReservedWord"><jws:handler-chain></span> <span class="ReservedWord"><jws:handler></span> <span class="ReservedWord"><jws:handler-class></span>fromjava.handler_simple.common.TestHandler <span class="ReservedWord"></jws:handler-class></span> <span class="ReservedWord"></jws:handler></span> <span class="ReservedWord"></jws:handler-chain></span> <span class="ReservedWord"></jws:handler-chains></span></pre></div><p>When packaging the service, the <code class="filename">handlers.xml</code> file must be in the classpath within the WAR file, either directly under <code class="literal">WEB-INF/classes</code> or further down in the same package as the service class file.</p><p>On the server side, the handlers may be configured in the <code class="filename">sun-jaxws.xml</code>deployment descriptor as well. A handler chain specified here will override handlers in WSDL customizations or annotated classes. The schema for the handler section is the same as in the previous examples:</p><div class="informalexample"><pre class="programlisting"><span class="ReservedWord"><endpoints</span> <span class="Identifier">...></span> <span class="Identifier"><endpoint...></span> <span class="Identifier"><handler-chains</span> <span class="Identifier">xmlns</span>=<span class="String">"http://java.sun.com/xml/ns/javaee"</span><span class="ReservedWord">></span> <span class="ReservedWord"><handler-chain></span> ... <span class="ReservedWord"></handler-chain></span> <span class="ReservedWord"></handler-chains></span> <span class="ReservedWord"></endpoint></span> <span class="ReservedWord"></endpoints></span></pre></div></div><div class="section" title="6.3.2. Programmatic Case"><div class="titlepage"><div><div><h4 class="title" id="section-34700025143465">6.3.2. Programmatic Case</h4></div></div></div><p>Handler chains may be configured on the client side at runtime by setting a chain directly on a <code class="literal">BindingProvider</code> (e.g., a <code class="literal">Dispatch</code> object or a port proxy) or by using a <code class="literal">HandlerResolver</code>. This example shows how to add a handler chain to a port proxy:</p><div class="informalexample"><pre class="programlisting"><span class="Comment">// given proxy interface HelloPortType</span> HelloPortType myProxy = <span class="Comment">// create proxy</span> Binding binding = ((BindingProvider) myProxy).getBinding(); <span class="Comment">// can create new list or use existing one</span> List<Handler> handlerList = binding.getHandlerChain(); handlerList.add(<span class="ReservedWord">new</span> MyHandler()); binding.setHandlerChain(handlerList);</pre></div><p>To configure the handlers that are added to newly created <code class="literal">Binding</code> objects, add a handler resolver to the service with <code class="literal">setHandlerResolver()</code>. The new resolver will be used whenever a <code class="literal">BindingProvider</code> is created from the service. An example resolver is as follows:</p><div class="informalexample"><pre class="programlisting"><span class="Comment">/* * Add handlers to the returned list based on the information * in info.getBindingID(), getPortName(), and/or getServiceName(). */</span> <span class="ReservedWord">public</span> <span class="ReservedWord">class</span> MyResolver <span class="ReservedWord">implements</span> HandlerResolver { <span class="ReservedWord">public</span> List<Handler> getHandlerChain(PortInfo info) { List<Handler> handlers = <span class="ReservedWord">new</span> ArrayList<Handler>(); <span class="Comment">// add handlers to list based on PortInfo information</span> <span class="ReservedWord">return</span> handlers; } }</pre></div><p>A resolver that modifies the initially configured handler chains could be written by calling <code class="literal">service.getHandlerResolver()</code> and passing the original resolver to a new one:</p><div class="informalexample"><pre class="programlisting"><span class="Comment">// original HandlerResolver passed in constructor or setter method</span> <span class="ReservedWord">public</span> List<Handler> getHandlerChain(PortInfo info) { List<Handler> handlers = originalResolver.getHandlerChain(info); <span class="Comment">// alter list based on PortInfo information</span> <span class="ReservedWord">return</span> handlers; }</pre></div></div></div><div class="section" title="6.4. Handler Samples"><div class="titlepage"><div><div><h3 class="title" id="section-8594509924044">6.4. Handler Samples</h3></div></div></div><p>The <span class="application">fromjavahandler</span> and <span class="application">fromwsdlhandler</span> samples set a <code class="literal">SOAPHandler</code> on the client and server. This handler simply outputs the contents of the SOAP message and can be used to see the requests and responses being passed back and forth. See the sample documentation for information on running the samples.</p></div></div><div lang="en" class="section" title="7. MTOM and Swaref"><div class="titlepage"><div><div><h2 class="title" style="clear: both" id="users-guide-mtom-and-swaref">7. MTOM and Swaref</h2></div></div></div><div class="section" title="7.1. MTOM and XOP"><div class="titlepage"><div><div><h3 class="title" id="mtom-and-xop">7.1. MTOM and XOP</h3></div></div></div><p><a class="link" href="http://www.w3.org/TR/soap12-mtom/" target="_top">MTOM</a> (Message Transmission and Optimization Mechanism) together with <a class="link" href="http://www.w3.org/TR/xop10/" target="_top">XOP</a> (XML Binary Optimized Packaging) defines how an XML binary data such as <code class="literal">xs:base64Binary</code> or <code class="literal">xs:hexBinary</code> can be optimally transmitted over the wire. XML type, such as <code class="literal">xs:base64Binary</code> is sent in lined inside the SOAP envelope. This gets quite in-efficient when the data size is more, for example a SOAP endpoint that exchanges images/songs etc. MTOM specifies how XOP packaging can be used to send the binary data optimally.</p></div><div class="section" title="7.2. MTOM in JAX-WS 2.0"><div class="titlepage"><div><div><h3 class="title" id="mtom-in-jaxws-2-0">7.2. MTOM in JAX-WS 2.0</h3></div></div></div><p>MTOM feature is disabled in JAX-WS by default. It can be enabled on the client and server. Once enabled all the XML binary data, XML elements of type <code class="literal">xs:base64Binary</code> and <code class="literal">xs:hexBinary</code> is optimally transmitted. Currently MTOM works only with proxy port.</p><div class="section" title="7.2.1. xmime:expectedContentType to Java type mapping"><div class="titlepage"><div><div><h4 class="title" id="xmmime-expectedmediatype-to-java">7.2.1. <code class="literal">xmime:expectedContentType</code> to Java type mapping</h4></div></div></div><p>An schema element of type <code class="literal">xs:bas64Binary</code> or <code class="literal">xs:hexBinary</code> can be annotated by using attribute reference using <a class="link" href="http://www.w3.org/TR/xml-media-types/" target="_top"><code class="literal">xmime:expectedContentType</code></a> JAXB 2.0 specification defines <code class="literal">xmime:expectedContentType</code> to Java type mapping in <a class="xref" href="#users-guide-mtom-and-swaref-table-1" title="Table 2. xmime:expectedContentType to Java type mapping">Table 2, “<code class="literal">xmime:expectedContentType</code> to Java type mapping”</a>. Here is this table:</p><div class="table"><a name="users-guide-mtom-and-swaref-table-1"></a><p class="title"><b>Table 2. <code class="literal">xmime:expectedContentType</code> to Java type mapping</b></p><div class="table-contents"><table summary="xmime:expectedContentType to Java
 type mapping" border="1"><colgroup><col width="50%"><col width="50%"></colgroup><thead><tr><th>MIME Type</th><th>Java Type</th></tr></thead><tbody><tr><td><p><code class="literal">image/gif</code></p></td><td><p><code class="literal">java.awt.Image</code></p></td></tr><tr><td><p><code class="literal">image/jpeg</code></p></td><td><p><code class="literal">java.awt.Image</code></p></td></tr><tr><td><p><code class="literal">text/plain</code></p></td><td><p><code class="literal">java.lang.String</code></p></td></tr><tr><td><p><code class="literal">text/xml</code> or <code class="literal">application/xml</code></p></td><td><p><code class="literal">javax.xml.transform.Source</code></p></td></tr><tr><td><p><code class="literal">*/*</code></p></td><td><p><code class="literal">javax.activation.DataHandler</code></p></td></tr></tbody></table></div></div><br class="table-break"><div class="informalexample"><pre class="programlisting"><span class="ReservedWord"><element</span> <span class="Identifier">name</span>=<span class="String">"image"</span> <span class="Identifier">type</span>=<span class="String">"base64Binary"</span><span class="ReservedWord">/></span></pre></div><p>is mapped to <code class="literal">byte[]</code></p><div class="informalexample"><pre class="programlisting"><element name="image" type="base64Binary" <span class="bold"><strong>xmime:expectedContentTypes="image/jpeg"</strong></span> xmlns:xmime="http://www.w3.org/2005/05/xmlmime"/></pre></div><p>is mapped to <code class="literal">java.awt.Image</code></p></div><div class="section" title="7.2.2. xmime:contentType schema annotation"><div class="titlepage"><div><div><h4 class="title" id="xmime-contenttype-schema-annotation">7.2.2. <code class="literal">xmime:contentType</code> schema annotation</h4></div></div></div><p><a class="link" href="http://www.w3.org/TR/xml-media-types/" target="_top"><code class="literal">xmime:contentType</code></a> schema annotation indicates the content-type of an XML element content whose type is <code class="literal">xs:base64Binary</code> or <code class="literal">xs:hexBinary</code>. The value of the attribute is a valid <code class="literal">content-type</code> string (e.g., "<code class="literal">text/xml; charset=utf-16</code>"). This attribute specifies the <code class="literal">content-type</code> of the element content on which it occurs. This annotation can be primarily used to indicate the <code class="literal">Content-Type</code> of binary data.</p><p>For example the schema type</p><div class="informalexample"><pre class="programlisting"><span class="ReservedWord"><element</span> <span class="Identifier">name</span>=<span class="String">"TestMtomXmimeContentType"</span> <span class="Identifier">type</span>=<span class="String">"types:PictureType"</span><span class="ReservedWord">/></span> <span class="ReservedWord"><complexType</span> <span class="Identifier">name</span>=<span class="String">"PictureType"</span><span class="ReservedWord">></span> <span class="ReservedWord"><simpleContent></span> <span class="ReservedWord"><restriction</span> <span class="Identifier">base</span>=<span class="String">"xmime:base64Binary"</span><span class="ReservedWord">></span> <span class="ReservedWord"><attribute</span> <span class="Identifier">ref</span>=<span class="String">"xmime:contentType"</span> <span class="Identifier">use</span>=<span class="String">"required"</span><span class="ReservedWord">/></span> <span class="ReservedWord"></restriction></span> <span class="ReservedWord"></simpleContent></span> <span class="ReservedWord"></complexType></span></pre></div><p>Here <code class="literal">xmime:base64Binary</code> is defined by <a class="link" href="http://www.w3.org/TR/xml-media-types/#schema" target="_top">Describing Media Content of Binary Data in XML</a>.</p><p>Gets mapped to PicutreType bean by <span class="command"><strong>wsimport</strong></span>:</p><div class="informalexample"><pre class="programlisting"> <code class="literal">PictureType req = new PictureType(); req.setValue(name.getBytes()); req.setContentType("application/xml");</code> </pre></div><p>On the wire this is how it looks:</p><div class="informalexample"><pre class="programlisting"> <code class="literal"><?xml version="1.0" encoding="UTF-8"?> <soapenv:Envelope xmlns:soapenv=" http://schemas.xmlsoap.org/soap/envelope/" xmlns:xsd=" http://www.w3.org/2001/XMLSchema" xmlns:ns1=" http://example.org/mtom/data" xmlns:ns2="http://www.w3.org/2005/05/xmlmime"> <soapenv:Body> <ns1:TestMtomXmimeContentTypeResponse ns2:contentType="application/xml"> <xop:Include xmlns:xop="http://www.w3.org/2004/08/xop/include" href="c id:193ed174-d313-4325-8eed-16cc25595e4e@example.org"/> </ns1:TestMtomXmimeContentTypeResponse> </soapenv:Body> </soapenv:Envelope></code> </pre></div></div><div class="section" title="7.2.3. How to enable MTOM in JAX-WS 2.0"><div class="titlepage"><div><div><h4 class="title" id="how-to-enable-mtom-in-jaxws-2-0">7.2.3. How to enable MTOM in JAX-WS 2.0</h4></div></div></div><p><span class="bold"><strong>Enabling MTOM on Server:</strong></span></p><div class="itemizedlist"><ul class="itemizedlist" type="disc"><li class="listitem"><p>Enable using <code class="literal">@javax.xml.ws.soap.MTOM</code> annotation on the endpoint (SEI) implementation class </p><div class="informalexample"><pre class="programlisting"><span class="Annotation">@javax.xml.ws.soap.MTOM</span> <span class="Annotation">@WebService(endpointInterface = "mtom.server.Hello")</span> <span class="ReservedWord">public</span> <span class="ReservedWord">class</span> HelloImpl <span class="ReservedWord">implements</span> Hello { <span class="Comment">// ...</span> }</pre></div></li></ul></div><div class="itemizedlist"><ul class="itemizedlist" type="disc"><li class="listitem"><p>MTOM can be also be enabled on an endpoint by specifying enable-mtom attribute to true on an endpoint element in <a class="link" href="jaxws-war.html#The_sun-jaxws.xml_File" target="_top">sun-jaxws.xml</a> deployment descriptor. </p><div class="informalexample"><pre class="programlisting"><span class="hl-directive" style="color: maroon"><?xml version="1.0" encoding="UTF-8"?></span> <span class="ReservedWord"><endpoints</span> <span class="Identifier">xmlns</span>=<span class="String">'http://java.sun.com/xml/ns/jax-ws/ri/runtime'</span> <span class="Identifier">version</span>=<span class="String">'2.0'</span><span class="ReservedWord">></span> <span class="ReservedWord"><endpoint</span> <span class="Identifier">name</span>=<span class="String">"Mtom"</span> <span class="Identifier">implementation</span>=<span class="String">"mtom.server.HelloImpl"</span> <span class="Identifier">url-pattern</span>=<span class="String">"/hello"</span> <span class="Identifier">enable-mtom</span>=<span class="String">"true"</span><span class="ReservedWord">/></span> <span class="ReservedWord"></endpoints></span></pre></div></li></ul></div><div class="itemizedlist"><ul class="itemizedlist" type="disc"><li class="listitem"><p>Enable using <code class="literal">@BindingType</code> on the endpoint (SEI) implementation class </p><div class="itemizedlist"><ul class="itemizedlist" type="circle"><li class="listitem"><p><code class="literal">@BindingType(value=javax.xml.ws.soap.SOAPBinding.SOAP11HTTP_MTOM_BINDING)</code> will enable MTOM on the deployed endpoint for SOAP 1.1 binding</p></li><li class="listitem"><p><code class="literal">@BindingType(value=javax.xml.ws.soap.SOAPBinding.SOAP12HTTP_MTOM_BINDING)</code> will enable MTOM on the deployed endpoint for SOAP 1.2 binding</p></li></ul></div></li></ul></div><p><span class="bold"><strong>Enabling MTOM on Client:</strong></span></p><div class="itemizedlist"><ul class="itemizedlist" type="disc"><li class="listitem"><p>To enable MTOM on client-side, pass javax.xml.ws.soap.MTOMFeature as WebServiceFeature parameter while crating the Proxy or Dispatch. Here is the code snippet from the client <a class="link" href="../samples/mtom/src/mtom/client/MtomApp.java" target="_top">MtomApp.java</a> of the mtom sample: </p><div class="itemizedlist"><ul class="itemizedlist" type="circle"><li class="listitem"><p>Hello port = new HelloService().getHelloPort(new MTOMFeature()); gives a proxy with MTOM enabled</p></li><li class="listitem"><p>javax.xml.ws.Service.createDispatch(....,new javax.xml.ws.soap.MTOMFeature()) gives a Dispatch instance with MTOM enabled</p></li></ul></div></li><li class="listitem"><p>JAX-WS 2.0 specification has defined API to enable and to check if the MTOM is enabled. </p><div class="itemizedlist"><ul class="itemizedlist" type="circle"><li class="listitem"><p>javax.xml.ws.soap.SOAPBinding.setMTOMEnabled(boolean enable) - enable or disable MTOM.</p></li><li class="listitem"><p>javax.xml.ws.soap.SOAPBinding.isMTOMEnabled() - returns true if MTOM is enabled otherwise false.</p></li></ul></div><div class="informalexample"><pre class="programlisting">Hello port = <span class="ReservedWord">new</span> HelloService.getHelloPort(); <span class="Comment">//get the binding and enable mtom</span> SOAPBinding binding = (SOAPBinding) ((BindingProvider) port).getBinding(); <span class="ReservedWord">boolean</span> mtomEnabled = binding.isMTOMEnabled(); binding.setMTOMEnabled(true);</pre></div></li></ul></div></div><div class="section" title="7.2.4. Attach vs In-line"><div class="titlepage"><div><div><h4 class="title" id="attach-vs-in-line">7.2.4. Attach vs In-line</h4></div></div></div><p>As defined by JAXB 2.0 specification <code class="literal">xs:base64Binary</code> and <code class="literal">xs:hexBinary</code> mapping to java is <code class="literal">byte[]</code>. JAX-WS implementation has set a threshold of 1KB of <code class="literal">byte[]</code> size. This threshold can be modified using implementation specific property <code class="literal">com.sun.xml.ws.developer.JAXWSProperties.MTOM_THRESHOLD_VALUE</code> in the <code class="literal">RequestContext</code> on the client side and in the <code class="literal">MessageContext</code> on the server side. If the <code class="literal">byte[]</code> that is being sent is less than this threshold (default is 1KB) then the binary data is base64 encoded by JAXB and in lined inside the SOAP Body otherwise the binary data is sent as attachment mime part in Multipart/Related package and XML infoset for the binary data is XOP encoded by JAXB </p><pre class="programlisting"><xop:Include href=...></pre><p>is used to reference the attachment. The XOP encoding and packaging is done as per described by the <a class="link" href="http://www.w3.org/TR/xop10/#xop_packages" target="_top">XOP packaging rules</a>. The href is the the <code class="literal">Content-ID</code> of the attachment and is encoded as per CID URI scheme defined in <a class="link" href="http://www.faqs.org/rfcs/rfc2111.html" target="_top">RFC 2111</a>. <code class="literal">xmime:contentType</code> attribute may appear on the element that includes binary data to indicate preferred media type as annotated on the corresponding schema.</p><div class="section" title="7.2.4.1. How to specify MTOM data Threshold"><div class="titlepage"><div><div><h5 class="title" id="mtom-threshold">7.2.4.1. How to specify MTOM data Threshold</h5></div></div></div><p>Default threshold value for MTOM feature is 0 bytes. You can set a threshold value for MTOM by using <code class="literal">@MTOM</code> annotation on server-side or using MTOMFeature on client-side. Let's say you set MTOM threshold as 3000, this serves as hint to JAX-WS when to send binary dat as attachments. In this case, JAX-WS will send any byte array in the message thats equal to or larger than 3KB as attachment and the corresponding XML infoset will be XOP encoded (will contain reference to this attachment)</p><div class="itemizedlist"><ul class="itemizedlist" type="disc"><li class="listitem"><p>On Server-side, <code class="literal">@MTOM(threshold=3000)</code></p></li><li class="listitem"><p>On Client-side, pass <code class="literal">MTOMFeature(3000)</code> as <code class="literal">WebServiceFeature</code> as mentioned in <a class="xref" href="#how-to-enable-mtom-in-jaxws-2-0" title="7.2.3. How to enable MTOM in JAX-WS 2.0">Section 7.2.3, “How to enable MTOM in JAX-WS 2.0”</a>, while creating the proxy/dispatch.</p></li></ul></div></div></div><div class="section" title="7.2.5. MTOM Samples"><div class="titlepage"><div><div><h4 class="title" id="mtom-samples">7.2.5. MTOM Samples</h4></div></div></div><div class="example"><a name="mtom"></a><p class="title"><b>Example 1. MTOM Sample - mtom</b></p><div class="example-contents"><p>This is SOAP 1.1 MTOM SampleThis is how the JAX-WS generated XOP packaged SOAP message looks on the wire:</p><div class="informalexample"><pre class="programlisting">Content-Type: Multipart/Related; <span class="bold"><strong>start-info="text/xml";</strong></span> <span class="bold"><strong>type="application/xop+xml";</strong></span> boundary="----=_Part_0_1744155.1118953559416" Content-Length: 3453 SOAPAction: "" ------=_Part_1_4558657.1118953559446 Content-Type: <span class="bold"><strong>application/xop+xml; type="text/xml";</strong></span> charset=utf-8 <soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/"> <soapenv:Body> <Detail xmlns="http://example.org/mtom/data"> <Photo>RHVrZQ==</Photo> <image> <span class="bold"><strong><xop:Include xmlns:xop="http://www.w3.org/2004/08/xop/include" href="cid:5aeaa450-17f0-4484-b845-a8480c363444@example.org"/></strong></span> </image> </Detail> </soapenv:Body> </soapenv:Envelope> ------=_Part_1_4558657.1118953559446 Content-Type: image/jpeg Content-ID: <5aeaa450-17f0-4484-b845-a8480c363444@example.org> ╪ α ►JFIF ☺☻ ☺ ☺ █ ♠♠ ♀¶ ♀♂♂♀↓↕‼☼¶↔→▼▲↔→∟∟ $.' ",#∟∟(7),01444▼'9=82<.342 █ C☺ ♀♂♀↑↑2!∟!22222222222222222222222222222222222222222222 222222 └ ) ¬♥☺" ☻◄☺♥◄☺ ─ ▼ ☺♣☺☺☺☺☺☺ ☺☻♥♦ ♂ ─ ╡► ☻☺♥♥☻♦♥♣♣♦♦ ☺}☺☻♥ ♦◄♣↕!1A♠‼Qa"q¶2?#B▒┴§R╤≡$3bré ▬↨↑↓→%&'()*456789:CDEFGHIJSTUVWXYZcdefghijstuvwxyzâäàåçêëèÆôöòûùÿÖÜóúñѪº¿⌐¬▓│┤╡╢╖╕╣║┬├─┼╞╟╚╔╩╥╙╘╒╓╫╪┘┌ßΓπΣσµτΦΘΩ±≥≤⌠⌡÷≈°∙· ─</pre></div><p>Above Photo is inlined binary data because its less than 1KB and image which is more than 1KB is sent as attachment. Here is the associated schema:</p><div class="informalexample"><pre class="programlisting"><span class="ReservedWord"><element</span> <span class="Identifier">name</span>=<span class="String">"Detail"</span> <span class="Identifier">type</span>=<span class="String">"types:DetailType"</span><span class="ReservedWord">/></span> <span class="ReservedWord"><complexType</span> <span class="Identifier">name</span>=<span class="String">"DetailType"</span><span class="ReservedWord">></span> <span class="ReservedWord"><sequence></span> <span class="Comment"><!-- mapped to byte[] --></span> <span class="ReservedWord"><element</span> <span class="Identifier">name</span>=<span class="String">"Photo"</span> <span class="Identifier">type</span>=<span class="String">"base64Binary"</span><span class="ReservedWord">/></span> <span class="Comment"><!-- mapped tojava.awt.Image --></span> <span class="ReservedWord"><element</span> <span class="Identifier">name</span>=<span class="String">"image"</span> <span class="Identifier">type</span>=<span class="String">"base64Binary"</span> <span class="bold"><strong>xmime:expectedContentTypes="image/jpeg"</strong></span>/> <span class="ReservedWord"></sequence></span> <span class="ReservedWord"></complexType></span></pre></div></div></div><br class="example-break"><div class="example"><a name="mtom-soap12"></a><p class="title"><b>Example 2. MTOM Sample - mtom-soap12</b></p><div class="example-contents"><p>This is SOAP 1.2 MTOM Sample. Here is how the JAX-WS generated soap message looks on the wire:</p><div class="informalexample"><pre class="programlisting"><element name="image" type="base64Binary" <span class="bold"><strong>xmime:expectedContentTypes="image/jpeg"</strong></span>/> Content-Type: Multipart/Related; <span class="bold"><strong>start-info="application/soap+xml"; type="application/xop+xml";</strong></span> boundary="----=_Part_0_1744155.1118960238280" Content-Length: 1946 SOAPAction: "" ------=_Part_1_4558657.1118960238320 Content-Type: <span class="bold"><strong>application/xop+xml</strong></span>; type="<span class="bold"><strong>application/soap+xml</strong></span>"; charset=utf-8 <soapenv:Envelope xmlns:soapenv="http://www.w3.org/2003/05/soap-envelope"> <soapenv:Body> <Detail xmlns="http://example.org/mtom/data"> <Photo>RHVrZQ==</Photo> <image> <span class="bold"><strong><xop:Include xmlns:xop="http://www.w3.org/2004/08/xop/include" href="cid:42a7ee0a-20ee-426b-a135-094d72bc138f@example.org"/></strong></span> </image> </Detail> </soapenv:Body> </soapenv:Envelope> ------=_Part_1_4558657.1118960238320 Content-Type: application/octet-stream Content-ID: <42a7ee0a-20ee-426b-a135-094d72bc138f@example.org> ╪ α ►JFIF ☺☻ ☺ ☺ █ ♠♠ ♀¶ ♀♂♂♀↓↕‼☼¶↔→▼▲↔→∟∟ $.' ",#∟∟(7),01444▼'9=82<.342 █ C☺ ♀♂♀↑↑2!∟!22222222222222222222222222222222222222222222 222222 └ ' )♥☺" ☻◄☺♥◄☺ ─ ▼ ☺♣☺☺☺☺☺☺ ☺☻♥♦ ♂ ─ ╡► ☻☺♥♥☻♦♥♣♣♦♦ ☺}☺☻♥ ♦◄♣↕!1A♠‼Qa"q¶2?#B▒┴§R╤≡$3bré ▬↨↑↓→%&'()*456789:CDEFGHIJSTUVWXYZcdefghijstuvwxyzâäàåçêëèÆôöòûùÿÖÜóúñѪº¿⌐¬▓│┤╡╢╖╕╣║┬├─┼╞╟╚╔╩╥╙╘╒╓╫╪┘┌ßΓπΣσµτΦΘΩ±≥≤⌠⌡÷≈°∙· ─ ▼☺ ♥☺☺☺☺☺☺☺☺☺ ☺☻♥♦</pre></div></div></div><br class="example-break"></div></div><div class="section" title="7.3. swaRef"><div class="titlepage"><div><div><h3 class="title" id="swaref">7.3. swaRef</h3></div></div></div><p><a class="link" href="http://www.ws-i.org/Profiles/AttachmentsProfile-1.0-2004-08-24.html" target="_top">WS-I Attachment Profile 1.0</a> defines mechanism to reference MIME attachment parts using <a class="link" href="http://www.ws-i.org/Profiles/AttachmentsProfile-1.0-2004-08-24.html#Referencing_Attachments_from_the_SOAP_Envelope" target="_top">swaRef</a>. In this mechanism the content of XML element of type <a class="link" href="http://ws-i.org/profiles/basic/1.1/xsd/" target="_top"><code class="literal">wsi:swaRef</code></a> is sent as MIME attachment and the element inside SOAP Body holds the reference to this attachment in the CID URI scheme as defined by <a class="link" href="http://www.faqs.org/rfcs/rfc2111.html" target="_top">RFC 2111</a>.</p><div class="section" title="7.3.1. swaRef in JAX-WS 2.0"><div class="titlepage"><div><div><h4 class="title" id="swaref-in-jaxws-2-0">7.3.1. swaRef in JAX-WS 2.0</h4></div></div></div><p>JAXB 2.0 defines mapping of <code class="literal">wsi:swaRef</code> schema type to javax.activation.DataHandler. An application will construct the DataHandler with the data and the appropriate MIME type and JAX-WS will coordinate with JAXB and SAAJ to send it as attachment MIME part.</p></div><div class="section" title="7.3.2. How to use swaRef"><div class="titlepage"><div><div><h4 class="title" id="how-to-use-swaref">7.3.2. How to use swaRef</h4></div></div></div><p>An XML element of type <code class="literal">wsi:swaRef</code> is mapped to a DataHandler and is sent as attachment over the wire. For example,</p><div class="informalexample"><pre class="programlisting"><span class="ReservedWord"><element</span> <span class="Identifier">name</span>=<span class="String">"claimForm"</span> <span class="Identifier">type</span>=<span class="String">"</span><span class="bold"><strong>wsi:swaRef</strong></span>" xmlns:wsi="http://ws-i.org/profiles/basic/1.1/xsd"/></pre></div><p>will be sent over the wire as :</p><div class="informalexample"><pre class="programlisting">Content-Type: Multipart/Related; start-info="text/xml"; type="application/xop+xml"; boundary="----=_Part_4_32542424.1118953563492" Content-Length: 1193 SOAPAction: "" ------=_Part_5_32550604.1118953563502 Content-Type: application/xop+xml; type="text/xml"; charset=utf-8 <soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/"> <soapenv:Body> <claimForm xmlns="http://example.org/mtom/data"> <span class="bold"><strong>cid:b0a597fd-5ef7-4f0c-9d85-6666239f1d25@example.jaxws.sun.com</strong></span> </claimForm> </soapenv:Body> </soapenv:Envelope> ------=_Part_5_32550604.1118953563502 Content-Type: application/xml Content-ID: <<span class="bold"><strong>b0a597fd-5ef7-4f0c-9d85-6666239f1d25@example.jaxws.sun.com</strong></span>> <?xml version="1.0" encoding="UTF-8"?> <application xmlns="http://java.sun.com/xml/ns/j2ee" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:schemaLocaption="http://java.sun.com/xml/ns/j2ee http://java.sun.com/xml/ns/j2ee/application_1_4.xsd" version="1.4"> <display-name>Simple example of application</display-name> <description>Simple example</description> <module> <ejb>ejb1.jar</ejb> </module> <module> <ejb>ejb2.jar</ejb> </module> <module> <web> <web-uri>web.war</web-uri> <context-root>web</context-root> </web> </module> </application></pre></div></div><div class="section" title="7.3.3. swaRef Sample"><div class="titlepage"><div><div><h4 class="title" id="swaref-samples">7.3.3. swaRef Sample</h4></div></div></div><p>Refer to <span class="application">swaRef</span> sample <code class="literal">testSwaRef()</code> method in <a class="link" href="../samples/mime/src/mime/client/MimeApp.java" target="_top">MimeApp.java.</a></p></div></div></div><div lang="en" class="section" title="8. SOAP 1.2"><div class="titlepage"><div><div><h2 class="title" style="clear: both" id="users-guide-soap-1-2">8. SOAP 1.2</h2></div></div></div><div class="section" title="8.1. Introduction"><div class="titlepage"><div><div><h3 class="title" id="section-94073181229507">8.1. Introduction</h3></div></div></div><p>The default binding supported by JAX-WS 2.0 is SOAP 1.1 over HTTP. With this release we have added <span class="bold"><strong>SOAP 1.2 binding over HTTP</strong></span> support into JAX-WS 2.0. This document describes how SOAP 1.2 binding can be applied to an endpoint and how it can be used on the client side in the case of proxy port. To enable SOAP 1.2 support in the <code class="literal">Dispatch</code> client please refer to the <code class="literal">Dispatch</code> documents.</p></div><div class="section" title="8.2. SOAP 1.2 Endpoint"><div class="titlepage"><div><div><h3 class="title" id="section-627071591090577">8.2. SOAP 1.2 Endpoint</h3></div></div></div><p>To enable SOAP 1.2 binding on an endpoint. You would need to set binding attribute value in <a class="link" href="jaxws-war.html#The_sun-jaxws.xml_File" target="_top">sun-jaxws.xml</a> to SOAP 1.2 HTTP binding value as specified by <code class="literal">javax.xml.ws.soap.SOAPBinding.SOAP12HTTP_BINDING</code> which is: "<a class="link" href="http://www.w3.org/2003/05/soap/bindings/HTTP/" target="_top">http://www.w3.org/2003/05/soap/bindings/HTTP/</a>" or "<a class="link" href="http://java.sun.com/xml/ns/jaxws/2003/05/soap/bindings/HTTP/" target="_top">http://java.sun.com/xml/ns/jaxws/2003/05/soap/bindings/HTTP/</a>"</p><p>Here is the <code class="filename">sun-jaxws.xml</code> from <span class="application">fromjava-soap1.2</span> sample:</p><div class="informalexample"><pre class="programlisting"><span class="hl-directive" style="color: maroon"><?xml version="1.0" encoding="UTF-8"?></span> <span class="ReservedWord"><endpoints</span> <span class="Identifier">xmlns</span>=<span class="String">"http://java.sun.com/xml/ns/jax-ws/ri/runtime"</span> <span class="Identifier">version</span>=<span class="String">"2.0"</span><span class="ReservedWord">></span> <span class="ReservedWord"><endpoint</span> <span class="Identifier">name</span>=<span class="String">"fromjava-soap12"</span> <span class="Identifier">implementation</span>=<span class="String">"fromjava_soap12.server.AddNumbersImpl"</span> <span class="Identifier">binding</span>=<span class="String">"http://java.sun.com/xml/ns/jaxws/2003/05/soap/bindings/HTTP/ url-pattern="</span><span class="ReservedWord">/a</span>ddnumbers"/> <span class="ReservedWord"></endpoints></span></pre></div><p>JAX-WS 2.0 generates WSDL on the fly when requested by a client. If this binding attribute is present and is equal to SOAP 1.2 HTTP binding WSDL with SOAP 1.2 binding is generated. Based on this binding descriptor JAX-WS runtime configures itself to handle SOAP 1.2 messages.</p><p>Notice that the binding id "<a class="link" href="http://java.sun.com/xml/ns/jaxws/2003/05/soap/bindings/HTTP/" target="_top">http://java.sun.com/xml/ns/jaxws/2003/05/soap/bindings/HTTP/</a>" is not a standard binding id. If you use SOAP 1.2 binding id "<a class="link" href="http://www.w3.org/2003/05/soap/bindings/HTTP/" target="_top">http://www.w3.org/2003/05/soap/bindings/HTTP/</a>" defined by JAX-WS, still the endpoint is configured to use SOAP 1.2 binding, except that a wsdl will not be generated on the fly.</p><p>Alternatively, you can specify the binding through <code class="literal">@BindingType</code> annotation in the implementation class to use SOAP 1.2 binding. Here is an example from the <span class="application">fromjava_soap12</span> sample.</p><div class="informalexample"><pre class="programlisting"><span class="Annotation">@WebService</span> <span class="Annotation">@BindingType(value = "http://java.sun.com/xml/ns/jaxws/2003/05/soap/bindings/HTTP/")</span> <span class="ReservedWord">public</span> <span class="ReservedWord">class</span> AddNumbersImpl { <span class="Comment">/** * @param number1 * @param number2 * @return The sum * @throws AddNumbersException if any of the numbers to be added is * negative. */</span> <span class="ReservedWord">public</span> <span class="ReservedWord">int</span> addNumbers(<span class="ReservedWord">int</span> number1, <span class="ReservedWord">int</span> number2) <span class="ReservedWord">throws</span> AddNumbersException { <span class="ReservedWord">if</span> (number1 < <span class="Numeric">0</span> || number2 < <span class="Numeric">0</span>) { <span class="ReservedWord">throw</span> <span class="ReservedWord">new</span> AddNumbersException(<span class="String">"Negative number cant be added "</span> + <span class="String">"!"</span>, <span class="String">"Numbers: "</span> + number1 + <span class="String">", "</span> + number2); } <span class="ReservedWord">return</span> number1 + number2; } }</pre></div><p>The commandline <a class="xref" href="#tools-wsgen" title="4. wsgen"><span class="command"><strong>wsgen</strong></span></a> and the equivalent ant task can be used to generate SOAP 1.1 (default) or SOAP 1.2 WSDL. The binding information should be passed using <code class="literal">-wsdl:protocol</code> switch.</p></div><div class="section" title="8.3. Client"><div class="titlepage"><div><div><h3 class="title" id="section-696486497021005">8.3. Client</h3></div></div></div><p>On the client there is nothing special that has to be done. JAX-WS runtime looks into the WSDL to determine the binding being used and configures itself accordingly. <a class="xref" href="#tools-wsimport" title="2. wsimport"><span class="command"><strong>wsimport</strong></span></a> command line tool or <span class="command"><strong>wsimport</strong></span> ant task can be used to import the WSDL and to generated the client side artifacts.</p></div><div class="section" title="8.4. Samples"><div class="titlepage"><div><div><h3 class="title" id="section-7037754311590527">8.4. Samples</h3></div></div></div><p>There are 2 samples bundled with this release</p><div class="itemizedlist"><ul class="itemizedlist" type="disc"><li class="listitem"><p><span class="application">fromwsdl-soap12</span> - shows SOAP 1.2 endpoint developed starting from wsdl</p></li><li class="listitem"><p><span class="application">fromjava-soap12</span> - shows SOAP 1.2 endpoint developed starting from Java</p></li></ul></div><p>A SOAP 1.2 message generated by JAX-WS:</p><div class="informalexample"><pre class="programlisting">Content-Type: application/soap+xml; charset=utf-8 Content-Length: 178 SOAPAction: "" <soapenv:Envelope xmlns:soapenv="http://www.w3.org/2003/05/soap-envelope"> <soapenv:Body> <addNumbers xmlns="http://duke.example.org"> <arg0>-10</arg0> <arg1>20</arg1> </addNumbers> </soapenv:Body> </soapenv:Envelope></pre></div><p>A SOAP 1.2 Fault message generated by JAX-WS:</p><div class="informalexample"><pre class="programlisting">Content-Type:application/soap+xml; charset=utf-8 Content-Length: 476 SOAPAction: "" <soapenv:Envelope xmlns:soapenv="http://www.w3.org/2003/05/soap-envelope"> <soapenv:Body> <soapenv:Fault> <soapenv:Code> <soapenv:Value> soapenv:Sender </soapenv:Value> </soapenv:Code> <soapenv:Reason> <soapenv:Text xml:lang="en"> Negative number cant be added! </soapenv:Text> </soapenv:Reason> <soapenv:Detail> <AddNumbersFault xmlns="http://duke.example.org"> <faultInfo>Numbers: -10, 20</faultInfo> <message>Negative number cant be added!</message> </AddNumbersFault> </soapenv:Detail> </soapenv:Fault> </soapenv:Body> </soapenv:Envelope></pre></div></div></div><div lang="en" class="section" title="9. WSDL Customization"><div class="titlepage"><div><div><h2 class="title" style="clear: both" id="users-guide-wsdl-customization">9. WSDL Customization</h2></div></div></div><p>The JAX-WS 2.0 specification defines standard XML-based customization for WSDL to Java mapping and to control certain features. These customizations, or <span class="emphasis"><em>binding declarations</em></span>, can customize almost all WSDL components that can be mapped to Java, such as the service endpoint interface class, method name, parameter name, exception class, etc. The other important thing you can do with these binding declarations is control certain features, such as asynchrony, provider, wrapper style, and additional headers. For example, a client application can enable asynchrony for a particular operation in a <code class="literal">portType</code> or all operations in a <code class="literal">portType</code> or all <code class="literal">portType</code> operations defined in the WSDL file.</p><p>The JAX-RPC 1.1 specification did not define a standard customization architecture. However JAX-RPC 1.x SI had limited WSDL to Java customization support. It allowed a JAX-RPC 1.x application to:</p><div class="itemizedlist"><ul class="itemizedlist" type="disc"><li class="listitem"><p>Define a package where Java artifacts mapped from a WSDL file will be generated.</p></li><li class="listitem"><p>Customize the package for the value classes mapped from the imported XML schema by the WSDL document.</p></li><li class="listitem"><p>Customize handler chains.</p></li></ul></div><p>But these customizations were not portable and could not be used across other JAX-RPC implementations. JAX-WS RI 2.2.7 provides complete support for all the binding declarations defined by the specification.</p><div class="section" title="9.1. Declaring Customizations"><div class="titlepage"><div><div><h3 class="title" id="declaring-customizations">9.1. Declaring Customizations</h3></div></div></div><p>All the binding declaration elements live in <code class="literal">http://java.sun.com/xml/ns/jaxws</code> namespace. There are two ways to specify binding declarations. In the first approach, all binding declarations pertaining to a given WSDL document are grouped together in a standalone document, called an <span class="emphasis"><em>external binding file</em></span>. The second approach consists of embedding binding declarations directly inside a WSDL document. In either case, the <code class="literal">jaxws:bindings</code> element is used as a container for JAX-WS binding declarations. The <code class="literal">jaxws</code> prefix maps to the <code class="literal">http://java.sun.com/xml/ns/jaxws</code> namespace.</p><div class="section" title="9.1.1. External Binding Declaration"><div class="titlepage"><div><div><h4 class="title" id="external-binding-declaration">9.1.1. External Binding Declaration</h4></div></div></div><p>External binding files are semantically equivalent to embedded binding declarations. When <span class="command"><strong>wsimport</strong></span> processes the WSDL document for which there is an external binding file, it internalizes the binding declarations defined in the external binding file on the nodes in the WSDL document they target using the <code class="literal">wsdlLocation</code> attribute. The embedded binding declarations can exist in a WSDL file and an external binding file targeting that WSDL, but <span class="command"><strong>wsimport</strong></span> may give an error if, upon embedding the binding declarations defined in the external binding files, the resulting WSDL document contains conflicting binding declarations.</p><div class="section" title="9.1.1.1. Root Binding Element"><div class="titlepage"><div><div><h5 class="title" id="root-binding-element">9.1.1.1. Root Binding Element</h5></div></div></div><p>The <code class="literal">jaxws:bindings</code> declaration appears as the root of all other binding declarations. This top-level <code class="literal">jaxws:bindings</code> element must specify the location of the WSDL file as a URI in the value of <code class="literal">wsdlLocation</code> attribute.</p><p>Its important that the <code class="literal">wsdlLocation</code> attribute on the root <code class="literal">jaxws:bindings</code> declaration is same as the WSDL location URI given to <span class="command"><strong>wsimport</strong></span>.</p><div class="informalexample"><pre class="programlisting"><span class="ReservedWord"><jaxws:bindings</span> <span class="Identifier">wsdlLocation</span>=<span class="String">"http://localhost:8080/jaxws-external-customize/addnumbers?WSDL"</span> <span class="Identifier">jaxws:xmlns</span>=<span class="String">"http://java.sun.com/xml/ns/jaxws"</span><span class="ReservedWord">></span> ... <span class="ReservedWord"></jaxws:bindings></span></pre></div></div><div class="section" title="9.1.1.2. Child Binding Elements"><div class="titlepage"><div><div><h5 class="title" id="child-binding-elements">9.1.1.2. Child Binding Elements</h5></div></div></div><p>The root <code class="literal">jaxws:bindings</code> element may contain child <code class="literal">jaxws:bindings</code> elements. In this case the child <code class="literal">jaxws:bindings</code> element must carry an XPath expression in the node attribute to refer to the WSDL node it customizes.</p><p>Here is an excerpt from an external binding file <a class="link" href="../samples/external-customize/etc/custom-client.xml" target="_top">custom-client.xml</a> in the <code class="literal">external-customize</code> sample:</p><div class="informalexample"><pre class="programlisting"><span class="ReservedWord"><jaxws:bindings</span> <span class="Identifier">wsdlLocation</span>=<span class="String">"http://localhost:8080/jaxws-external-customize/addnumbers?WSDL"</span> <span class="Identifier">jaxws:xmlns</span>=<span class="String">"http://java.sun.com/xml/ns/jaxws"</span><span class="ReservedWord">></span> <span class="ReservedWord"><jaxws:bindings</span> <span class="Identifier">node</span>=<span class="String">"wsdl:definitions"</span> <span class="Identifier">xmlns:wsdl</span>=<span class="String">"http://schemas.xmlsoap.org/wsdl/"</span><span class="ReservedWord">></span> <span class="ReservedWord"><jaxws:package</span> <span class="Identifier">name</span>=<span class="String">"external_customize.client"</span><span class="ReservedWord">/></span> ... <span class="ReservedWord"></jaxws:bindings></span> <span class="ReservedWord"></jaxws:bindings></span></pre></div><p>In this example the child <code class="literal">jaxws:bindings</code> applies package customization. An XPath expression in the node attribute refers to the root node of the WSDL document, which is <code class="literal">wsdl:definitions</code> and declares the package <code class="literal">external_customize.client</code> for all the generated Java classes mapped from the WSDL file.</p></div></div><div class="section" title="9.1.2. Embedded Binding Declarations"><div class="titlepage"><div><div><h4 class="title" id="embedded-binding-declarations">9.1.2. Embedded Binding Declarations</h4></div></div></div><p>Embedded binding declarations directly inside the WSDL follow different rules compared to the binding declarations declared in the external binding file. Here are some important facts and rules as defined in the JAX-WS 2.0 specification:</p><div class="itemizedlist"><ul class="itemizedlist" type="disc"><li class="listitem"><p>An embedded binding declaration is specified by using the <code class="literal">jaxws:bindings</code> element as a WSDL extension inside the wsdl node that is to be customized.</p></li><li class="listitem"><p>When a <code class="literal">jaxws:bindings</code> element is used as a WSDL extension, the <code class="literal">jaxws:bindings</code> element should not have node attribute (the node attribute is only used in external customization file to scope the custmization to a wsdl element).</p></li><li class="listitem"><p>A binding declaration embedded in a WSDL can only affect the WSDL element it extends.</p></li></ul></div><p>Here's an example of embedded binding declarations in the WSDL <code class="literal">AddNumbers.wsdl</code> from the <code class="literal">inline-customize</code> sample:</p><div class="informalexample"><pre class="programlisting"><span class="ReservedWord"><wsdl:portType</span> <span class="Identifier">name</span>=<span class="String">"AddNumbersImpl"</span><span class="ReservedWord">></span> <span class="Comment"><!-- wsdl:portType customizations --></span> <span class="ReservedWord"><jaxws:bindings</span> <span class="Identifier">xmlns:jaxws</span>=<span class="String">"http://java.sun.com/xml/ns/jaxws"</span><span class="ReservedWord">></span> <span class="Comment"><!-- rename the generated SEI from AddNumbersImpl to MathUtil --></span> <span class="ReservedWord"><jaxws:class</span> <span class="Identifier">name</span>=<span class="String">"MathUtil"</span><span class="ReservedWord">/></span> ... <span class="ReservedWord"></jaxws:bindings></span> <span class="ReservedWord"><wsdl:operation</span> <span class="Identifier">name</span>=<span class="String">"addNumber"</span><span class="ReservedWord">></span> ... <span class="ReservedWord"></wsdl:operation></span> <span class="ReservedWord"></wsdl:portType></span></pre></div><p>The above WSDL file excerpt shows the <code class="literal">wsdl:portType</code> customization. <code class="literal">jaxws:bindings</code> appears as extension element of <code class="literal">portType</code>. It customizes the class name of the generated service endpoint interface. Without this customization, or by default, the service endpoint interface class is named after the <code class="literal">wsdl:portType</code> name. The binding declaration <code class="literal">jaxws:class</code> customizes the generated class to be named <code class="literal">MathUtil</code> instead of <code class="literal">AddNumberImpl</code>.</p><p>In the following section, all the possible standard customizations and their scope is described. Global customizations can be specified under <wsdl:definitions> element and other customizations can be specified under the node of its scope.</p></div></div><div class="section" title="9.2. Standard Customizations"><div class="titlepage"><div><div><h3 class="title" id="standard-customizations">9.2. Standard Customizations</h3></div></div></div><p>This section provides the details of all the possible WSDL binding declarations.</p><div class="section" title="9.2.1. Global bindings"><div class="titlepage"><div><div><h4 class="title" id="global-bindings">9.2.1. Global bindings</h4></div></div></div><p>The global customizations are the customizations that applies to the entire scope of <code class="literal">wsdl:definition</code> in the wsdl referenced by the root <code class="literal">jaxws:bindings@wsdlLocation.Following</code> customizations have the global scopes:</p><pre class="programlisting"><span class="ReservedWord"><jaxws:package</span> <span class="Identifier">name</span>=<span class="String">"..."</span><span class="ReservedWord">/></span></pre><pre class="programlisting"><span class="ReservedWord"><jaxws:enableWrapperStyle/></span></pre><pre class="programlisting"><span class="ReservedWord"><jaxws:enableAsyncMapping/></span></pre><p>These can appear as direct child of the <a class="xref" href="#root-binding-element" title="9.1.1.1. Root Binding Element">Root Binding Element</a> declarations in the external customization file. For example:</p><div class="informalexample"><pre class="programlisting"><span class="ReservedWord"><bindings</span> <span class="Identifier">xmlns:wsdl</span>=<span class="String">"http://schemas.xmlsoap.org/wsdl/"</span> <span class="Identifier">wsdlLocation</span>=<span class="String">"http://localhost:8080/jaxws-external-customize/addnumbers?WSDL"</span> <span class="Identifier">xmlns</span>=<span class="String">"http://java.sun.com/xml/ns/jaxws"</span><span class="ReservedWord">></span> <span class="ReservedWord"><package</span> <span class="Identifier">name</span>=<span class="String">"external_customize.client"</span><span class="ReservedWord">/></span> <span class="ReservedWord"><enableWrapperStyle></span>true<span class="ReservedWord"></enableWrapperStyle></span> <span class="ReservedWord"><enableAsyncMapping></span>false<span class="ReservedWord"></enableAsyncMapping></span> <span class="ReservedWord"></bindings></span></pre></div><p>In embedded usage, the global customization can be specified under <code class="literal"><wsdl:definitions></code> node of the wsdl.</p></div><div class="section" title="9.2.2. Package Customization"><div class="titlepage"><div><div><h4 class="title" id="package-customization">9.2.2. Package Customization</h4></div></div></div><p>By default <span class="command"><strong>wscompile</strong></span> generates WSDL artifacts in a package computed from the WSDL <code class="literal">targetNamespace</code>. For example, a WSDL file with the <code class="literal">targetNamespace</code> <code class="literal">http://duke.example.org</code> without any package customization will be mapped to the <code class="literal">org.duke</code> package. To customize the default package mapping you would use a <code class="literal">jaxws:package</code> customization on the <code class="literal">wsdl:definitions</code> node or it can directly appear inside the top level bindings element.</p><p>An important thing to note is that <code class="option">-p</code> option on commandline <span class="command"><strong>wsimport.sh</strong></span> tool (package attribute on <span class="command"><strong>wsimport</strong></span> ant task), overrides the <code class="literal">jaxws:package</code> customization,it also overrides the schema package customization specified using jaxb schema customization.</p><p>For example:</p><div class="informalexample"><pre class="programlisting"><span class="ReservedWord"><bindings</span> <span class="Identifier">xmlns:wsdl</span>=<span class="String">"http://schemas.xmlsoap.org/wsdl/"</span> <span class="Identifier">wsdlLocation</span>=<span class="String">"http://localhost:8080/jaxws-external-customize/addnumbers?WSDL"</span> <span class="Identifier">xmlns</span>=<span class="String">"http://java.sun.com/xml/ns/jaxws"</span><span class="ReservedWord">></span> <span class="ReservedWord"><package</span> <span class="Identifier">name</span>=<span class="String">"external_customize.client"</span><span class="ReservedWord">></span> <span class="ReservedWord"><javadoc></span>Mathutil package<span class="ReservedWord"></javadoc></span> <span class="ReservedWord"></package></span> ... <span class="ReservedWord"></bindings></span></pre></div><p>or</p><div class="informalexample"><pre class="programlisting"><span class="ReservedWord"><bindings</span> <span class="Identifier">xmlns:wsdl</span>=<span class="String">"http://schemas.xmlsoap.org/wsdl/"</span> <span class="Identifier">wsdlLocation</span>=<span class="String">"http://localhost:8080/jaxws-external-customize/addnumbers?WSDL"</span> <span class="Identifier">xmlns</span>=<span class="String">"http://java.sun.com/xml/ns/jaxws"</span><span class="ReservedWord">></span> <span class="ReservedWord"><bindings</span> <span class="Identifier">node</span>=<span class="String">"wsdl:definitions"</span><span class="ReservedWord">></span> <span class="ReservedWord"><package</span> <span class="Identifier">name</span>=<span class="String">"external_customize.client"</span><span class="ReservedWord">></span> <span class="ReservedWord"><javadoc></span>Mathutil package<span class="ReservedWord"></javadoc></span> <span class="ReservedWord"></package></span> ... <span class="ReservedWord"></bindings></span> ... <span class="ReservedWord"></bindings></span></pre></div></div><div class="section" title="9.2.3. Wrapper Style"><div class="titlepage"><div><div><h4 class="title" id="wrapper-style">9.2.3. Wrapper Style</h4></div></div></div><p><span class="command"><strong>wsimport</strong></span> by default applies wrapper style rules to the abstract operation defined in the <code class="literal">wsdl:portType</code>, and if an operation qualifies the Java method signature is generated accordingly. Wrapper style Java method generation can be disabled by using <code class="literal">jaxws:enableWrapperStyle</code>.</p><p><code class="literal">jaxws:enableWrapperStyle</code> can appear on the toplevel bindings element (with <code class="literal">@wsdlLocation</code> attribute), it can also appear on the following target nodes:</p><div class="itemizedlist"><ul class="itemizedlist" type="disc"><li class="listitem"><p><code class="literal">wsdl:definitions</code> global scope, applies to all the <code class="literal">wsdl:operations</code> of all <code class="literal">wsdl:portType</code> attributes</p></li><li class="listitem"><p><code class="literal">wsdl:portType</code> applies to all the <code class="literal">wsdl:operations</code> in the <code class="literal">portType</code></p></li><li class="listitem"><p><code class="literal">wsdl:operation</code> applies to only this <code class="literal">wsdl:operation</code></p></li></ul></div><p>For example:</p><div class="informalexample"><pre class="programlisting"><span class="ReservedWord"><bindings</span> <span class="Identifier">xmlns:wsdl</span>=<span class="String">"http://schemas.xmlsoap.org/wsdl/"</span> <span class="Identifier">wsdlLocation</span>=<span class="String">"http://localhost:8080/jaxws-external-customize/addnumbers?WSDL"</span> <span class="Identifier">xmlns</span>=<span class="String">"http://java.sun.com/xml/ns/jaxws"</span><span class="ReservedWord">></span> <span class="Comment"><!-- applies to wsdl:definitions node, that would mean the entire wsdl --></span> <span class="ReservedWord"><enableWrapperStyle></span>true<span class="ReservedWord"></enableWrapperStyle></span> <span class="Comment"><!-- wsdl:portType operation customization --></span> <span class="ReservedWord"><bindings</span> <span class="Identifier">node</span>=<span class="String">"wsdl:definitions/wsdl:portType[@name='AddNumbersImpl']/wsdl:operation[@name='addNumbers']"</span><span class="ReservedWord">></span> <span class="Comment"><!-- change java method name from addNumbers() to add() --></span> <span class="ReservedWord"><enableWrapperStyle></span>false<span class="ReservedWord"></enableWrapperStyle></span> ... <span class="ReservedWord"></bindings></span> ... <span class="ReservedWord"></bindings></span></pre></div><p>In the example above the wrapper style is disabled for the <code class="literal">addNumbers</code> operation in <code class="literal">AddNumbersImpl</code> <code class="literal">portType</code> .This is because <span class="command"><strong>wsimport</strong></span> processes this binding in the following order: first <code class="literal">wsdl:operation</code>, then its parent <code class="literal">wsdl:portType</code>, and finally <code class="literal">wsdl:definitions</code>. Here <code class="literal">wsdl:operation</code> <code class="literal">addNumbers</code> has this customization disabled so this is what is applied by <span class="command"><strong>wsimport</strong></span> to generate a bare Java method signature.</p></div><div class="section" title="9.2.4. Asynchrony"><div class="titlepage"><div><div><h4 class="title" id="asynchrony">9.2.4. Asynchrony</h4></div></div></div><p>A client application can use the <code class="literal">jaxws:enableAsyncMapping</code> binding declaration so that <span class="command"><strong>wsimport</strong></span> will generate async polling and callback operations along with the normal synchronous method when it compiles a WSDL file.</p><p>It has the same target nodes as the wrapper style binding declaration described above in section 2.2.</p><div class="itemizedlist"><ul class="itemizedlist" type="disc"><li class="listitem"><p><code class="literal">wsdl:definitions</code> or toplevel bindings element: global scope, applies to all the <code class="literal">wsdl:operations</code> of all <code class="literal">wsdl:portType</code></p></li><li class="listitem"><p><code class="literal">wsdl:portType</code> applies to all the <code class="literal">wsdl:operations</code> in the <code class="literal">portType</code></p></li><li class="listitem"><p><code class="literal">wsdl:operation</code> applies to only this <code class="literal">wsdl:operation</code></p></li></ul></div><p>Example :</p><div class="informalexample"><pre class="programlisting"><span class="ReservedWord"><bindings</span> <span class="Identifier">xmlns:wsdl</span>=<span class="String">"http://schemas.xmlsoap.org/wsdl/"</span> <span class="Identifier">wsdlLocation</span>=<span class="String">"http://localhost:8080/jaxws-external-customize/addnumbers?WSDL"</span> <span class="Identifier">xmlns</span>=<span class="String">"http://java.sun.com/xml/ns/jaxws"</span><span class="ReservedWord">></span> <span class="Comment"><!-- applies to wsdl:definitions node, that would mean the entire wsdl --></span> <span class="ReservedWord"><enableAsyncMapping></span>false<span class="ReservedWord"></enableAsyncMapping></span> <span class="Comment"><!-- wsdl:portType operation customization --></span> <span class="ReservedWord"><bindings</span> <span class="Identifier">node</span>=<span class="String">"wsdl:definitions/wsdl:portType[@name='AddNumbersImpl']/wsdl:operation[@name='addNumbers']"</span><span class="ReservedWord">></span> <span class="Comment"><!-- change java method name from addNumbers() to add() --></span> <span class="ReservedWord"><enableAsyncMapping></span>true<span class="ReservedWord"></enableAsyncMapping></span> ... <span class="ReservedWord"></bindings></span> ... <span class="ReservedWord"></bindings></span></pre></div><p>In the above example <span class="command"><strong>wsimport</strong></span> will generate async polling and callback methods for the <code class="literal">addNumbers</code> operation. In the <code class="literal">wsdl:definition</code> node, the async customization is disabled or false but the <code class="literal">wsdl:operation</code> node has it enabled or true, and so <span class="command"><strong>wsimport</strong></span> generates the async methods of the <code class="literal">wsdl:operation</code> <code class="literal">addNumbers</code>.</p><p>This is how the generated signatures look (annotations are removed from synchronous method for reading simplicity):</p><div class="informalexample"><pre class="programlisting"><span class="Comment">//synchronous method</span> <span class="ReservedWord">public</span> <span class="ReservedWord">int</span> addNumbers(<span class="ReservedWord">int</span> number1, <span class="ReservedWord">int</span> number2) <span class="ReservedWord">throws</span> org.duke.AddNumbersFault_Exception, java.rmi.RemoteException; <span class="Comment">//async polling Method</span> <span class="ReservedWord">public</span> Response<AddNumbersResponse> addNumbers(<span class="ReservedWord">int</span> number1, <span class="ReservedWord">int</span> number2); <span class="Comment">//async callback Method</span> <span class="ReservedWord">public</span> Future<?> addNumbers(<span class="ReservedWord">int</span> number1, <span class="ReservedWord">int</span> number2, AsyncHandler<AddNumbersResponse>); ...</pre></div></div><div class="section" title="9.2.5. The Provider Interface"><div class="titlepage"><div><div><h4 class="title" id="provider-interface">9.2.5. The Provider Interface</h4></div></div></div><p>By default the value of <code class="literal">jaxws:provider</code> binding is false. That is, provider interface generation is disabled. In order to mark a port as provider interface this binding declaration should refer to the <code class="literal">wsdl:port</code> node using an XPath expression. Please note that provider binding declaration applies only when developing a server starting from a WSDL file.</p></div><div class="section" title="9.2.6. Class Customization"><div class="titlepage"><div><div><h4 class="title" id="class-customization">9.2.6. Class Customization</h4></div></div></div><p>The generated class for <code class="literal">wsdl:portType</code>, <code class="literal">wsdl:fault</code>, <code class="literal">soap:headerfault</code>, and <code class="literal">wsdl:server</code> can be customized using the <code class="literal">jaxws:class</code> binding declaration. Refer to the external binding declaration file <code class="literal">custom-client.xml</code> in the <code class="literal">external-customize</code> sample.</p><div class="section" title="9.2.6.1. The Service Endpoint Interface Class"><div class="titlepage"><div><div><h5 class="title" id="sei-class">9.2.6.1. The Service Endpoint Interface Class</h5></div></div></div><p><span class="command"><strong>wscompile</strong></span> will generate the service endpoint interface class <code class="literal">MathUtil</code> instead of the default <code class="literal">AddNumbersImpl</code> in this example:</p><div class="informalexample"><pre class="programlisting"><span class="Comment"><!-- wsdl:portType customization --></span> <span class="ReservedWord"><bindings</span> <span class="Identifier">node</span>=<span class="String">"wsdl:definitions/wsdl:portType[@name='AddNumbersImpl']"</span><span class="ReservedWord">></span> <span class="Comment"><!-- change the generated SEI class --></span> <span class="ReservedWord"><class</span> <span class="Identifier">name</span>=<span class="String">"MathUtil"</span><span class="ReservedWord">></span> <span class="ReservedWord"><javadoc></span>Perform mathematical computations<span class="ReservedWord"></javadoc></span> <span class="ReservedWord"></class></span> <span class="ReservedWord"></bindings></span></pre></div></div><div class="section" title="9.2.6.2. The Exception Class"><div class="titlepage"><div><div><h5 class="title" id="exception-class">9.2.6.2. The Exception Class</h5></div></div></div><p><span class="command"><strong>wsimport</strong></span> will generate the <code class="literal">MathUtilException</code> class instead of the default <code class="literal">AddNumbersExeption</code> in this example:</p><div class="informalexample"><pre class="programlisting"><span class="Comment"><!-- change the generated exception class name --></span> <span class="ReservedWord"><bindings</span> <span class="Identifier">node</span>=<span class="String">"wsdl:definitions/wsdl:portType[@name='AddNumbersImpl']/wsdl:operation[@name='addNumbers']/wsdl:fault[@name='AddNumbersException']"</span><span class="ReservedWord">></span> <span class="ReservedWord"><class</span> <span class="Identifier">name</span>=<span class="String">"MathUtilException"</span><span class="ReservedWord">></span> <span class="ReservedWord"><javadoc></span>Exception generated during computation<span class="ReservedWord"></javadoc></span> <span class="ReservedWord"></class></span> <span class="ReservedWord"></bindings></span></pre></div></div><div class="section" title="9.2.6.3. The Service Class"><div class="titlepage"><div><div><h5 class="title" id="service-class">9.2.6.3. The Service Class</h5></div></div></div><p><span class="command"><strong>wsimport</strong></span> will generate <code class="literal">MathUtilService</code> instead of the default <code class="literal">AddNumbersService</code> in this example:</p><div class="informalexample"><pre class="programlisting"><span class="Comment"><!-- wsdl:service customization --></span> <span class="ReservedWord"><bindings</span> <span class="Identifier">node</span>=<span class="String">"wsdl:definitions/wsdl:service[@name='AddNumbersService']"</span><span class="ReservedWord">></span> <span class="Comment"><!-- change the generated service class --></span> <span class="ReservedWord"><class</span> <span class="Identifier">name</span>=<span class="String">"MathUtilService"</span><span class="ReservedWord">></span> <span class="ReservedWord"><javadoc></span>Service to perform mathematical computations<span class="ReservedWord"></javadoc></span> <span class="ReservedWord"></class></span> <span class="ReservedWord"></bindings></span></pre></div></div></div><div class="section" title="9.2.7. Java Method Customization"><div class="titlepage"><div><div><h4 class="title" id="java-method-customization">9.2.7. Java Method Customization</h4></div></div></div><p>The <code class="literal">jaxws:method</code> binding declaration is used to customize the generated Java method name of a service endpoint interface and to customize the port accessor method in the generated <code class="literal">Service</code> class. Refer to the external binding declaration file <code class="literal">custom-client.xml</code> in the <code class="literal">external-customize</code> sample.</p><div class="section" title="9.2.7.1. Service Endpoint Interface Methods"><div class="titlepage"><div><div><h5 class="title" id="sei-method">9.2.7.1. Service Endpoint Interface Methods</h5></div></div></div><p><span class="command"><strong>wsimport</strong></span> will generate a method named <code class="literal">add</code> instead of the default <code class="literal">addNumbers</code> in this example:</p><div class="informalexample"><pre class="programlisting"><span class="Comment"><!-- wsdl:portType operation customization --></span> <span class="ReservedWord"><bindings</span> <span class="Identifier">node</span>=<span class="String">"wsdl:definitions/wsdl:portType[@name='AddNumbersImpl']/wsdl:operation[@name='addNumbers']"</span><span class="ReservedWord">></span> <span class="Comment"><!-- change java method name from addNumbers() to add() --></span> <span class="ReservedWord"><method</span> <span class="Identifier">name</span>=<span class="String">"add"</span><span class="ReservedWord">></span> <span class="ReservedWord"><javadoc></span>Adds the numbers<span class="ReservedWord"></javadoc></span> <span class="ReservedWord"></method></span> <span class="ReservedWord"></bindings></span></pre></div></div><div class="section" title="9.2.7.2. Port Accessor Methods in the Service Class"><div class="titlepage"><div><div><h5 class="title" id="port-accessor-method-in-service">9.2.7.2. Port Accessor Methods in the Service Class</h5></div></div></div><p><span class="command"><strong>wsimport</strong></span> will generate the <code class="literal">getMathUtil</code> port accessor method in the generated <code class="literal">Service</code> class instead of the default <code class="literal">getAddNumbersImplPort</code> method in this example:</p><div class="informalexample"><pre class="programlisting"><span class="Comment"><!-- change the port accessor method --></span> <span class="ReservedWord"><bindings</span> <span class="Identifier">node</span>=<span class="String">"wsdl:definitions/wsdl:service[@name='AddNumbersService']/wsdl:port[@name='AddNumbersImplPort']"</span><span class="ReservedWord">></span> <span class="ReservedWord"><method</span> <span class="Identifier">name</span>=<span class="String">"getMathUtil"</span><span class="ReservedWord">></span> <span class="ReservedWord"><javadoc></span>Returns MathUtil port<span class="ReservedWord"></javadoc></span> <span class="ReservedWord"></method></span> <span class="ReservedWord"></bindings></span></pre></div></div></div><div class="section" title="9.2.8. Java Parameter Customization"><div class="titlepage"><div><div><h4 class="title" id="java-parameter-customization">9.2.8. Java Parameter Customization</h4></div></div></div><p>The <code class="literal">jaxws:parameter</code> binding declaration is used to change the parameter name of generated Java methods. It can be used to change the method parameter of a <code class="literal">wsdl:operation</code> in a <code class="literal">wsdl:portType.</code> Refer to the external binding declaration file <code class="literal">custom-client.xml</code> of the <code class="literal">external-customize</code> sample.</p><div class="informalexample"><pre class="programlisting"><span class="ReservedWord"><bindings</span> <span class="Identifier">node</span>=<span class="String">"wsdl:definitions/wsdl:portType[@name='AddNumbersImpl']/wsdl:operation[@name='addNumbers']"</span><span class="ReservedWord">></span> <span class="Comment"><!-- rename method parameters--></span> <span class="ReservedWord"><parameter</span> <span class="Identifier">part</span>=<span class="String">"definitions/message[@name='addNumbers']/part[@name='parameters']"</span> <span class="Identifier">element</span>=<span class="String">"tns:number1"</span> <span class="Identifier">name</span>=<span class="String">"num1"</span><span class="ReservedWord">/></span> ... <span class="ReservedWord"></bindings></span></pre></div><p>The above sample renames the default parameter name of the Java method <code class="literal">addNumbers</code> from <code class="literal">number1</code> to <code class="literal">num1</code>.</p></div><div class="section" title="9.2.9. Javadoc customization"><div class="titlepage"><div><div><h4 class="title" id="javadoc-customization">9.2.9. Javadoc customization</h4></div></div></div><p><code class="literal">jaxws:javadoc</code> customization can be used to specify javadoc text for java package, class(SEI, Service or Exception class) and on the methods in SEI and service class. Inorder to do it,it should appear on the corresponding wsdl nodes.</p><p>For package level javadoc:</p><div class="informalexample"><pre class="programlisting"><span class="ReservedWord"><jaxws:package</span> <span class="Identifier">name</span>=<span class="String">"xs:string"</span><span class="ReservedWord">></span> <span class="ReservedWord"><jaxws:javadoc></span>xs:string<span class="ReservedWord"></jaxws:javadoc></span> <span class="ReservedWord"></jaxws:package></span></pre></div><p>For class level javadoc:</p><div class="informalexample"><pre class="programlisting"><span class="ReservedWord"><jaxws:class</span> <span class="Identifier">name</span>=<span class="String">"xs:string"</span><span class="ReservedWord">></span> <span class="ReservedWord"><jaxws:javadoc></span>xs:string<span class="ReservedWord"></jaxws:javadoc></span> <span class="ReservedWord"></jaxws:class></span></pre></div><p>For method level javadoc:</p><div class="informalexample"><pre class="programlisting"><span class="ReservedWord"><jaxws:method</span> <span class="Identifier">name</span>=<span class="String">"xs:string"</span><span class="ReservedWord">></span> <span class="ReservedWord"><jaxws:javadoc></span>xs:string<span class="ReservedWord"></jaxws:javadoc></span> <span class="ReservedWord"></jaxws:method></span> </pre></div><p>For specific samples on javadoc customization for class, refer <a class="xref" href="#sei-class" title="9.2.6.1. The Service Endpoint Interface Class">The Service Endpoint Interface Class</a>, <a class="xref" href="#exception-class" title="9.2.6.2. The Exception Class">The Exception Class</a> and <a class="xref" href="#service-class" title="9.2.6.3. The Service Class">The Service Class</a> customization. For javadoc customization on method refer <a class="xref" href="#sei-method" title="9.2.7.1. Service Endpoint Interface Methods">Service Endpoint Interface Methods</a> and <a class="xref" href="#port-accessor-method-in-service" title="9.2.7.2. Port Accessor Methods in the Service Class">Port Accessor Methods in the Service Class</a> customization and for package level customization refer <a class="xref" href="#package-customization" title="9.2.2. Package Customization">Package Customization</a>.</p></div><div class="section" title="9.2.10. XML Schema Customization"><div class="titlepage"><div><div><h4 class="title" id="xml-schema-customization">9.2.10. XML Schema Customization</h4></div></div></div><p>An XML schema inlined inside a compiled WSDL file can be customized by using standard JAXB bindings. These JAXB bindings can live inside the schema or as the child of a <code class="literal">jaxws:bindings</code> element in an external binding declaration file:</p><div class="informalexample"><pre class="programlisting"><span class="ReservedWord"><jaxws:bindings</span> <span class="Identifier">node</span>=<span class="String">"wsdl:definitions/wsdl:types/xsd:schema[@targetNamespace='http://duke.example.org']"</span><span class="ReservedWord">></span> <span class="ReservedWord"><jaxb:schemaBindings></span> <span class="ReservedWord"><jaxb:package</span> <span class="Identifier">name</span>=<span class="String">"fromwsdl.server"</span><span class="ReservedWord">/></span> <span class="ReservedWord"></jaxb:schemaBindings></span> <span class="ReservedWord"></jaxws:bindings></span></pre></div><p>External XML schema files imported by the WSDL file can be customized using a JAXB external binding declaration file:</p><div class="informalexample"><pre class="programlisting"><span class="ReservedWord"><jxb:bindings</span> <span class="Identifier">xmlns:xsd</span>=<span class="String">"http://www.w3.org/2001/XMLSchema"</span> <span class="Identifier">xmlns:jxb</span>=<span class="String">"http://java.sun.com/xml/ns/jaxb"</span> <span class="Identifier">version</span>=<span class="String">"1.0"</span><span class="ReservedWord">></span> <span class="ReservedWord"><jxb:bindings</span> <span class="Identifier">schemaLocation</span>=<span class="String">"http://localhost:8080/jaxws-external-customize/schema1.xsd"</span> <span class="Identifier">node</span>=<span class="String">"/xsd:schema"</span><span class="ReservedWord">></span> <span class="ReservedWord"><jxb:schemaBindings></span> <span class="ReservedWord"><jxb:package</span> <span class="Identifier">name</span>=<span class="String">"fromjava.client"</span><span class="ReservedWord">/></span> <span class="ReservedWord"></jxb:schemaBindings></span> <span class="ReservedWord"></jxb:bindings></span> ... <span class="ReservedWord"></jxb:bindings></span></pre></div><p>The external JAXB binding declaration file can be passed to <span class="command"><strong>wsimport</strong></span> using the <code class="option">-b</code> switch. See the JAX-WS <a class="xref" href="#wscompiletool" title="1.2. wsimport"><span class="command"><strong>wsimport</strong></span></a> documentation for details.</p></div><div class="section" title="9.2.11. Handler Chain Customization"><div class="titlepage"><div><div><h4 class="title" id="handler-chain-customization">9.2.11. Handler Chain Customization</h4></div></div></div><p><code class="literal">jaxws:bindings</code> customization can be used to customize or add handlers. All that is needed is to inline a handler chain configuration conforming to JSR 181 Handler Chain configuration schema inside <code class="literal">jaxws:bindings</code> element.</p><p>Below is a sample JAX-WS binding declaration file with JSR 181 handler chain configuration:</p><div class="informalexample"><pre class="programlisting"><span class="ReservedWord"><jaxws:bindings</span> <span class="Identifier">xmlns:xsd</span>=<span class="String">"http://www.w3.org/2001/XMLSchema"</span> <span class="Identifier">xmlns:jaxb</span>=<span class="String">"http://java.sun.com/xml/ns/jaxb"</span> <span class="Identifier">xmlns:wsdl</span>=<span class="String">"http://schemas.xmlsoap.org/wsdl/"</span> <span class="Identifier">wsdlLocation</span>=<span class="String">"http://localhost:8080/jaxws-fromwsdlhandler/addnumbers?WSDL"</span> <span class="Identifier">xmlns:jaxws</span>=<span class="String">"http://java.sun.com/xml/ns/jaxws"</span> <span class="Identifier">xmlns:javaee</span>=<span class="String">"http://java.sun.com/xml/ns/javaee"</span><span class="ReservedWord">></span> <span class="ReservedWord"><jaxws:bindings</span> <span class="Identifier">node</span>=<span class="String">"wsdl:definitions"</span><span class="ReservedWord">></span> <span class="ReservedWord"><javaee:handler-chain></span> <span class="ReservedWord"><javaee:handler-chain-name></span>LoggingHandlers <span class="ReservedWord"></javaee:handler-chain-name></span> <span class="ReservedWord"><javaee:handler></span> <span class="ReservedWord"><javaee:handler-name></span>Logger<span class="ReservedWord"></javaee:handler-name></span> <span class="ReservedWord"><javaee:handler-class></span>fromwsdlhandler.common.LoggingHandler <span class="ReservedWord"></javaee:handler-class></span> <span class="ReservedWord"></javaee:handler></span> <span class="ReservedWord"></javaee:handler-chain></span> <span class="ReservedWord"></jaxws:bindings></span> <span class="ReservedWord"></jaxws:bindings></span></pre></div><p>When this customization file is passed on to <span class="command"><strong>wsimport</strong></span> tool using -b switch together with the WSDL, <span class="command"><strong>wsimport</strong></span> generates all the artifacts togather with a handler configuration file which has everything inside <code class="literal">jaxws:bindings</code> element enclosing the <code class="literal">jws:handler-chain</code> element. It also add <code class="literal">@javax.jws.HandlerChain</code> annotation in the generated SEI class. JAXWS runtime uses the <code class="literal">@HandlerChain</code> annotation from the SEI to find the handlers that has to be added into the handle chain.</p></div></div></div><div lang="en" class="section" title="10. Annotations"><div class="titlepage"><div><div><h2 class="title" style="clear: both" id="users-guide-annotations">10. Annotations</h2></div></div></div><div class="section" title="10.1. Overview"><div class="titlepage"><div><div><h3 class="title" id="section-031540603185018">10.1. Overview</h3></div></div></div><p>Annotations play a critical role in JAX-WS 2.2. First, annotations are used in mapping Java to WSDL and schema. Second, annotations are used a runtime to control how the JAX-WS runtime processes and responds to web service invocations. Currently the annotations utilized by JAXR-WS 2.0 are defined in separate JSRs:</p><div class="itemizedlist"><ul class="itemizedlist" type="disc"><li class="listitem"><p><a class="link" href="http://www.jcp.org/en/jsr/detail?id=181" target="_top">JSR 181: Web Services Metadata for the Java TM Platform</a></p></li><li class="listitem"><p><a class="link" href="http://www.jcp.org/en/jsr/detail?id=222" target="_top">JSR 222: Java TM Architecture for XML Binding (JAXB) 2.1</a></p></li><li class="listitem"><p><a class="link" href="http://www.jcp.org/en/jsr/detail?id=224" target="_top">JSR 224: Java TM API for XML Web Services (JAX-WS) 2.0 and 2.1</a></p></li><li class="listitem"><p><a class="link" href="http://www.jcp.org/en/jsr/detail?id=250" target="_top">JSR 250: Common Annotations for the Java TM Platform</a>.</p></li></ul></div></div><div class="section" title="10.2. JSR 181 (Web Services Metadata) Annotations"><div class="titlepage"><div><div><h3 class="title" id="jsr-181">10.2. JSR 181 (Web Services Metadata) Annotations</h3></div></div></div><p>Because JSR 181 has been written to work with JAX-RPC 1.1, we have made slight changes in the use and interpretation of these annotations to work better with JAX-WS 2.0. We are working with the JSR 181 expert group to align the next release with JAX-WS 2.0 and we hope that all of the changes we have made will be folded in.</p><div class="section" title="10.2.1. @javax.jws.WebService"><div class="titlepage"><div><div><h4 class="title" id="javax-jws-webservice-outline">10.2.1. <code class="literal">@javax.jws.WebService</code></h4></div></div></div><p>The purpose of this annotation is to mark an endpoint implementation as implementing a web service or to mark that a service endpoint interface as defining a web service interface. All endpoint implementation classes MUST have a <code class="literal">WebService</code> annotation and must meet the requirements of section 3.3 of the <a class="link" href="http://www.jcp.org/en/jsr/detail?id=224" target="_top">JAX-WS 2.0</a> specification.</p><div class="table"><a name="d0e4116"></a><p class="title"><b>Table 3. <code class="literal">@javax.jws.WebService</code> - Description of Properties</b></p><div class="table-contents"><table summary="@javax.jws.WebService - Description
 of Properties" border="1"><colgroup><col width="16%"><col width="54%"><col width="30%"></colgroup><thead><tr><th>Property</th><th>Description</th><th>Default</th></tr></thead><tbody><tr><td><p><code class="literal">name</code></p></td><td><p>The name of the <code class="literal">wsdl:portType</code></p></td><td><p>The unqualified name of the Java class or interface</p></td></tr><tr><td><p><code class="literal">targetNamespace</code></p></td><td><p>The XML namespace of the the WSDL and some of the XML elements generated from this web service. Most of the XML elements will be in the namespace according to the JAXB mapping rules.</p></td><td><p>The namespace mapped from the package name containing the web service according to section 3.2 of the <a class="link" href="http://www.jcp.org/en/jsr/detail?id=224" target="_top">JAX-WS 2.0</a> specification.</p></td></tr><tr><td><p><code class="literal">serviceName</code></p></td><td><p>The Service name of the web service: <code class="literal">wsdl:service</code></p></td><td><p>The unqualified name of the Java class or interface + "Service"</p></td></tr><tr><td><p><code class="literal">endpointInterface</code></p></td><td><p>The qualified name of the service endpoint interface. If the implementation bean references a service endpoint interface, that service endpoint interface is used to determine the abstract WSDL contract (portType and bindings). In this case, the service implementation bean MUST NOT include any JSR 181 annotations other than <code class="literal">@WebService</code> and <code class="literal">@HandlerChain</code> In addition, the <code class="literal">@WebService</code> annotation MUST NOT include the name annotation element. The endpoint implementation class is not required to implement the endpointInterface.</p></td><td><p>None – If not specified, the endpoint implementation class is used to generate the web service contract. In this case, a service endpoint interface is not required.</p></td></tr><tr><td><p><code class="literal">portName</code></p></td><td><p>The <code class="literal">wsdl:portName</code></p></td><td><p>The <code class="literal">WebService.name</code> + "Port"</p></td></tr><tr><td><p><code class="literal">wsdlLocation</code></p></td><td><p>Not currently used by JAX-WS RI 2.2.7</p></td><td><p></p></td></tr></tbody></table></div></div><br class="table-break"><div class="section" title="10.2.1.1. Annotation Type Definition"><div class="titlepage"><div><div><h5 class="title" id="section-5790511949612727">10.2.1.1. Annotation Type Definition</h5></div></div></div><div class="informalexample"><pre class="programlisting"><span class="Annotation">@Retention(value = RetentionPolicy.RUNTIME)</span> <span class="Annotation">@Target({ElementType.TYPE})</span> <span class="ReservedWord">public</span> <span class="Annotation">@interface</span> WebService { String name() <span class="ReservedWord">default</span> <span class="String">""</span>; String targetNamespace() <span class="ReservedWord">default</span> <span class="String">""</span>; String serviceName() <span class="ReservedWord">default</span> <span class="String">""</span>; String wsdlLocation() <span class="ReservedWord">default</span> <span class="String">""</span>; String endpointInterface() <span class="ReservedWord">default</span> <span class="String">""</span>; String portName() <span class="ReservedWord">default</span> <span class="String">""</span>; }</pre></div></div><div class="section" title="10.2.1.2. Examples"><div class="titlepage"><div><div><h5 class="title" id="section-724263520121821">10.2.1.2. Examples</h5></div></div></div><div class="example"><a name="d0e4229"></a><p class="title"><b>Example 3. <code class="literal">@javax.jws.WebService</code> - Example 1</b></p><div class="example-contents"><pre class="programlisting"><span class="Annotation">@WebService(name = "AddNumbers", targetNamespace = "http://duke.example.org")</span> <span class="ReservedWord">public</span> <span class="ReservedWord">class</span> AddNumbersImpl { <span class="Comment">/** * @param number1 * @param number2 * @return The sum * @throws AddNumbersException if any of the numbers to be added is * negative. */</span> <span class="ReservedWord">public</span> <span class="ReservedWord">int</span> addNumbers(<span class="ReservedWord">int</span> number1, <span class="ReservedWord">int</span> number2) <span class="ReservedWord">throws</span> AddNumbersException { <span class="ReservedWord">if</span> (number1 < <span class="Numeric">0</span> || number2 < <span class="Numeric">0</span>) { <span class="ReservedWord">throw</span> <span class="ReservedWord">new</span> AddNumbersException(<span class="String">"Negative number cant be added "</span> + <span class="String">"!"</span>, <span class="String">"Numbers: "</span> + number1 + <span class="String">", "</span> + number2); } <span class="ReservedWord">return</span> number1 + number2; } }</pre></div></div><br class="example-break"><p>If you are familiar with JAX-RPC 1.1, you will notice that the <code class="literal">AddNumbersImpl</code> implementation class does not implement a service endpoint interface. In JAX-WS 2.2 a service endpoint interface is no longer required. If a service endpoint interfaces is desired, then the <code class="literal">@WebService</code> annotation on the endpoint implementation is modified to specify the endpoint interface and the actual service endpoint interface must also have a <code class="literal">@WebService</code> annotation. The following is the above <code class="literal">AddNumbersImpl</code> modified to use a service endpoint interface.</p><div class="example"><a name="d0e4250"></a><p class="title"><b>Example 4. <code class="literal">@javax.jws.WebService</code> - Example 2 - Implementation class using Service Endpoint Interface</b></p><div class="example-contents"><pre class="programlisting"><span class="Annotation">@WebService(endpointInterface = "annotations.server.AddNumbersIF")</span> <span class="ReservedWord">public</span> <span class="ReservedWord">class</span> AddNumbersImpl { <span class="Comment">/** * @param number1 * @param number2 * @return The sum * @throws AddNumbersException if any of the numbers to be added is * negative. */</span> <span class="ReservedWord">public</span> <span class="ReservedWord">int</span> addNumbers(<span class="ReservedWord">int</span> number1, <span class="ReservedWord">int</span> number2) <span class="ReservedWord">throws</span> AddNumbersException { <span class="ReservedWord">if</span> (number1 < <span class="Numeric">0</span> || number2 < <span class="Numeric">0</span>) { <span class="ReservedWord">throw</span> <span class="ReservedWord">new</span> AddNumbersException(<span class="String">"Negative number cant be "</span> + <span class="String">"added!"</span>, <span class="String">"Numbers: "</span> + number1 + <span class="String">", "</span> + number2); } <span class="ReservedWord">return</span> number1 + number2; } }</pre><pre class="programlisting"><span class="Annotation">@WebService(targetNamespace = "http://duke.example.org", name = "AddNumbers")</span> <span class="ReservedWord">public</span> <span class="ReservedWord">interface</span> AddNumbersIF <span class="ReservedWord">extends</span> Remote { <span class="ReservedWord">public</span> <span class="ReservedWord">int</span> addNumbers(<span class="ReservedWord">int</span> number1, <span class="ReservedWord">int</span> number2) <span class="ReservedWord">throws</span> RemoteException, AddNumbersException; }</pre></div></div><br class="example-break"></div></div><div class="section" title="10.2.2. @javax.jws.WebMethod"><div class="titlepage"><div><div><h4 class="title" id="javax-jws-webmethod-outline">10.2.2. <code class="literal">@javax.jws.WebMethod</code></h4></div></div></div><p>The purpose of this annotation is to expose a method as a web service operation. The method must meet all the requirements of section 3.4 of the <a class="link" href="http://www.jcp.org/en/jsr/detail?id=224" target="_top">JAX-WS 2.0</a> specification.</p><div class="table"><a name="d0e4268"></a><p class="title"><b>Table 4. <code class="literal">@javax.jws.WebMethod</code> - Description of Properties</b></p><div class="table-contents"><table summary="@javax.jws.WebMethod - Description
 of Properties" border="1"><colgroup><col width="16%"><col width="54%"><col width="30%"></colgroup><thead><tr><th>Property</th><th>Description</th><th>Default</th></tr></thead><tbody><tr><td><p><code class="literal">operationName</code></p></td><td><p>The name of the <code class="literal">wsdl:operation</code> matching this method. For operations using the mode defined by <code class="literal">SOAPBinding.Style.DOCUMENT</code>, <code class="literal">SOAPBinding.Use.LITERAL</code>, and <code class="literal">SOAPBinding.ParameterStyle.BARE</code>, this name is also used for the global XML element representing the operations body element. The namespace of this name is taken from the value <code class="literal">@WebService.targetNamespace</code> or its default value.</p></td><td><p>The name of the Java method</p></td></tr><tr><td><p><code class="literal">action</code></p></td><td><p>The XML namespace of the the WSDL and some of the XML elements generated from this web service. Most of the XML elements will be in the namespace according to the JAXB mapping rules.</p></td><td><p>""</p></td></tr><tr><td><p><code class="literal">exclude</code></p></td><td><p>Used to exclude a method from the WebService.</p></td><td><p>false</p></td></tr></tbody></table></div></div><br class="table-break"><div class="section" title="10.2.2.1. Annotation Type Definition"><div class="titlepage"><div><div><h5 class="title" id="section-54961496738835">10.2.2.1. Annotation Type Definition</h5></div></div></div><div class="informalexample"><pre class="programlisting"><span class="Annotation">@Retention(value = RetentionPolicy.RUNTIME)</span> <span class="Annotation">@Target({ElementType.METHOD})</span> <span class="ReservedWord">public</span> <span class="Annotation">@interface</span> WebMethod { String operationName() <span class="ReservedWord">default</span> <span class="String">""</span>; String action() <span class="ReservedWord">default</span> <span class="String">""</span>; <span class="ReservedWord">boolean</span> exclude() <span class="ReservedWord">default</span> false; }</pre></div></div><div class="section" title="10.2.2.2. Examples"><div class="titlepage"><div><div><h5 class="title" id="section-998755081708335">10.2.2.2. Examples</h5></div></div></div><div class="example"><a name="d0e4343"></a><p class="title"><b>Example 5. <code class="literal">@javax.jws.WebMethod</code> - Example</b></p><div class="example-contents"><pre class="programlisting"><span class="Annotation">@WebService(targetNamespace = "http://duke.example.org", name = "AddNumbers")</span> <span class="ReservedWord">public</span> <span class="ReservedWord">interface</span> AddNumbersIF <span class="ReservedWord">extends</span> Remote { <span class="Annotation">@WebMethod(operationName = "add", action = "urn:addNumbers")</span> <span class="ReservedWord">public</span> <span class="ReservedWord">int</span> addNumbers(<span class="ReservedWord">int</span> number1, <span class="ReservedWord">int</span> number2) <span class="ReservedWord">throws</span> RemoteException, AddNumbersException; }</pre></div></div><br class="example-break"></div></div><div class="section" title="10.2.3. @javax.jws.OneWay"><div class="titlepage"><div><div><h4 class="title" id="javax-jws-oneway-outline">10.2.3. <code class="literal">@javax.jws.OneWay</code></h4></div></div></div><p>The purpose of this annotation is to mark a method as a web service one-way operation. The method must meet all the requirements of section 3.4.1 of the <a class="link" href="http://www.jcp.org/en/jsr/detail?id=224" target="_top">JSR 224</a> spec.</p><p>There are no properties on the <code class="literal">OneWay</code> annotation.</p><div class="section" title="10.2.3.1. Annotation Type Definition"><div class="titlepage"><div><div><h5 class="title" id="section-57285842212862">10.2.3.1. Annotation Type Definition</h5></div></div></div><div class="informalexample"><pre class="programlisting"><span class="Annotation">@Retention(value = RetentionPolicy.RUNTIME)</span> <span class="Annotation">@Target({ElementType.METHOD})</span> <span class="ReservedWord">public</span> <span class="Annotation">@interface</span> Oneway { }</pre></div></div><div class="section" title="10.2.3.2. Examples"><div class="titlepage"><div><div><h5 class="title" id="section-877748055333987">10.2.3.2. Examples</h5></div></div></div><div class="example"><a name="d0e4373"></a><p class="title"><b>Example 6. <code class="literal">@javax.jws.OneWay</code> - Example</b></p><div class="example-contents"><pre class="programlisting"><span class="Annotation">@WebService(name = "CheckIn")</span> <span class="ReservedWord">public</span> <span class="ReservedWord">class</span> CheckInIF { <span class="Annotation">@WebMethod</span> <span class="Annotation">@OneWay</span> <span class="ReservedWord">public</span> <span class="ReservedWord">void</span> checkIn(String name); }</pre></div></div><br class="example-break"></div></div><div class="section" title="10.2.4. @javax.jws.WebParam"><div class="titlepage"><div><div><h4 class="title" id="javax-jws-webparam-outline">10.2.4. <code class="literal">@javax.jws.WebParam</code></h4></div></div></div><p>This annotation is used to customize the mapping of a single parameter to a message part or element.</p><div class="table"><a name="d0e4386"></a><p class="title"><b>Table 5. <code class="literal">@javax.jws.WebParam</code> - Description of Properties</b></p><div class="table-contents"><table summary="@javax.jws.WebParam - Description of
 Properties" border="1"><colgroup><col width="16%"><col width="54%"><col width="30%"></colgroup><thead><tr><th>Property</th><th>Description</th><th>Default</th></tr></thead><tbody><tr><td><p><code class="literal">name</code></p></td><td><p>Name of the parameter.</p><p>If the operation is RPC style and <code class="literal">@WebParam.partName</code> has not been specified, this is name of the <code class="literal">wsdl:part</code> representing the parameter.</p><p><code class="literal">@WebMethod.operation</code> Name, if the operation is document style and the parameter style is <code class="literal">BARE</code>.</p><p>Otherwise, the default is <code class="literal">argN</code> if the operation is document style or the parameter maps to a header, this is the local name of the XML element representing the parameter.</p><p>A name MUST be specified if the operation is document style, the parameter style is <code class="literal">BARE</code>, and the mode is <code class="literal">OUT</code> or <code class="literal">INOUT</code>.</p></td><td><p><code class="literal">@WebMethod.operation</code> Name, if the operation is document style and the parameter style is <code class="literal">BARE</code>. Otherwise, the default is <code class="literal">argN</code>, where <code class="literal">N</code> represents the index of the parameter in the method signature (starting at <code class="literal">arg0</code>).</p></td></tr><tr><td><p><code class="literal">targetNamespace</code></p></td><td><p>The XML namespace for the parameter. Only used if the operation is document style or the paramater maps to a header. If the target namespace is set to "", this represents the empty namespace.</p></td><td><p>The empty namespace, if the operation is document style, the parameter style is <code class="literal">WRAPPED</code>, and the parameter does not map to a header. Otherwise, the default is the <code class="literal">targetNamespace</code> for the Web Service.</p></td></tr><tr><td><p><code class="literal">mode</code></p></td><td><p>Represents the direction the parameter flows for this method. Possible values are <code class="literal">IN</code>, <code class="literal">INOUT</code> and <code class="literal">OUT</code>. <code class="literal">INOUT</code> and <code class="literal">OUT</code> modes can only be used with parameters that meet the requirements for a holder as classified by section 3.5 of the <a class="link" href="http://www.jcp.org/en/jsr/detail?id=224" target="_top">JAX-WS 2.0</a> specification. <code class="literal">OUT</code> and <code class="literal">INOUT</code> parameters can be used by all <code class="literal">RPC</code> and <code class="literal">DOCUMENT</code> bindings.</p></td><td><p><code class="literal">IN</code> for non-holder parameters <code class="literal">INOUT</code> for holder parameters.</p></td></tr><tr><td><p><code class="literal">header</code></p></td><td><p>Specifies whether the parameter should be carried in a header.</p></td><td><p><code class="literal">FALSE</code></p></td></tr><tr><td><p><code class="literal">partName</code></p></td><td><p>Used to specify the <code class="literal">partName</code> for the parameter with <code class="literal">RPC</code> or <code class="literal">DOCUMENT</code>/<code class="literal">BARE</code> operations.</p></td><td><p><code class="literal">@WebParam.name </code></p></td></tr></tbody></table></div></div><br class="table-break"><div class="section" title="10.2.4.1. Annotation Type Definition"><div class="titlepage"><div><div><h5 class="title" id="section-704139125883689">10.2.4.1. Annotation Type Definition</h5></div></div></div><div class="informalexample"><pre class="programlisting"><span class="Annotation">@Retention(value = RetentionPolicy.RUNTIME)</span> <span class="Annotation">@Target({ElementType.PARAMETER})</span> <span class="ReservedWord">public</span> <span class="Annotation">@interface</span> WebParam { <span class="ReservedWord">public</span> enum Mode { IN, OUT, INOUT } String name() <span class="ReservedWord">default</span> <span class="String">""</span>; String targetNamespace() <span class="ReservedWord">default</span> <span class="String">""</span>; Mode mode() <span class="ReservedWord">default</span> Mode.IN; <span class="ReservedWord">boolean</span> header() <span class="ReservedWord">default</span> false; String partName() <span class="ReservedWord">default</span> <span class="String">""</span>; }</pre></div></div><div class="section" title="10.2.4.2. Examples"><div class="titlepage"><div><div><h5 class="title" id="section-759744573502372">10.2.4.2. Examples</h5></div></div></div><div class="example"><a name="d0e4568"></a><p class="title"><b>Example 7. <code class="literal">@javax.jws.WebParam</code> - Example 1</b></p><div class="example-contents"><pre class="programlisting"><span class="Annotation">@WebService(targetNamespace = "http://duke.example.org", name = "AddNumbers")</span> <span class="ReservedWord">public</span> <span class="ReservedWord">interface</span> AddNumbersIF <span class="ReservedWord">extends</span> Remote { <span class="Annotation">@WebMethod(operationName = "add", action = "urn:addNumbers")</span> <span class="Annotation">@WebResult(name = "return")</span> <span class="ReservedWord">public</span> <span class="ReservedWord">int</span> addNumbers(<span class="Annotation">@WebParam(name = "num1")</span> <span class="ReservedWord">int</span> number1, <span class="Annotation">@WebParam(name = "num2")</span> <span class="ReservedWord">int</span> number2) <span class="ReservedWord">throws</span> RemoteException, AddNumbersException; }</pre></div></div><br class="example-break"><div class="example"><a name="d0e4575"></a><p class="title"><b>Example 8. <code class="literal">@javax.jws.WebParam</code> - Example 2</b></p><div class="example-contents"><pre class="programlisting"><span class="Annotation">@WebService(targetNamespace = "http://duke.example.org", name = "AddNumbers")</span> <span class="ReservedWord">public</span> <span class="ReservedWord">interface</span> AddNumbersIF <span class="ReservedWord">extends</span> Remote { <span class="Annotation">@WebMethod(operationName = "add", action = "urn:addNumbers")</span> <span class="Annotation">@WebResult(name = "return")</span> <span class="ReservedWord">public</span> <span class="ReservedWord">void</span> addNumbers(<span class="Annotation">@WebParam(name = "num1")</span> <span class="ReservedWord">int</span> number1, <span class="Annotation">@WebParam(name = "num2")</span> <span class="ReservedWord">int</span> number2, <span class="Annotation">@WebParam(name = "result", mode = WebParam.Mode.OUT)</span> Holder<Integer> result) <span class="ReservedWord">throws</span> RemoteException, AddNumbersException; }</pre></div></div><br class="example-break"></div></div><div class="section" title="10.2.5. @javax.jws.WebResult"><div class="titlepage"><div><div><h4 class="title" id="javax-jws-webresult-outline">10.2.5. <code class="literal">@javax.jws.WebResult</code></h4></div></div></div><p>This annotation is used to customize the mapping of the method return value to a WSDL part or XML element.</p><div class="table"><a name="d0e4588"></a><p class="title"><b>Table 6. <code class="literal">@javax.jws.WebResult</code> - Description of Properties</b></p><div class="table-contents"><table summary="@javax.jws.WebResult - Description
 of Properties" border="1"><colgroup><col width="16%"><col width="54%"><col width="30%"></colgroup><thead><tr><th>Property</th><th>Description</th><th>Default</th></tr></thead><tbody><tr><td><p><code class="literal">name</code></p></td><td><p>The name of the return value in the WSDL and on the wire. For <code class="literal">RPC</code> bindings this is the part name of the return value in the response message. For <code class="literal">DOCUMENT</code> bindings this is the local name of the XML element representing the return value.</p></td><td><p>"return" for <code class="literal">RPC</code> and <code class="literal">DOCUMENT</code>/<code class="literal">WRAPPED</code> bindings. Method name + "Response" for <code class="literal">DOCUMENT</code>/<code class="literal">BARE</code> bindings.</p></td></tr><tr><td><p><code class="literal">targetNamespace</code></p></td><td><p>The XML namespace for the return value. Only used if the operation is document style or the return value maps to a header. If the target namespace is set to "", this represents the empty namespace.</p></td><td><p>The empty namespace, if the operation is document style, the parameter style is <code class="literal">WRAPPED</code>, and the return value does not map to a header, Otherwise, the default is the <code class="literal">targetNamespace</code> for the Web Service.</p></td></tr><tr><td><p><code class="literal">header</code></p></td><td><p>Specifies whether the result should be carried in a header.</p></td><td><p><code class="literal">FALSE</code></p></td></tr><tr><td><p><code class="literal">partName</code></p></td><td><p>Used to specify the <code class="literal">partName</code> for the result with <code class="literal">RPC</code> or <code class="literal">DOCUMENT</code>/<code class="literal">BARE</code> operations.</p></td><td><p><code class="literal">@WebResult.name </code></p></td></tr></tbody></table></div></div><br class="table-break"><div class="section" title="10.2.5.1. Annotation Type Definition"><div class="titlepage"><div><div><h5 class="title" id="section-825230071110141">10.2.5.1. Annotation Type Definition</h5></div></div></div><div class="informalexample"><pre class="programlisting"><span class="Annotation">@Retention(value = RetentionPolicy.RUNTIME)</span> <span class="Annotation">@Target({ElementType.METHOD})</span> <span class="ReservedWord">public</span> <span class="Annotation">@interface</span> WebResult { String name() <span class="ReservedWord">default</span> <span class="String">"return"</span>; String targetNamespace() <span class="ReservedWord">default</span> <span class="String">""</span>; <span class="ReservedWord">boolean</span> header() <span class="ReservedWord">default</span> false; String partName() <span class="ReservedWord">default</span> <span class="String">""</span>; }</pre></div></div><div class="section" title="10.2.5.2. Examples"><div class="titlepage"><div><div><h5 class="title" id="section-324659921484612">10.2.5.2. Examples</h5></div></div></div><div class="example"><a name="d0e4700"></a><p class="title"><b>Example 9. <code class="literal">@javax.jws.WebResult</code> - Example</b></p><div class="example-contents"><pre class="programlisting"><span class="Annotation">@WebService(targetNamespace = "http://duke.example.org", name = "AddNumbers")</span> <span class="ReservedWord">public</span> <span class="ReservedWord">interface</span> AddNumbersIF <span class="ReservedWord">extends</span> Remote { <span class="Annotation">@WebMethod(operationName = "add", action = "urn:addNumbers")</span> <span class="Annotation">@WebResult(name = "return")</span> <span class="ReservedWord">public</span> <span class="ReservedWord">int</span> addNumbers(<span class="Annotation">@WebParam(name = "num1")</span> <span class="ReservedWord">int</span> number1, <span class="Annotation">@WebParam(name = "num2")</span> <span class="ReservedWord">int</span> number2) <span class="ReservedWord">throws</span> RemoteException, AddNumbersException; }</pre></div></div><br class="example-break"></div></div><div class="section" title="10.2.6. @javax.jws.HandlerChain"><div class="titlepage"><div><div><h4 class="title" id="javax-jws-handlerchain-outline">10.2.6. <code class="literal">@javax.jws.HandlerChain</code></h4></div></div></div><p>This annotation is used to specified an externally defined handler chain.</p><div class="table"><a name="d0e4713"></a><p class="title"><b>Table 7. <code class="literal">@javax.jws.HandlerChain</code> - Description of Properties</b></p><div class="table-contents"><table summary="@javax.jws.HandlerChain -
 Description of Properties" border="1"><colgroup><col width="16%"><col width="54%"><col width="30%"></colgroup><thead><tr><th>Property</th><th>Description</th><th>Default</th></tr></thead><tbody><tr><td><p><code class="literal">file</code></p></td><td><p>Location of the file containing the handler chain definition. The location can be relative or absolute with in a classpath system. If the location is relative, it is relative to the package of the web service. If it is absolute, it is absolute from some path on the classpath.</p></td><td><p>None</p></td></tr><tr><td><p><code class="literal">name</code></p></td><td><p><span class="bold"><strong>DEPRECATED</strong></span> The handler chain name from within the handler chain file.</p></td><td><p>""</p></td></tr></tbody></table></div></div><br class="table-break"><div class="section" title="10.2.6.1. Annotation Type Definition"><div class="titlepage"><div><div><h5 class="title" id="section-888738992154297">10.2.6.1. Annotation Type Definition</h5></div></div></div><div class="informalexample"><pre class="programlisting"><span class="Annotation">@Retention(value = RetentionPolicy.RUNTIME)</span> <span class="Annotation">@Target({ElementType.TYPE})</span> <span class="ReservedWord">public</span> <span class="Annotation">@interface</span> HandlerChain { String file(); <span class="Annotation">@Deprecated</span> String name() <span class="ReservedWord">default</span> <span class="String">""</span>; }</pre></div></div><div class="section" title="10.2.6.2. Examples"><div class="titlepage"><div><div><h5 class="title" id="section-0070675424428255">10.2.6.2. Examples</h5></div></div></div><div class="example"><a name="d0e4764"></a><p class="title"><b>Example 10. <code class="literal">@javax.jws.HandlerChain</code> - Example</b></p><div class="example-contents"><pre class="programlisting"><span class="Annotation">@WebService</span> <span class="Annotation">@HandlerChain(file = "handlers.xml")</span> <span class="ReservedWord">public</span> <span class="ReservedWord">class</span> AddNumbersImpl { <span class="Comment">/** * @param number1 * @param number2 * @return The sum * @throws AddNumbersException if any of the numbers to be added is * negative. */</span> <span class="ReservedWord">public</span> <span class="ReservedWord">int</span> addNumbers(<span class="ReservedWord">int</span> number1, <span class="ReservedWord">int</span> number2) <span class="ReservedWord">throws</span> AddNumbersException { <span class="ReservedWord">if</span> (number1 < <span class="Numeric">0</span> || number2 < <span class="Numeric">0</span>) { <span class="ReservedWord">throw</span> <span class="ReservedWord">new</span> AddNumbersException(<span class="String">"Negative number cant be added "</span> + <span class="String">"!"</span>, <span class="String">"Numbers: "</span> + number1 + <span class="String">", "</span> + number2); } <span class="ReservedWord">return</span> number1 + number2; } }</pre></div></div><br class="example-break"><div class="example"><a name="d0e4771"></a><p class="title"><b>Example 11. <code class="literal">@javax.jws.HandlerChain</code> - Example - handlers.xml</b></p><div class="example-contents"><pre class="programlisting"><span class="ReservedWord"><jws:handler-config</span> <span class="Identifier">xmlns:jws</span>=<span class="String">"http://java.sun.com/xml/ns/javaee"</span><span class="ReservedWord">></span> <span class="ReservedWord"><jws:handler-chains></span> <span class="ReservedWord"><jws:handler-chain></span> <span class="ReservedWord"><jws:handler></span> <span class="ReservedWord"><jws:handler-class></span>fromjavahandler.common.LoggingHandler <span class="ReservedWord"></jws:handler-class></span> <span class="ReservedWord"></jws:handler></span> <span class="ReservedWord"></jws:handler-chain></span> <span class="ReservedWord"></jws:handler-chains></span> <span class="ReservedWord"></jws:handler-config></span></pre></div></div><br class="example-break"><div class="important" title="Important" style="margin-left: 0.5in; margin-right: 0.5in;"><h3 class="title">Important</h3><p>When using a handler chain file, it is important that the file is store in the appropriate place in the classpath so that the file can be found. This means that when a raw WAR file is created that the file must be place in the proper directory. Please refer to the <span class="application">fromjavahandlers</span> <a class="link" href="../samples/docs/jax-ws-ri-overview" target="_top">sample application</a> and the <a class="xref" href="#users-guide-handler" title="6. Handler">Handler</a> for more information.</p></div></div></div><div class="section" title="10.2.7. @javax.jws.soap.SOAPBinding"><div class="titlepage"><div><div><h4 class="title" id="javax-jws-soap-soapbinding-outline">10.2.7. <code class="literal">@javax.jws.soap.SOAPBinding</code></h4></div></div></div><p>JSR 181 also allows you to specify a <code class="literal">SOAPBinding</code> annotation on an endpoint implementation or service endpoint interface. This annotation lets the developer choose between <code class="literal">DOCUMENT\LITERAL WRAPPED</code>, <code class="literal">DOCUMENT\LITERAL BARE</code>, <code class="literal">RPC\LITERAL</code> and <code class="literal">RPC\ENCODED</code> endpoints with the default being <code class="literal">DOCUMENT\LITERAL WRAPPED</code>. JAX-WS 2.2 does not support <code class="literal">RPC\ENCODED</code>. The main difference between <code class="literal">DOCUMENT\LITERAL BARE</code> and <code class="literal">DOCUMENT\LITERAL WRAPPED</code> is that methods on a <code class="literal">DOCUMENT\LITERAL WRAPPED</code> endpoint can have multiple parameters bound to the body of a SOAP message, while a <code class="literal">DOCUMENT\LITERAL BARE</code> can only have one such parameter. The main difference between <code class="literal">DOCUMENT\LITERAL WRAPPED</code> and <code class="literal">RPC\LITERAL</code> is that a <code class="literal">DOCUMENT\LITERAL</code> invocation can be fully validated by a standard validating XML parser, while an <code class="literal">RPC\LITERAL</code> invocation cannot because of the implied wrapper element around the invocation body.</p><div class="table"><a name="d0e4840"></a><p class="title"><b>Table 8. <code class="literal">@javax.jws.soap.SOAPBinding</code> - Description of Properties</b></p><div class="table-contents"><table summary="@javax.jws.soap.SOAPBinding -
 Description of Properties" border="1"><colgroup><col width="16%"><col width="54%"><col width="30%"></colgroup><thead><tr><th>Property</th><th>Description</th><th>Default</th></tr></thead><tbody><tr><td><p><code class="literal">style</code></p></td><td><p>Defines the style for messages used in a web service. The value can be either <code class="literal">DOCUMENT</code> or <code class="literal">RPC</code>.</p></td><td><p><code class="literal">DOCUMENT</code></p></td></tr><tr><td><p><code class="literal">use</code></p></td><td><p>Defines the encoding used for messages used in web service. Can only be <code class="literal">LITERAL</code> for JAX-WS 2.2.</p></td><td><p><code class="literal">LITERAL</code></p></td></tr><tr><td><p><code class="literal">parameterStyle</code></p></td><td><p>Determines if the method's parameters represent the entire message body or whether the parameters are wrapped in a body element named after the operation. Choice of <code class="literal">WRAPPED</code> or <code class="literal">BARE</code>. <code class="literal">BARE</code> can only be used with <code class="literal">DOCUMENT</code> style bindings.</p></td><td><p><code class="literal">WRAPPED</code></p></td></tr></tbody></table></div></div><br class="table-break"><div class="section" title="10.2.7.1. Annotation Type Definition"><div class="titlepage"><div><div><h5 class="title" id="section-980481850012988">10.2.7.1. Annotation Type Definition</h5></div></div></div><div class="informalexample"><pre class="programlisting"><span class="Annotation">@Retention(value = RetentionPolicy.RUNTIME)</span> <span class="Annotation">@Target({ElementType.TYPE, ElementType.METHOD})</span> <span class="ReservedWord">public</span> <span class="Annotation">@interface</span> SOAPBinding { <span class="ReservedWord">public</span> enum Style { DOCUMENT, RPC, } <span class="ReservedWord">public</span> enum Use { LITERAL, ENCODED, } <span class="ReservedWord">public</span> enum ParameterStyle { BARE, WRAPPED, } Style style() <span class="ReservedWord">default</span> Style.DOCUMENT; Use use() <span class="ReservedWord">default</span> Use.LITERAL; ParameterStyle parameterStyle() <span class="ReservedWord">default</span> ParameterStyle.WRAPPED; }</pre></div></div><div class="section" title="10.2.7.2. Examples"><div class="titlepage"><div><div><h5 class="title" id="section-106596084465574">10.2.7.2. Examples</h5></div></div></div><div class="example"><a name="d0e4924"></a><p class="title"><b>Example 12. <code class="literal">@javax.jws.soap.SOAPBinding</code> - Example</b></p><div class="example-contents"><pre class="programlisting"><span class="Annotation">@WebService(targetNamespace = "http://duke.example.org", name = "AddNumbers")</span> <span class="Annotation">@SOAPBinding(style = SOAPBinding.Style.RPC, use = SOAPBinding.Use.LITERAL)</span> <span class="ReservedWord">public</span> <span class="ReservedWord">interface</span> AddNumbersIF <span class="ReservedWord">extends</span> Remote { <span class="Annotation">@WebMethod(operationName = "add", action = "urn:addNumbers")</span> <span class="Annotation">@WebResult(name = "return")</span> <span class="ReservedWord">public</span> <span class="ReservedWord">int</span> addNumbers(<span class="Annotation">@WebParam(name = "num1")</span> <span class="ReservedWord">int</span> number1, <span class="Annotation">@WebParam(name = "num2")</span> <span class="ReservedWord">int</span> number2) <span class="ReservedWord">throws</span> RemoteException, AddNumbersException; }</pre></div></div><br class="example-break"></div></div></div><div class="section" title="10.3. JSR 224 (JAX-WS) Annotations"><div class="titlepage"><div><div><h3 class="title" id="jsr-224-jax-ws-annotations-outline">10.3. JSR 224 (JAX-WS) Annotations</h3></div></div></div><p>The following are standard annotations needed by JAX-WS that are not defined in JSR 181. The developer may not ever use these annotations directly as some of them are generated by JAX-WS tools but they will be presented here to avoid confusion.</p><div class="section" title="10.3.1. @javax.xml.ws.BindingType"><div class="titlepage"><div><div><h4 class="title" id="javax-xml-ws-bindingtype-outline">10.3.1. <code class="literal">@javax.xml.ws.BindingType</code></h4></div></div></div><p>The <code class="literal">BindingType</code> annotation is used to specify the binding to use for a web service endpoint implementation class. As well as specify additional features that may be enabled.</p><p>This annotation may be overriden programmatically or via deployment descriptors, depending on the platform in use.</p><div class="table"><a name="d0e4947"></a><p class="title"><b>Table 9. <code class="literal">@javax.xml.ws.BindingType</code> - Description of Properties</b></p><div class="table-contents"><table summary="@javax.xml.ws.BindingType -
 Description of Properties" border="1"><colgroup><col width="16%"><col width="54%"><col width="30%"></colgroup><thead><tr><th>Property</th><th>Description</th><th>Default</th></tr></thead><tbody><tr><td><p><code class="literal">value</code></p></td><td><p>A binding identifier (a URI).</p><p>See the <code class="literal">SOAPBinding</code> and <code class="literal">HTTPBinding</code> for the definition of the standard binding identifiers.</p><p><code class="code">@see javax.xml.ws.Binding</code></p><p><code class="code">@see javax.xml.ws.soap.SOAPBinding#SOAP11HTTP_BINDING</code></p><p><code class="code">@see javax.xml.ws.soap.SOAPBinding#SOAP12HTTP_BINDING</code></p><p><code class="code">@see javax.xml.ws.http.HTTPBinding#HTTP_BINDING</code></p></td><td><p>"<code class="literal">SOAP 1.1 Protocol</code>"/<code class="literal">HTTP</code></p></td></tr></tbody></table></div></div><br class="table-break"><div class="section" title="10.3.1.1. Annotation Type Definition"><div class="titlepage"><div><div><h5 class="title" id="section-2239237830275984">10.3.1.1. Annotation Type Definition</h5></div></div></div><div class="informalexample"><pre class="programlisting"><span class="Annotation">@Target(ElementType.TYPE)</span> <span class="Annotation">@Retention(RetentionPolicy.RUNTIME)</span> <span class="Annotation">@Documented</span> <span class="ReservedWord">public</span> <span class="Annotation">@interface</span> BindingType { <span class="Comment">/** * A binding identifier (a URI). * If not specified, the default is the SOAP 1.1 / HTTP * binding. * <p/> * See the * SOAPBinding and * HTTPBinding * for the definition of the standard binding identifiers. * * @see javax.xml.ws.Binding * @see javax.xml.ws.soap.SOAPBinding#SOAP11HTTP_BINDING * @see javax.xml.ws.soap.SOAPBinding#SOAP12HTTP_BINDING * @see javax.xml.ws.http.HTTPBinding#HTTP_BINDING */</span> String value() <span class="ReservedWord">default</span> <span class="String">""</span>; <span class="Comment">/** * An array of Features to enable/disable on the specified * binding. * If not specified, features will be enabled/disabled based * on their own rules. Refer to the documentation of the * feature * to determine when it will be automatically enabled. * <p/> * See the * SOAPBinding * for the definition of the standard feature identifiers. * * @see javax.xml.ws.RespectBindingFeature * @see javax.xml.ws.soap.AddressingFeature * @see javax.xml.ws.soap.MTOMFeature * @since JAX-WS 2.1 */</span> Feature[] features() <span class="ReservedWord">default</span> {}; }</pre></div></div><div class="section" title="10.3.1.2. Examples"><div class="titlepage"><div><div><h5 class="title" id="section-673452285502762">10.3.1.2. Examples</h5></div></div></div><div class="example"><a name="d0e5010"></a><p class="title"><b>Example 13. <code class="literal">@javax.xml.ws.BindingType</code> - Example</b></p><div class="example-contents"><p>Given the web service defined by</p><pre class="programlisting"><span class="Annotation">@WebService</span> <span class="Annotation">@BindingType(value = "http://www.w3.org/2003/05/soap/bindings/HTTP/")</span> <span class="ReservedWord">public</span> <span class="ReservedWord">class</span> AddNumbersImpl { <span class="Comment">/** * @param number1 * @param number2 * @return The sum * @throws AddNumbersException if any of the numbers to be added is * negative. */</span> <span class="ReservedWord">public</span> <span class="ReservedWord">int</span> addNumbers(<span class="ReservedWord">int</span> number1, <span class="ReservedWord">int</span> number2) <span class="ReservedWord">throws</span> AddNumbersException { <span class="ReservedWord">if</span> (number1 < <span class="Numeric">0</span> || number2 < <span class="Numeric">0</span>) { <span class="ReservedWord">throw</span> <span class="ReservedWord">new</span> AddNumbersException(<span class="String">"Negative number cant be "</span> + <span class="String">"added!"</span>, <span class="String">"Numbers: "</span> + number1 + <span class="String">", "</span> + number2); } <span class="ReservedWord">return</span> number1 + number2; } }</pre><p>The deployed endpoint would use the SOAP 1.2 over HTTP binding.</p></div></div><br class="example-break"></div></div><div class="section" title="10.3.2. @javax.xml.ws.RequestWrapper"><div class="titlepage"><div><div><h4 class="title" id="javax-xml-ws-requestwrapper-outline">10.3.2. <code class="literal">@javax.xml.ws.RequestWrapper</code></h4></div></div></div><p>This annotation annotates methods in the Service Endpoint Interface with the request wrapper bean to be used at runtime.</p><p>When starting from Java this annotation is used to resolve overloading conflicts in <code class="literal">DOCUMENT\LITERAL</code> mode. Only the <code class="literal">className</code> is required in this case.</p><div class="table"><a name="d0e5035"></a><p class="title"><b>Table 10. <code class="literal">@javax.xml.ws.RequestWrapper</code> - Description of Properties</b></p><div class="table-contents"><table summary="@javax.xml.ws.RequestWrapper -
 Description of Properties" border="1"><colgroup><col width="16%"><col width="54%"><col width="30%"></colgroup><thead><tr><th>Property</th><th>Description</th><th>Default</th></tr></thead><tbody><tr><td><p><code class="literal">localName</code></p></td><td><p>Specifies the <code class="literal">localName</code> of the XML Schema element representing this request wrapper.</p></td><td><p><code class="literal">operationName</code> as defined by <code class="literal">@javax.jws.WebMethod</code></p></td></tr><tr><td><p><code class="literal">targetNamespace</code></p></td><td><p>namespace of the request wrapper element.</p></td><td><p>the <code class="literal">targetNamespace</code> of the SEI</p></td></tr><tr><td><p><code class="literal">className</code></p></td><td><p>The name of the Class representing the request wrapper.</p></td><td><p></p></td></tr></tbody></table></div></div><br class="table-break"><div class="section" title="10.3.2.1. Annotation Type Definition"><div class="titlepage"><div><div><h5 class="title" id="section-253709758478671">10.3.2.1. Annotation Type Definition</h5></div></div></div><div class="informalexample"><pre class="programlisting"><span class="Annotation">@Target({ElementType.TYPE, ElementType.METHOD})</span> <span class="Annotation">@Retention(RetentionPolicy.RUNTIME)</span> <span class="ReservedWord">public</span> <span class="Annotation">@interface</span> RequestWrapper { <span class="Comment">/** * Elements local name. */</span> <span class="ReservedWord">public</span> String localName() <span class="ReservedWord">default</span> <span class="String">""</span>; <span class="Comment">/** * Elements namespace name. */</span> <span class="ReservedWord">public</span> String targetNamespace() <span class="ReservedWord">default</span> <span class="String">""</span>; <span class="Comment">/** * Request wrapper bean name. */</span> <span class="ReservedWord">public</span> String className() <span class="ReservedWord">default</span> <span class="String">""</span>; }</pre></div></div><div class="section" title="10.3.2.2. Examples"><div class="titlepage"><div><div><h5 class="title" id="section-677521323678242">10.3.2.2. Examples</h5></div></div></div><div class="example"><a name="d0e5104"></a><p class="title"><b>Example 14. <code class="literal">@javax.xml.ws.RequestWrapper</code> - Example</b></p><div class="example-contents"><pre class="programlisting"><span class="ReservedWord">public</span> <span class="ReservedWord">interface</span> AddNumbersImpl { <span class="Comment">/** * @param arg1 * @param arg0 * @return returns int * @throws AddNumbersException_Exception */</span> <span class="Annotation">@WebMethod</span> <span class="Annotation">@WebResult(targetNamespace = "")</span> <span class="Annotation">@RequestWrapper(localName = "addNumbers", targetNamespace = "http://server.fromjava/", className = "fromjava.client.AddNumbers")</span> <span class="Annotation">@ResponseWrapper(localName = "addNumbersResponse", targetNamespace = "http://server.fromjava/", className = "fromjava.client.AddNumbersResponse")</span> <span class="ReservedWord">public</span> <span class="ReservedWord">int</span> addNumbers(<span class="Annotation">@WebParam(name = "arg0", targetNamespace = "")</span> <span class="ReservedWord">int</span> arg0, <span class="Annotation">@WebParam(name = "arg1", targetNamespace = "")</span> <span class="ReservedWord">int</span> arg1) <span class="ReservedWord">throws</span> AddNumbersException_Exception; }</pre></div></div><br class="example-break"></div></div><div class="section" title="10.3.3. @javax.xml.ws.ResponseWrapper"><div class="titlepage"><div><div><h4 class="title" id="javax-xml-ws-responsewrapper-outline">10.3.3. <code class="literal">@javax.xml.ws.ResponseWrapper</code></h4></div></div></div><p>This annotation annotates methods in the Service Endpoint Interface with the response wrapper bean to be used at runtime.</p><p>When starting from Java this annotation is used to resolve overloading conflicts in <code class="literal">DOCUMENT\LITERAL</code> mode. Only the <code class="literal">className</code> is required in this case.</p><div class="table"><a name="d0e5125"></a><p class="title"><b>Table 11. <code class="literal">@javax.xml.ws.ResponseWrapper</code> - Description of Properties</b></p><div class="table-contents"><table summary="@javax.xml.ws.ResponseWrapper -
 Description of Properties" border="1"><colgroup><col width="16%"><col width="54%"><col width="30%"></colgroup><thead><tr><th>Property</th><th>Description</th><th>Default</th></tr></thead><tbody><tr><td><p><code class="literal">localName</code></p></td><td><p>Specifies the <code class="literal">localName</code> of the XML Schema element representing this request wrapper.</p></td><td><p><code class="literal">operationName</code> as defined by <code class="literal">@javax.jws.WebMethod</code></p></td></tr><tr><td><p><code class="literal">targetNamespace</code></p></td><td><p>namespace of the request wrapper element.</p></td><td><p>the <code class="literal">targetNamespace</code> of the SEI</p></td></tr><tr><td><p><code class="literal">className</code></p></td><td><p>The name of the Class representing the request wrapper.</p></td><td><p></p></td></tr></tbody></table></div></div><br class="table-break"><div class="section" title="10.3.3.1. Annotation Type Definition"><div class="titlepage"><div><div><h5 class="title" id="section-431093721276197">10.3.3.1. Annotation Type Definition</h5></div></div></div><div class="informalexample"><pre class="programlisting"><span class="Annotation">@Target(ElementType.METHOD)</span> <span class="Annotation">@Retention(RetentionPolicy.RUNTIME)</span> <span class="ReservedWord">public</span> <span class="Annotation">@interface</span> ResponseWrapper { <span class="Comment">/** * Elements local name. */</span> <span class="ReservedWord">public</span> String localName() <span class="ReservedWord">default</span> <span class="String">""</span>; <span class="Comment">/** * Elements namespace name. */</span> <span class="ReservedWord">public</span> String targetNamespace() <span class="ReservedWord">default</span> <span class="String">""</span>; <span class="Comment">/** * Request wrapper bean name. */</span> <span class="ReservedWord">public</span> String className() <span class="ReservedWord">default</span> <span class="String">""</span>; }</pre></div></div><div class="section" title="10.3.3.2. Examples"><div class="titlepage"><div><div><h5 class="title" id="section-486634908061201">10.3.3.2. Examples</h5></div></div></div><div class="example"><a name="d0e5194"></a><p class="title"><b>Example 15. <code class="literal">@javax.xml.ws.ResponseWrapper</code> - Example</b></p><div class="example-contents"><pre class="programlisting"><span class="ReservedWord">public</span> <span class="ReservedWord">interface</span> AddNumbersImpl { <span class="Comment">/** * @param arg1 * @param arg0 * @return returns int * @throws AddNumbersException_Exception */</span> <span class="Annotation">@WebMethod</span> <span class="Annotation">@WebResult(targetNamespace = "")</span> <span class="Annotation">@RequestWrapper(localName = "addNumbers", targetNamespace = "http://server.fromjava/", className = "fromjava.client.AddNumbers")</span> <span class="Annotation">@ResponseWrapper(localName = "addNumbersResponse", targetNamespace = "http://server.fromjava/", className = "fromjava.client.AddNumbersResponse")</span> <span class="ReservedWord">public</span> <span class="ReservedWord">int</span> addNumbers(<span class="Annotation">@WebParam(name = "arg0", targetNamespace = "")</span> <span class="ReservedWord">int</span> arg0, <span class="Annotation">@WebParam(name = "arg1", targetNamespace = "")</span> <span class="ReservedWord">int</span> arg1) <span class="ReservedWord">throws</span> AddNumbersException_Exception; }</pre></div></div><br class="example-break"></div></div><div class="section" title="10.3.4. @javax.xml.ws.ServiceMode"><div class="titlepage"><div><div><h4 class="title" id="javax-xml-ws-servicemode-outline">10.3.4. <code class="literal">@javax.xml.ws.ServiceMode</code></h4></div></div></div><p>This annotation allows the <a class="xref" href="#users-guide-provider" title="2. Provider">Provider</a> developer to indicate whether a <code class="literal">Provider</code> implementation wishes to work with entire protocol messages or just with protocol message payloads.</p><div class="table"><a name="d0e5212"></a><p class="title"><b>Table 12. <code class="literal">@javax.xml.ws.ServiceMode</code> - Description of Properties</b></p><div class="table-contents"><table summary="@javax.xml.ws.ServiceMode -
 Description of Properties" border="1"><colgroup><col width="16%"><col width="54%"><col width="30%"></colgroup><thead><tr><th>Property</th><th>Description</th><th>Default</th></tr></thead><tbody><tr><td><p><code class="literal">value</code></p></td><td><p>Convey whether the <code class="literal">Provider</code> endpoint wants to access then entire message (<code class="literal">MESSAGE</code>) or just the payload (<code class="literal">PAYLOAD</code>).</p></td><td><p><code class="literal">PAYLOAD</code></p></td></tr></tbody></table></div></div><br class="table-break"><div class="section" title="10.3.4.1. Annotation Type Definition"><div class="titlepage"><div><div><h5 class="title" id="section-7509472401703894">10.3.4.1. Annotation Type Definition</h5></div></div></div><div class="informalexample"><pre class="programlisting"><span class="Annotation">@Target({ElementType.TYPE})</span> <span class="Annotation">@Retention(RetentionPolicy.RUNTIME)</span> <span class="Annotation">@Inherited</span> <span class="Annotation">@Documented</span> <span class="ReservedWord">public</span> <span class="Annotation">@interface</span> ServiceMode { <span class="Comment">/** * Service mode. <code>PAYLOAD</code> indicates that the * <code>Provider</code> implementation * wishes to work with protocol message payloads only. * <code>MESSAGE</code> indicates * that the <code>Provider</code> implementation wishes to work with * entire protocol * messages. */</span> <span class="ReservedWord">public</span> Service.Mode value() <span class="ReservedWord">default</span> Service.Mode.PAYLOAD; }</pre></div></div><div class="section" title="10.3.4.2. Examples"><div class="titlepage"><div><div><h5 class="title" id="section-0843754606554705">10.3.4.2. Examples</h5></div></div></div><div class="example"><a name="d0e5260"></a><p class="title"><b>Example 16. <code class="literal">@javax.xml.ws.ServiceMode</code> - Example</b></p><div class="example-contents"><pre class="programlisting"><span class="Annotation">@ServiceMode(value = Service.Mode.PAYLOAD)</span> <span class="ReservedWord">public</span> <span class="ReservedWord">class</span> AddNumbersImpl <span class="ReservedWord">implements</span> Provider<Source> { <span class="ReservedWord">public</span> Source invoke(Source source) <span class="ReservedWord">throws</span> RemoteException { <span class="ReservedWord">try</span> { DOMResult dom = <span class="ReservedWord">new</span> DOMResult(); Transformer trans = TransformerFactory.newInstance() .newTransformer(); trans.transform(source, dom); Node node = dom.getNode(); Node root = node.getFirstChild(); Node first = root.getFirstChild(); <span class="ReservedWord">int</span> number1 = Integer.decode(first.getFirstChild() .getNodeValue()); Node second = first.getNextSibling(); <span class="ReservedWord">int</span> number2 = Integer.decode(second.getFirstChild() .getNodeValue()); <span class="ReservedWord">return</span> sendSource(number1, number2); } <span class="ReservedWord">catch</span> (Exception e) { e.printStackTrace(); <span class="ReservedWord">throw</span> <span class="ReservedWord">new</span> RemoteException(<span class="String">"Error in provider endpoint"</span>); } } <span class="ReservedWord">private</span> Source sendSource(<span class="ReservedWord">int</span> number1, <span class="ReservedWord">int</span> number2) { <span class="ReservedWord">int</span> sum = number1 + number2; String body = <span class="String">"<ns:addNumbersResponse xmlns:ns =\"http://duke"</span> + <span class="String">".example.org\"><return>"</span> + sum + <span class="String">"</return></ns:addNumbersResponse>"</span>; Source source = <span class="ReservedWord">new</span> StreamSource(<span class="ReservedWord">new</span> ByteArrayInputStream(body.getBytes())); <span class="ReservedWord">return</span> source; } }</pre></div></div><br class="example-break"></div></div><div class="section" title="10.3.5. @javax.xml.ws.WebEndpoint"><div class="titlepage"><div><div><h4 class="title" id="javax-xml-ws-webendpoint-outline">10.3.5. <code class="literal">@javax.xml.ws.WebEndpoint</code></h4></div></div></div><p>Used to annotate the <code class="literal">getPortName()</code> methods of a generated service interface.</p><p>The information specified in this annotation is sufficient to uniquely identify a <code class="literal">wsdl:port</code> element inside a <code class="literal">wsdl:service</code>. The latter is determined based on the value of the <code class="literal">WebServiceClient</code> annotation on the generated service interface itself.</p><div class="table"><a name="d0e5287"></a><p class="title"><b>Table 13. <code class="literal">@javax.xml.ws.WebEndpoint</code> - Description of Properties</b></p><div class="table-contents"><table summary="@javax.xml.ws.WebEndpoint -
 Description of Properties" border="1"><colgroup><col width="16%"><col width="54%"><col width="30%"></colgroup><thead><tr><th>Property</th><th>Description</th><th>Default</th></tr></thead><tbody><tr><td><p><code class="literal">name</code></p></td><td><p>Defines the local name of the XML element representing the corresponding port in the WSDL.</p></td><td><p>""</p></td></tr></tbody></table></div></div><br class="table-break"><div class="section" title="10.3.5.1. Annotation Type Definition"><div class="titlepage"><div><div><h5 class="title" id="section-800546080791241">10.3.5.1. Annotation Type Definition</h5></div></div></div><div class="informalexample"><pre class="programlisting"><span class="Comment">/** * Used to annotate the <code>get<em>PortName</em>()</code> * methods of a generated service interface. * <p/> * <p>The information specified in this annotation is sufficient * to uniquely identify a <code>wsdl:port</code> element * inside a <code>wsdl:service</code>. The latter is * determined based on the value of the <code>WebServiceClient</code> * annotation on the generated service interface itself. * * @see javax.xml.ws.WebServiceClient * @since JAX-WS 2.0 */</span> <span class="Annotation">@Target({ElementType.METHOD})</span> <span class="Annotation">@Retention(RetentionPolicy.RUNTIME)</span> <span class="Annotation">@Documented</span> <span class="ReservedWord">public</span> <span class="Annotation">@interface</span> WebEndpoint { <span class="Comment">/** * The local name of the endpoint. */</span> String name() <span class="ReservedWord">default</span> <span class="String">""</span>; }</pre></div></div><div class="section" title="10.3.5.2. Examples"><div class="titlepage"><div><div><h5 class="title" id="section-969119628218757">10.3.5.2. Examples</h5></div></div></div><div class="example"><a name="d0e5325"></a><p class="title"><b>Example 17. <code class="literal">@javax.xml.ws.WebEndpoint</code> - Example</b></p><div class="example-contents"><pre class="programlisting"><span class="Annotation">@WebServiceClient(name = "AddNumbersImplService", targetNamespace = "http://server.fromjava/", wsdlLocation = "http://localhost:8080/jaxws-fromjava/addnumbers" + "?wsdl")</span> <span class="ReservedWord">public</span> <span class="ReservedWord">class</span> AddNumbersImplService <span class="ReservedWord">extends</span> Service { <span class="ReservedWord">private</span> <span class="ReservedWord">final</span> <span class="ReservedWord">static</span> URL WSDL_LOCATION; <span class="ReservedWord">private</span> <span class="ReservedWord">final</span> <span class="ReservedWord">static</span> QName ADDNUMBERSIMPLSERVICE = <span class="ReservedWord">new</span> QName (<span class="String">"http://server.fromjava/"</span>, <span class="String">"AddNumbersImplService"</span>); <span class="ReservedWord">private</span> <span class="ReservedWord">final</span> <span class="ReservedWord">static</span> QName ADDNUMBERSIMPLPORT = <span class="ReservedWord">new</span> QName (<span class="String">"http://server.fromjava/"</span>, <span class="String">"AddNumbersImplPort"</span>); <span class="ReservedWord">static</span> { URL url = null; <span class="ReservedWord">try</span> { url = <span class="ReservedWord">new</span> URL(<span class="String">"http://localhost:8080/jaxws-fromjava"</span> + <span class="String">"/addnumbers?wsdl"</span>); } <span class="ReservedWord">catch</span> (MalformedURLException e) { e.printStackTrace(); } WSDL_LOCATION = url; } <span class="ReservedWord">public</span> AddNumbersImplService(URL wsdlLocation, QName serviceName) { <span class="ReservedWord">super</span>(wsdlLocation, serviceName); } <span class="ReservedWord">public</span> AddNumbersImplService() { <span class="ReservedWord">super</span>(WSDL_LOCATION, ADDNUMBERSIMPLSERVICE); } <span class="Comment">/** * @return returns AddNumbersImpl */</span> <span class="Annotation">@WebEndpoint(name = "AddNumbersImplPort")</span> <span class="ReservedWord">public</span> AddNumbersImpl getAddNumbersImplPort() { <span class="ReservedWord">return</span> (AddNumbersImpl) <span class="ReservedWord">super</span>.getPort(ADDNUMBERSIMPLPORT, AddNumbersImpl.<span class="ReservedWord">class</span>); } }</pre></div></div><br class="example-break"></div></div><div class="section" title="10.3.6. @javax.xml.ws.WebFault"><div class="titlepage"><div><div><h4 class="title" id="javax-xml-ws-webfault-outline">10.3.6. <code class="literal">@javax.xml.ws.WebFault</code></h4></div></div></div><p>This annotation is generated by the JAX-WS tools into service specific exception classes generated from a WSDL to customize the local and namespace name of the fault element and the name of the fault bean and to mark the service specific exception as one generated from WSDL. The reason that the JAX-WS needs to know if a service specific exception is generated from a WSDL or not is because these exceptions will already have a fault bean generated for them. The name of this fault bean is not the same name as the one generated from a Java service specific exception class. For more information on this topic, please refer to section 3.6 of the <a class="link" href="http://www.jcp.org/en/jsr/detail?id=224" target="_top">JAX-WS 2.0</a> specification.</p><div class="table"><a name="d0e5341"></a><p class="title"><b>Table 14. <code class="literal">@javax.xml.ws.WebFault</code> - Description of Properties</b></p><div class="table-contents"><table summary="@javax.xml.ws.WebFault - Description
 of Properties" border="1"><colgroup><col width="16%"><col width="54%"><col width="30%"></colgroup><thead><tr><th>Property</th><th>Description</th><th>Default</th></tr></thead><tbody><tr><td><p><code class="literal">name</code></p></td><td><p>Defines the local name of the XML element representing the corresponding fault in the WSDL.</p></td><td><p>""</p></td></tr><tr><td><p><code class="literal">targetNamespace</code></p></td><td><p>Defines the namespace of the XML element representing the corresponding fault in the WSDL.</p></td><td><p>""</p></td></tr><tr><td><p><code class="literal">faultBean</code></p></td><td><p>The qualified name of the Java class that represents the detail of the fault message.</p></td><td><p>""</p></td></tr></tbody></table></div></div><br class="table-break"><div class="section" title="10.3.6.1. Annotation Type Definition"><div class="titlepage"><div><div><h5 class="title" id="section-4120261211514535">10.3.6.1. Annotation Type Definition</h5></div></div></div><div class="informalexample"><pre class="programlisting"><span class="Comment">/** * Used to annotate service specific exception classes to customize * to the local and namespace name of the fault element and the name * of the fault bean. * * @since JAX-WS 2.0 */</span> <span class="Annotation">@Target({ElementType.TYPE})</span> <span class="Annotation">@Retention(RetentionPolicy.RUNTIME)</span> <span class="Annotation">@Documented</span> <span class="ReservedWord">public</span> <span class="Annotation">@interface</span> WebFault { <span class="Comment">/** * Element's local name. */</span> <span class="ReservedWord">public</span> String name() <span class="ReservedWord">default</span> <span class="String">""</span>; <span class="Comment">/** * Element's namespace name. */</span> <span class="ReservedWord">public</span> String targetNamespace() <span class="ReservedWord">default</span> <span class="String">""</span>; <span class="Comment">/** * Fault bean name. */</span> <span class="ReservedWord">public</span> String faultBean() <span class="ReservedWord">default</span> <span class="String">""</span>; <span class="Comment">/** * wsdl:Message's name. Default name is the exception's class name. * * @since JAX-WS 2.2 */</span> <span class="ReservedWord">public</span> String messageName() <span class="ReservedWord">default</span> <span class="String">""</span>; }</pre></div></div><div class="section" title="10.3.6.2. Examples"><div class="titlepage"><div><div><h5 class="title" id="section-36622117177507">10.3.6.2. Examples</h5></div></div></div><div class="example"><a name="d0e5401"></a><p class="title"><b>Example 18. <code class="literal">@javax.xml.ws.WebFault</code> - Example</b></p><div class="example-contents"><pre class="programlisting"><span class="Annotation">@javax.xml.ws.WebFault(name = "AddNumbersException", targetNamespace = "http://server.fromjava/jaxws")</span> <span class="ReservedWord">public</span> <span class="ReservedWord">class</span> AddNumbersException_Exception <span class="ReservedWord">extends</span> Exception { <span class="ReservedWord">private</span> fromjava.client.AddNumbersException faultInfo; <span class="ReservedWord">public</span> AddNumbersException_Exception(String message, fromjava.client.AddNumbersException faultInfo) { <span class="ReservedWord">super</span>(message); <span class="ReservedWord">this</span>.faultInfo = faultInfo; } <span class="ReservedWord">public</span> AddNumbersException_Exception(String message, fromjava.client .AddNumbersException faultInfo, Throwable cause) { <span class="ReservedWord">super</span>(message, cause); <span class="ReservedWord">this</span>.faultInfo = faultInfo; } <span class="ReservedWord">public</span> fromjava.client.AddNumbersException getFaultInfo() { <span class="ReservedWord">return</span> faultInfo; } }</pre></div></div><br class="example-break"></div></div><div class="section" title="10.3.7. @javax.xml.ws.WebServiceClient"><div class="titlepage"><div><div><h4 class="title" id="javax-xml-ws-webserviceclient-outline">10.3.7. <code class="literal">@javax.xml.ws.WebServiceClient</code></h4></div></div></div><p>The information specified in this annotation is sufficient to uniquely identify a <code class="literal">wsdl:service</code> element inside a WSDL document. This <code class="literal">wsdl:service</code> element represents the Web service for which the generated service interface provides a client view.</p><div class="table"><a name="d0e5420"></a><p class="title"><b>Table 15. <code class="literal">@javax.xml.ws.WebServiceClient</code> - Description of Properties</b></p><div class="table-contents"><table summary="@javax.xml.ws.WebServiceClient -
 Description of Properties" border="1"><colgroup><col width="16%"><col width="54%"><col width="30%"></colgroup><thead><tr><th>Property</th><th>Description</th><th>Default</th></tr></thead><tbody><tr><td><p><code class="literal">name</code></p></td><td><p>Defines the local name of the <code class="literal">wsdl:serviceName</code> in the WSDL.</p></td><td><p>""</p></td></tr><tr><td><p><code class="literal">targetNamespace</code></p></td><td><p>Defines the namespace for the <code class="literal">wsdl:serviceName</code> in the WSDL.</p></td><td><p>""</p></td></tr><tr><td><p><code class="literal">wsdlLocation</code></p></td><td><p>Specifies the location of the WSDL that defines this service.</p></td><td><p>""</p></td></tr></tbody></table></div></div><br class="table-break"><div class="section" title="10.3.7.1. Annotation Type Definition"><div class="titlepage"><div><div><h5 class="title" id="section-01521047797341">10.3.7.1. Annotation Type Definition</h5></div></div></div><div class="informalexample"><pre class="programlisting"><span class="Comment">/** * Used to annotate a generated service interface. * <p/> * <p>The information specified in this annotation is sufficient * to uniquely identify a <code>wsdl:service</code> * element inside a WSDL document. This <code>wsdl:service</code> * element represents the Web service for which the generated * service interface provides a client view. * * @since JAX-WS 2.0 */</span> <span class="Annotation">@Target({ElementType.TYPE})</span> <span class="Annotation">@Retention(RetentionPolicy.RUNTIME)</span> <span class="Annotation">@Documented</span> <span class="ReservedWord">public</span> <span class="Annotation">@interface</span> WebServiceClient { <span class="Comment">/** * The local name of the Web service. */</span> String name() <span class="ReservedWord">default</span> <span class="String">""</span>; <span class="Comment">/** * The namespace for the Web service. */</span> String targetNamespace() <span class="ReservedWord">default</span> <span class="String">""</span>; <span class="Comment">/** * The location of the WSDL document for the service (a URL). */</span> String wsdlLocation() <span class="ReservedWord">default</span> <span class="String">""</span>; }</pre></div></div><div class="section" title="10.3.7.2. Examples"><div class="titlepage"><div><div><h5 class="title" id="section-616559816681746">10.3.7.2. Examples</h5></div></div></div><div class="example"><a name="d0e5486"></a><p class="title"><b>Example 19. <code class="literal">@javax.xml.ws.WebServiceClient</code> - Example</b></p><div class="example-contents"><pre class="programlisting"><span class="Annotation">@WebServiceClient(name = "AddNumbersImplService", targetNamespace = "http://server.fromjava/", wsdlLocation = "http://localhost:8080/jaxws-fromjava/addnumbers" + "?wsdl")</span> <span class="ReservedWord">public</span> <span class="ReservedWord">class</span> AddNumbersImplService <span class="ReservedWord">extends</span> Service { <span class="ReservedWord">private</span> <span class="ReservedWord">final</span> <span class="ReservedWord">static</span> URL WSDL_LOCATION; <span class="ReservedWord">private</span> <span class="ReservedWord">final</span> <span class="ReservedWord">static</span> QName ADDNUMBERSIMPLSERVICE = <span class="ReservedWord">new</span> QName (<span class="String">"http://server.fromjava/"</span>, <span class="String">"AddNumbersImplService"</span>); <span class="ReservedWord">private</span> <span class="ReservedWord">final</span> <span class="ReservedWord">static</span> QName ADDNUMBERSIMPLPORT = <span class="ReservedWord">new</span> QName (<span class="String">"http://server.fromjava/"</span>, <span class="String">"AddNumbersImplPort"</span>); <span class="ReservedWord">static</span> { URL url = null; <span class="ReservedWord">try</span> { url = <span class="ReservedWord">new</span> URL(<span class="String">"http://localhost:8080/jaxws-fromjava"</span> + <span class="String">"/addnumbers?wsdl"</span>); } <span class="ReservedWord">catch</span> (MalformedURLException e) { e.printStackTrace(); } WSDL_LOCATION = url; } <span class="ReservedWord">public</span> AddNumbersImplService(URL wsdlLocation, QName serviceName) { <span class="ReservedWord">super</span>(wsdlLocation, serviceName); } <span class="ReservedWord">public</span> AddNumbersImplService() { <span class="ReservedWord">super</span>(WSDL_LOCATION, ADDNUMBERSIMPLSERVICE); } <span class="Comment">/** * @return returns AddNumbersImpl */</span> <span class="Annotation">@WebEndpoint(name = "AddNumbersImplPort")</span> <span class="ReservedWord">public</span> AddNumbersImpl getAddNumbersImplPort() { <span class="ReservedWord">return</span> (AddNumbersImpl) <span class="ReservedWord">super</span>.getPort(ADDNUMBERSIMPLPORT, AddNumbersImpl.<span class="ReservedWord">class</span>); } }</pre></div></div><br class="example-break"></div></div><div class="section" title="10.3.8. @javax.xml.ws.WebServiceProvider"><div class="titlepage"><div><div><h4 class="title" id="javax-xml-ws-webserviceprovider-outline">10.3.8. <code class="literal">@javax.xml.ws.WebServiceProvider</code></h4></div></div></div><p>Annotation used to annotate a <code class="literal">Provider</code> implementation class.</p><div class="table"><a name="d0e5502"></a><p class="title"><b>Table 16. <code class="literal">@javax.xml.ws.WebServiceProvider</code> - Description of Properties</b></p><div class="table-contents"><table summary="@javax.xml.ws.WebServiceProvider -
 Description of Properties" border="1"><colgroup><col width="16%"><col width="54%"><col width="30%"></colgroup><thead><tr><th>Property</th><th>Description</th><th>Default</th></tr></thead><tbody><tr><td><p><code class="literal">targetNamespace</code></p></td><td><p>The XML namespace of the the WSDL and some of the XML elements generated from this web service. Most of the XML elements will be in the namespace according to the JAXB mapping rules.</p></td><td><p>The namespace mapped from the package name containing the web service according to section 3.2 of the <a class="link" href="http://www.jcp.org/en/jsr/detail?id=224" target="_top">JAX-WS 2.0</a> specification.</p></td></tr><tr><td><p><code class="literal">serviceName</code></p></td><td><p>The Service name of the web service: <code class="literal">wsdl:service</code></p></td><td><p>The unqualified name of the Java class or interface + "Service"</p></td></tr><tr><td><p><code class="literal">portName</code></p></td><td><p>The <code class="literal">wsdl:portName</code></p></td><td><p></p></td></tr><tr><td><p><code class="literal">wsdlLocation</code></p></td><td><p>Location of the WSDL description for the service</p></td><td><p></p></td></tr></tbody></table></div></div><br class="table-break"><div class="section" title="10.3.8.1. Annotation Type Definition"><div class="titlepage"><div><div><h5 class="title" id="section-194282375923834">10.3.8.1. Annotation Type Definition</h5></div></div></div><div class="informalexample"><pre class="programlisting"><span class="Comment">/** * Used to annotate a Provider implementation class. * * @since JAX-WS 2.0 * @see javax.xml.ws.Provider */</span> <span class="Annotation">@Target(ElementType.TYPE)</span> <span class="Annotation">@Retention(RetentionPolicy.RUNTIME)</span> <span class="Annotation">@Documented</span> <span class="ReservedWord">public</span> <span class="Annotation">@interface</span> WebServiceProvider { <span class="Comment">/** * Location of the WSDL description for the service. */</span> String wsdlLocation() <span class="ReservedWord">default</span> <span class="String">""</span>; <span class="Comment">/** * Service name. */</span> String serviceName() <span class="ReservedWord">default</span> <span class="String">""</span>; <span class="Comment">/** * Target namespace for the service */</span> String targetNamespace() <span class="ReservedWord">default</span> <span class="String">""</span>; <span class="Comment">/** * Port name. */</span> String portName() <span class="ReservedWord">default</span> <span class="String">""</span>; }</pre></div></div><div class="section" title="10.3.8.2. Examples"><div class="titlepage"><div><div><h5 class="title" id="section-5041062451497706">10.3.8.2. Examples</h5></div></div></div><div class="example"><a name="d0e5578"></a><p class="title"><b>Example 20. <code class="literal">@javax.xml.ws.WebServiceProvider</code> - Example</b></p><div class="example-contents"><pre class="programlisting"><span class="Annotation">@ServiceMode(value = Service.Mode.PAYLOAD)</span> <span class="Annotation">@WebServiceProvider(wsdlLocation = "WEB-INF/wsdl/AddNumbers.wsdl")</span> <span class="ReservedWord">public</span> <span class="ReservedWord">class</span> AddNumbersImpl <span class="ReservedWord">implements</span> Provider { <span class="ReservedWord">public</span> Source invoke(Source source) { <span class="ReservedWord">try</span> { DOMResult dom = <span class="ReservedWord">new</span> DOMResult(); Transformer trans = TransformerFactory.newInstance() .newTransformer(); trans.transform(source, dom); Node node = dom.getNode(); Node root = node.getFirstChild(); Node first = root.getFirstChild(); <span class="ReservedWord">int</span> number1 = Integer.decode(first.getFirstChild() .getNodeValue()); Node second = first.getNextSibling(); <span class="ReservedWord">int</span> number2 = Integer.decode(second.getFirstChild() .getNodeValue()); <span class="ReservedWord">return</span> sendSource(number1, number2); } <span class="ReservedWord">catch</span> (Exception e) { e.printStackTrace(); <span class="ReservedWord">throw</span> <span class="ReservedWord">new</span> RuntimeException(<span class="String">"Error in provider endpoint"</span>, e); } } <span class="ReservedWord">private</span> Source sendSource(<span class="ReservedWord">int</span> number1, <span class="ReservedWord">int</span> number2) { <span class="ReservedWord">int</span> sum = number1 + number2; String body = <span class="String">""</span> + sum + <span class="String">""</span>; Source source = <span class="ReservedWord">new</span> StreamSource(<span class="ReservedWord">new</span> ByteArrayInputStream(body.getBytes())); <span class="ReservedWord">return</span> source; } }</pre></div></div><br class="example-break"></div></div><div class="section" title="10.3.9. @javax.xml.ws.WebServiceRef"><div class="titlepage"><div><div><h4 class="title" id="javax-xml-ws-webserviceref-outline">10.3.9. <code class="literal">@javax.xml.ws.WebServiceRef</code></h4></div></div></div><p>The <code class="literal">WebServiceRef</code> annotation is used to define a reference to a web service and (optionally) an injection target for it. Web service references are resources in the Java EE 5 sense.</p><div class="table"><a name="d0e5594"></a><p class="title"><b>Table 17. <code class="literal">@javax.xml.ws.WebServiceRef</code> - Description of Properties</b></p><div class="table-contents"><table summary="@javax.xml.ws.WebServiceRef -
 Description of Properties" border="1"><colgroup><col width="16%"><col width="54%"><col width="30%"></colgroup><thead><tr><th>Property</th><th>Description</th><th>Default</th></tr></thead><tbody><tr><td><p><code class="literal">name</code></p></td><td><p>The JNDI name of the resource. For field annotations, the default is the field name. For method annotations, the default is the JavaBeans property name corresponding to the method. For class annotations, there is no default and this must be specified.</p></td><td><p></p></td></tr><tr><td><p><code class="literal">type</code></p></td><td><p>The Java type of the resource. For field annotations, the default is the type of the field. For method annotations, the default is the type of the JavaBeans property. For class annotations, there is no default and this must be specified.</p></td><td><p></p></td></tr><tr><td><p><code class="literal">mappedName</code></p></td><td><p>A product specific name that this resource should be mapped to.</p></td><td><p></p></td></tr><tr><td><p><code class="literal">value</code></p></td><td><p>The service class, always a type extending <code class="literal">javax.xml.ws.Service</code>. This element must be specified whenever the type of the reference is a service endpoint interface.</p></td><td><p></p></td></tr><tr><td><p><code class="literal">wsdlLocation</code></p></td><td><p>Location of the WSDL description for the service</p></td><td><p></p></td></tr></tbody></table></div></div><br class="table-break"><div class="section" title="10.3.9.1. Annotation Type Definition"><div class="titlepage"><div><div><h5 class="title" id="section-910589920332548">10.3.9.1. Annotation Type Definition</h5></div></div></div><div class="informalexample"><pre class="programlisting"><span class="Comment">/** * The <code>WebServiceRef</code> annotation is used to * define a reference to a web service and * (optionally) an injection target for it. * It can be used to inject both service and proxy * instances. These injected references are not thread safe. * If the references are accessed by multiple threads, * usual synchronization techinques can be used to * support multiple threads. * <p/> * Web service references are resources in the Java EE 5 sense. * The annotations (for example, {@link Addressing}) annotated with * meta-annotation {@link WebServiceFeatureAnnotation} * can be used in conjunction with <code>WebServiceRef</code>. * The created reference MUST be configured with annotation's web service * feature. * <p/> * If a JAX-WS implementation encounters an unsupported or unrecognized * annotation annotated with the <code>WebServiceFeatureAnnotation</code> * that is specified with <code>WebServiceRef</code>, * an ERROR MUST be given. * * @see javax.annotation.Resource * @see WebServiceFeatureAnnotation * @since JAX-WS 2.0 */</span> <span class="Annotation">@Target({ElementType.TYPE, ElementType.METHOD, ElementType.FIELD})</span> <span class="Annotation">@Retention(RetentionPolicy.RUNTIME)</span> <span class="Annotation">@Documented</span> <span class="ReservedWord">public</span> <span class="Annotation">@interface</span> WebServiceRef { <span class="Comment">/** * The JNDI name of the resource. For field annotations, * the default is the field name. For method annotations, * the default is the JavaBeans property name corresponding * to the method. For class annotations, there is no default * and this MUST be specified. * <p/> * The JNDI name can be absolute(with any logical namespace) or * relative * to JNDI <code>java:comp/env</code> namespace. */</span> String name() <span class="ReservedWord">default</span> <span class="String">""</span>; <span class="Comment">/** * The Java type of the resource. For field annotations, * the default is the type of the field. For method annotations, * the default is the type of the JavaBeans property. * For class annotations, there is no default and this MUST be * specified. */</span> Class<?> type() <span class="ReservedWord">default</span> Object.<span class="ReservedWord">class</span>; <span class="Comment">/** * A product specific name that this resource should be mapped to. * The name of this resource, as defined by the <code>name</code> * element or defaulted, is a name that is local to the application * component using the resource. (When a relative JNDI name * is specified, then it's a name in the JNDI * <code>java:comp/env</code> namespace.) Many application servers * provide a way to map these local names to names of resources * known to the application server. This mapped name is often a * <i>global</i> JNDI name, but may be a name of any form. * <p/> * Application servers are not required to support any particular * form or type of mapped name, nor the ability to use mapped names. * The mapped name is product-dependent and often * installation-dependent. * No use of a mapped name is portable. */</span> String mappedName() <span class="ReservedWord">default</span> <span class="String">""</span>; <span class="Comment">/** * The service class, alwiays a type extending * <code>javax.xml.ws.Service</code>. This element MUST be specified * whenever the type of the reference is a service endpoint interface. */</span> <span class="Comment">// 2.1 has Class value() default Object.class;</span> <span class="Comment">// Fixing this raw Class type correctly in 2.2 API. This shouldn't </span> <span class="Comment">// cause</span> <span class="Comment">// any compatibility issues for applications.</span> Class<? <span class="ReservedWord">extends</span> Service> value() <span class="ReservedWord">default</span> Service.<span class="ReservedWord">class</span>; <span class="Comment">/** * A URL pointing to the WSDL document for the web service. * If not specified, the WSDL location specified by annotations * on the resource type is used instead. */</span> String wsdlLocation() <span class="ReservedWord">default</span> <span class="String">""</span>; <span class="Comment">/** * A portable JNDI lookup name that resolves to the target * web service reference. * * @since JAX-WS 2.2 */</span> String lookup() <span class="ReservedWord">default</span> <span class="String">""</span>; }</pre></div></div></div><div class="section" title="10.3.10. @javax.xml.ws.Action"><div class="titlepage"><div><div><h4 class="title" id="javax-xml-ws-action-outline">10.3.10. <code class="literal">@javax.xml.ws.Action</code></h4></div></div></div><p>The <code class="literal">Action</code> annotation allows explicit association of <code class="literal">Action</code> message addressing property with <code class="literal">input</code>, <code class="literal">output</code>, and <code class="literal">fault</code> messages of the mapped WSDL operation.</p><p>This annotation can be specified on each method of a service endpoint interface or implementation. For such a method, the mapped operation in the generated WSDL contains explicit <code class="literal">wsaw:Action</code> attribute on the WSDL <code class="literal">input</code>, <code class="literal">output</code> and <code class="literal">fault</code> messages of the WSDL <code class="literal">operation</code> based upon which attributes of the <code class="literal">Action</code> annotation have been specified.</p><div class="table"><a name="d0e5712"></a><p class="title"><b>Table 18. <code class="literal">@javax.xml.ws.Action</code> - Description of Properties</b></p><div class="table-contents"><table summary="@javax.xml.ws.Action - Description
 of Properties" border="1"><colgroup><col width="16%"><col width="54%"><col width="30%"></colgroup><thead><tr><th>Property</th><th>Description</th><th>Default</th></tr></thead><tbody><tr><td><p><code class="literal">input</code></p></td><td><p>Explicit value of <code class="literal">Action</code> message addressing property for the <code class="literal">input</code> message of the operation. If the value is "", then no <code class="literal">wsaw:Action</code> is generated.</p></td><td><p>""</p></td></tr><tr><td><p><code class="literal">ouput</code></p></td><td><p>Explicit value of <code class="literal">Action</code> message addressing property for the <code class="literal">output</code> message of the operation. If the value is "", then no <code class="literal">wsaw:Action</code> is generated.</p></td><td><p>""</p></td></tr><tr><td><p><code class="literal">fault</code></p></td><td><p>Explicit value of <code class="literal">Action</code> message addressing property for the <code class="literal">fault</code> message(s) of the operation. Each exception that is mapped to a fault and requires explicit <code class="literal">Action</code> message addressing property, need to be specified as a value in this property using FaultAction annotation.</p></td><td><p>{}</p></td></tr></tbody></table></div></div><br class="table-break"><div class="section" title="10.3.10.1. Annotation Type Definition"><div class="titlepage"><div><div><h5 class="title" id="section-51086889743311215">10.3.10.1. Annotation Type Definition</h5></div></div></div><div class="informalexample"><pre class="programlisting"><span class="Comment">/** * The <code>Action</code> annotation allows explicit association of a * WS-Addressing <code>Action</code> message addressing property with * <code>input</code>, <code>output</code>, and * <code>fault</code> messages of the mapped WSDL operation. * <p/> * This annotation can be specified on each method of a service endpoint * interface. * For such a method, the mapped operation in the generated WSDL's * <code>wsam:Action</code> attribute on the WSDL <code>input</code>, * <code>output</code> and <code>fault</code> messages of the WSDL * <code>operation</code> * is based upon which attributes of the <code>Action</code> annotation * have been specified. * For the exact computation of <code>wsam:Action</code> values for the * messages, refer * to the algorithm in the JAX-WS specification. * * @see FaultAction * @since JAX-WS 2.1 */</span> <span class="Annotation">@Documented</span> <span class="Annotation">@Retention(RetentionPolicy.RUNTIME)</span> <span class="Annotation">@Target(ElementType.METHOD)</span> <span class="ReservedWord">public</span> <span class="Annotation">@interface</span> Action { <span class="Comment">/** * Explicit value of the WS-Addressing <code>Action</code> message * addressing property for the <code>input</code> * message of the operation. */</span> String input() <span class="ReservedWord">default</span> <span class="String">""</span>; <span class="Comment">/** * Explicit value of the WS-Addressing <code>Action</code> message * addressing property for the <code>output</code> * message of the operation. */</span> String output() <span class="ReservedWord">default</span> <span class="String">""</span>; <span class="Comment">/** * Explicit value of the WS-Addressing <code>Action</code> message * addressing property for the <code>fault</code> * message(s) of the operation. Each exception that is mapped to a * fault and requires an explicit WS-Addressing * <code>Action</code> message addressing property, * needs to be specified as a value in this property * using {@link FaultAction} annotation. */</span> FaultAction[] fault() <span class="ReservedWord">default</span> {}; }</pre></div></div><div class="section" title="10.3.10.2. Examples"><div class="titlepage"><div><div><h5 class="title" id="section-386040099353688">10.3.10.2. Examples</h5></div></div></div><div class="example"><a name="d0e5799"></a><p class="title"><b>Example 21. <code class="literal">@javax.xml.ws.Action</code> - Example 1 - Specify explicit values for <code class="literal">Action</code> message addressing property for <code class="literal">input</code> and <code class="literal">output</code> messages.</b></p><div class="example-contents"><pre class="programlisting"><span class="Annotation">@javax.jws.WebService</span> <span class="ReservedWord">public</span> <span class="ReservedWord">class</span> AddNumbersImpl { <span class="Annotation">@javax.xml.ws.Action( input = "http://example.com/inputAction", output = "http://example.com/outputAction")</span> <span class="ReservedWord">public</span> <span class="ReservedWord">int</span> addNumbers(<span class="ReservedWord">int</span> number1, <span class="ReservedWord">int</span> number2) { <span class="ReservedWord">return</span> number1 + number2; } }</pre><p>The generated WSDL looks like:</p><pre class="programlisting"><span class="ReservedWord"><definitions</span> <span class="Identifier">targetNamespace</span>=<span class="String">"http://example.com/numbers"</span> <span class="Identifier">...></span> <span class="Identifier">...</span> <span class="Identifier"><portType</span> <span class="Identifier">name</span>=<span class="String">"AddNumbersPortType"</span><span class="ReservedWord">></span> <span class="ReservedWord"><operation</span> <span class="Identifier">name</span>=<span class="String">"AddNumbers"</span><span class="ReservedWord">></span> <span class="ReservedWord"><input</span> <span class="Identifier">message</span>=<span class="String">"tns:AddNumbersInput"</span> <span class="Identifier">name</span>=<span class="String">"Parameters"</span> <span class="Identifier">wsaw:Action</span>=<span class="String">"http://example.com/inputAction"</span><span class="ReservedWord">/></span> <span class="ReservedWord"><output</span> <span class="Identifier">message</span>=<span class="String">"tns:AddNumbersOutput"</span> <span class="Identifier">name</span>=<span class="String">"Result"</span> <span class="Identifier">wsaw:Action</span>=<span class="String">"http://example.com/outputAction"</span><span class="ReservedWord">/></span> <span class="ReservedWord"></operation></span> <span class="ReservedWord"></portType></span> ... <span class="ReservedWord"></definitions></span></pre></div></div><br class="example-break"><div class="example"><a name="d0e5819"></a><p class="title"><b>Example 22. <code class="literal">@javax.xml.ws.Action</code> - Example 2 - Specify explicit value for <code class="literal">Action</code> message addressing property for only the <code class="literal">input</code> message.</b></p><div class="example-contents"><p>The default values are used for the <code class="literal">output</code> message.</p><pre class="programlisting"><span class="Annotation">@javax.jws.WebService</span> <span class="ReservedWord">public</span> <span class="ReservedWord">class</span> AddNumbersImpl { <span class="Annotation">@javax.xml.ws.Action(input = "http://example.com/inputAction")</span> <span class="ReservedWord">public</span> <span class="ReservedWord">int</span> addNumbers(<span class="ReservedWord">int</span> number1, <span class="ReservedWord">int</span> number2) { <span class="ReservedWord">return</span> number1 + number2; } }</pre><p>The generated WSDL looks like:</p><pre class="programlisting"><span class="ReservedWord"><definitions</span> <span class="Identifier">targetNamespace</span>=<span class="String">"http://example.com/numbers"</span> <span class="Identifier">...></span> <span class="Identifier">...</span> <span class="Identifier"><portType</span> <span class="Identifier">name</span>=<span class="String">"AddNumbersPortType"</span><span class="ReservedWord">></span> <span class="ReservedWord"><operation</span> <span class="Identifier">name</span>=<span class="String">"AddNumbers"</span><span class="ReservedWord">></span> <span class="ReservedWord"><input</span> <span class="Identifier">message</span>=<span class="String">"tns:AddNumbersInput"</span> <span class="Identifier">name</span>=<span class="String">"Parameters"</span> <span class="Identifier">wsaw:Action</span>=<span class="String">"http://example.com/inputAction"</span><span class="ReservedWord">/></span> <span class="ReservedWord"><output</span> <span class="Identifier">message</span>=<span class="String">"tns:AddNumbersOutput"</span> <span class="Identifier">name</span>=<span class="String">"Result"</span><span class="ReservedWord">/></span> <span class="ReservedWord"></operation></span> <span class="ReservedWord"></portType></span> ... <span class="ReservedWord"></definitions></span></pre><p>It is legitimate to specify an explicit value for <code class="literal">Action</code> message addressing property for <code class="literal">output</code> message only. In this case, a default value of <code class="literal">wsaw:Action</code> is used for the <code class="literal">input</code> message.</p></div></div><br class="example-break"><div class="example"><a name="d0e5855"></a><p class="title"><b>Example 23. <code class="literal">@javax.xml.ws.Action</code> - Example 3 - <code class="literal">@FaultAction</code></b></p><div class="example-contents"><p>See <code class="literal"><a class="xref" href="#javax-xml-ws-faultaction-outline" title="10.3.11. @javax.xml.ws.FaultAction"><code class="literal">@javax.xml.ws.FaultAction</code></a></code> for an example of how to specify an explicit value for <code class="literal">Action</code> message addressing property for the <code class="literal">fault</code> message.</p></div></div><br class="example-break"></div></div><div class="section" title="10.3.11. @javax.xml.ws.FaultAction"><div class="titlepage"><div><div><h4 class="title" id="javax-xml-ws-faultaction-outline">10.3.11. <code class="literal">@javax.xml.ws.FaultAction</code></h4></div></div></div><p>The <code class="literal">FaultAction</code> annotation is used inside an <code class="literal">Action</code> annotation to allow an explicit association of <code class="literal">Action</code> message addressing property with the <code class="literal">fault</code> messages of the WSDL operation mapped from the exception class.</p><p>The <code class="literal">fault</code> message in the generated WSDL operation mapped for <code class="literal">className</code> class contains explicit <code class="literal">wsaw:Action</code> attribute.</p><div class="table"><a name="d0e5902"></a><p class="title"><b>Table 19. <code class="literal">@javax.xml.ws.FaultAction</code> - Description of Properties</b></p><div class="table-contents"><table summary="@javax.xml.ws.FaultAction -
 Description of Properties" border="1"><colgroup><col width="16%"><col width="54%"><col width="30%"></colgroup><thead><tr><th>Property</th><th>Description</th><th>Default</th></tr></thead><tbody><tr><td><p><code class="literal">className</code></p></td><td><p>Name of the exception class</p></td><td><p>there is no default and is required.</p></td></tr><tr><td><p><code class="literal">value</code></p></td><td><p>Value of <code class="literal">Action</code> message addressing property for the exception</p></td><td><p>""</p></td></tr></tbody></table></div></div><br class="table-break"><div class="section" title="10.3.11.1. Annotation Type Definition"><div class="titlepage"><div><div><h5 class="title" id="section-2290523806237594">10.3.11.1. Annotation Type Definition</h5></div></div></div><div class="informalexample"><pre class="programlisting"><span class="Annotation">@Documented</span> <span class="Annotation">@Retention(RetentionPolicy.RUNTIME)</span> <span class="Annotation">@Target(ElementType.METHOD)</span> <span class="ReservedWord">public</span> <span class="Annotation">@interface</span> FaultAction { <span class="Comment">/** * Name of the exception class */</span> Class<? <span class="ReservedWord">extends</span> Exception> className(); <span class="Comment">/** * Value of WS-Addressing <code>Action</code> message addressing * property for the exception */</span> String value() <span class="ReservedWord">default</span> <span class="String">""</span>; }</pre></div></div><div class="section" title="10.3.11.2. Examples"><div class="titlepage"><div><div><h5 class="title" id="section-139653992039007">10.3.11.2. Examples</h5></div></div></div><div class="example"><a name="d0e5954"></a><p class="title"><b>Example 24. <code class="literal">@javax.xml.ws.FaultAction</code> - Example 1 - Specify explicit values for <code class="literal">Action</code> message addressing property for the <code class="literal">input</code>, <code class="literal">output</code> and <code class="literal">fault</code> message if the Java method throws only one service specific exception.</b></p><div class="example-contents"><pre class="programlisting"><span class="Annotation">@javax.jws.WebService</span> <span class="ReservedWord">public</span> <span class="ReservedWord">class</span> AddNumbersImpl { <span class="Annotation">@javax.xml.ws.Action( input = "http://example.com/inputAction", output = "http://example.com/outputAction", fault = { @javax.xml.ws.FaultAction(className = AddNumbersException.class, value = "http://example.com/faultAction")})</span> <span class="ReservedWord">public</span> <span class="ReservedWord">int</span> addNumbers(<span class="ReservedWord">int</span> number1, <span class="ReservedWord">int</span> number2) <span class="ReservedWord">throws</span> AddNumbersException { <span class="ReservedWord">return</span> number1 + number2; } }</pre><p>The generated WSDL looks like:</p><pre class="programlisting"><span class="ReservedWord"><definitions</span> <span class="Identifier">targetNamespace</span>=<span class="String">"http://example.com/numbers"</span> <span class="Identifier">...></span> <span class="Identifier">...</span> <span class="Identifier"><portType</span> <span class="Identifier">name</span>=<span class="String">"AddNumbersPortType"</span><span class="ReservedWord">></span> <span class="ReservedWord"><operation</span> <span class="Identifier">name</span>=<span class="String">"AddNumbers"</span><span class="ReservedWord">></span> <span class="ReservedWord"><input</span> <span class="Identifier">message</span>=<span class="String">"tns:AddNumbersInput"</span> <span class="Identifier">name</span>=<span class="String">"Parameters"</span> <span class="Identifier">wsaw:Action</span>=<span class="String">"http://example.com/inputAction"</span><span class="ReservedWord">/></span> <span class="ReservedWord"><output</span> <span class="Identifier">message</span>=<span class="String">"tns:AddNumbersOutput"</span> <span class="Identifier">name</span>=<span class="String">"Result"</span> <span class="Identifier">wsaw:Action</span>=<span class="String">"http://example.com/outputAction"</span><span class="ReservedWord">/></span> <span class="ReservedWord"><fault</span> <span class="Identifier">message</span>=<span class="String">"tns:AddNumbersException"</span> <span class="Identifier">name</span>=<span class="String">"AddNumbersException"</span> <span class="Identifier">wsaw:Action</span>=<span class="String">"http://example.com/faultAction"</span><span class="ReservedWord">/></span> <span class="ReservedWord"></operation></span> <span class="ReservedWord"></portType></span> ... <span class="ReservedWord"></definitions></span></pre></div></div><br class="example-break"><div class="example"><a name="d0e5977"></a><p class="title"><b>Example 25. <code class="literal">@javax.xml.ws.FaultAction</code> - Example 1 - Specify explicit values for <code class="literal">Action</code> message addressing property if the Java method throws only one service specific exception, without specifying the values for <code class="literal">input</code> and <code class="literal">output</code> messages.</b></p><div class="example-contents"><pre class="programlisting"><span class="Annotation">@javax.jws.WebService</span> <span class="ReservedWord">public</span> <span class="ReservedWord">class</span> AddNumbersImpl { <span class="Annotation">@javax.xml.ws.Action( fault = {@javax.xml.ws.FaultAction(className = AddNumbersException.class, value = "http://example.com/faultAction")})</span> <span class="ReservedWord">public</span> <span class="ReservedWord">int</span> addNumbers(<span class="ReservedWord">int</span> number1, <span class="ReservedWord">int</span> number2) <span class="ReservedWord">throws</span> AddNumbersException { <span class="ReservedWord">return</span> number1 + number2; } }</pre><p>The generated WSDL looks like:</p><pre class="programlisting"><span class="ReservedWord"><definitions</span> <span class="Identifier">targetNamespace</span>=<span class="String">"http://example.com/numbers"</span> <span class="Identifier">...></span> <span class="Identifier">...</span> <span class="Identifier"><portType</span> <span class="Identifier">name</span>=<span class="String">"AddNumbersPortType"</span><span class="ReservedWord">></span> <span class="ReservedWord"><operation</span> <span class="Identifier">name</span>=<span class="String">"AddNumbers"</span><span class="ReservedWord">></span> <span class="ReservedWord"><input</span> <span class="Identifier">message</span>=<span class="String">"tns:AddNumbersInput"</span> <span class="Identifier">name</span>=<span class="String">"Parameters"</span><span class="ReservedWord">/></span> <span class="ReservedWord"><output</span> <span class="Identifier">message</span>=<span class="String">"tns:AddNumbersOutput"</span> <span class="Identifier">name</span>=<span class="String">"Result"</span><span class="ReservedWord">/></span> <span class="ReservedWord"><fault</span> <span class="Identifier">message</span>=<span class="String">"tns:addNumbersFault"</span> <span class="Identifier">name</span>=<span class="String">"InvalidNumbers"</span> <span class="Identifier">wsa:Action</span>=<span class="String">"http://example.com/addnumbers/fault"</span><span class="ReservedWord">/></span> <span class="ReservedWord"></operation></span> <span class="ReservedWord"></portType></span> ... <span class="ReservedWord"></definitions></span></pre></div></div><br class="example-break"><div class="example"><a name="d0e5997"></a><p class="title"><b>Example 26. <code class="literal">@javax.xml.ws.FaultAction</code> - Example 1 - Specify explicit values for <code class="literal">Action</code> message addressing property if the Java method throws more than one service specific exception.</b></p><div class="example-contents"><pre class="programlisting"><span class="Annotation">@javax.jws.WebService</span> <span class="ReservedWord">public</span> <span class="ReservedWord">class</span> AddNumbersImpl { <span class="Annotation">@javax.xml.ws.Action( fault = {@javax.xml.ws.FaultAction(className = AddNumbersException.class, value = "http://example.com/addFaultAction"), @javax.xml.ws.FaultAction(className = TooBigNumbersException.class, value = "http://example" + ".com/toobigFaultAction")})</span> <span class="ReservedWord">public</span> <span class="ReservedWord">int</span> addNumbers(<span class="ReservedWord">int</span> number1, <span class="ReservedWord">int</span> number2) <span class="ReservedWord">throws</span> AddNumbersException, TooBigNumbersException { <span class="ReservedWord">return</span> number1 + number2; } }</pre><p>The generated WSDL looks like:</p><pre class="programlisting"><span class="ReservedWord"><definitions</span> <span class="Identifier">targetNamespace</span>=<span class="String">"http://example.com/numbers"</span> <span class="Identifier">...></span> <span class="Identifier">...</span> <span class="Identifier"><portType</span> <span class="Identifier">name</span>=<span class="String">"AddNumbersPortType"</span><span class="ReservedWord">></span> <span class="ReservedWord"><operation</span> <span class="Identifier">name</span>=<span class="String">"AddNumbers"</span><span class="ReservedWord">></span> <span class="ReservedWord"><input</span> <span class="Identifier">message</span>=<span class="String">"tns:AddNumbersInput"</span> <span class="Identifier">name</span>=<span class="String">"Parameters"</span><span class="ReservedWord">/></span> <span class="ReservedWord"><output</span> <span class="Identifier">message</span>=<span class="String">"tns:AddNumbersOutput"</span> <span class="Identifier">name</span>=<span class="String">"Result"</span><span class="ReservedWord">/></span> <span class="ReservedWord"><fault</span> <span class="Identifier">message</span>=<span class="String">"tns:addNumbersFault"</span> <span class="Identifier">name</span>=<span class="String">"AddNumbersException"</span> <span class="Identifier">wsa:Action</span>=<span class="String">"http://example.com/addnumbers/fault"</span><span class="ReservedWord">/></span> <span class="ReservedWord"><fault</span> <span class="Identifier">message</span>=<span class="String">"tns:tooBigNumbersFault"</span> <span class="Identifier">name</span>=<span class="String">"TooBigNumbersException"</span> <span class="Identifier">wsa:Action</span>=<span class="String">"http://example.com/toobigFaultAction"</span><span class="ReservedWord">/></span> <span class="ReservedWord"></operation></span> <span class="ReservedWord"></portType></span> ... <span class="ReservedWord"></definitions></span></pre></div></div><br class="example-break"></div></div></div><div class="section" title="10.4. JSR 222 (JAXB) Annotations"><div class="titlepage"><div><div><h3 class="title" id="jsr-222-jaxb-annotations-outline">10.4. JSR 222 (JAXB) Annotations</h3></div></div></div><p>The following JAXB annotations are being documented because JAX-WS generates them when generating wrapper beans and exception beans according to the JAX-WS 2.0 spec. Please refer to sections 3.5.2.1 and 3.6 of the <a class="link" href="http://www.jcp.org/en/jsr/detail?id=224" target="_top">JAX-WS 2.0</a> specification for more information on these beans. For more information on these and other JAXB annotations please refer to the <a class="link" href="http://www.jcp.org/en/jsr/detail?id=222" target="_top">JAXB 2.0 specification</a>.</p><div class="section" title="10.4.1. @javax.xml.bind.annotation.XmlRootElement"><div class="titlepage"><div><div><h4 class="title" id="javax-xml-bind-annotation-xmlrootelement-outline">10.4.1. <code class="literal">@javax.xml.bind.annotation.XmlRootElement</code></h4></div></div></div><p>This annotation is used to map a top level class to a global element in the XML schema used by the WSDL of the web service.</p><div class="table"><a name="d0e6028"></a><p class="title"><b>Table 20. <code class="literal">@javax.xml.bind.annotation.XmlRootElement</code> - Description of Properties</b></p><div class="table-contents"><table summary="@javax.xml.bind.annotation.XmlRootElement
 - Description of Properties" border="1"><colgroup><col width="16%"><col width="54%"><col width="30%"></colgroup><thead><tr><th>Property</th><th>Description</th><th>Default</th></tr></thead><tbody><tr><td><p><code class="literal">name</code></p></td><td><p>Defines the local name of the XML element representing the annotated class</p></td><td><code class="literal">##default</code> – the name is derived from the class</td></tr><tr><td><p><code class="literal">namespace</code></p></td><td><p>Defines the namespace of the XML element representing the annotated class</p></td><td><code class="literal">##default</code> – the namespace is derived from the package of the class</td></tr></tbody></table></div></div><br class="table-break"><div class="section" title="10.4.1.1. Annotation Type Definition"><div class="titlepage"><div><div><h5 class="title" id="section-638165859587004">10.4.1.1. Annotation Type Definition</h5></div></div></div><div class="informalexample"><pre class="programlisting"><span class="Annotation">@Retention(RetentionPolicy.RUNTIME)</span> <span class="Annotation">@Target({ElementType.TYPE})</span> <span class="ReservedWord">public</span> <span class="Annotation">@interface</span> XmlRootElement { <span class="Comment">/** * namespace name of the XML element. * <p/> * If the value is "##default", then the XML namespace name is * derived * from the package of the class ( {@link XmlSchema} ). If the * package is unnamed, then the XML namespace is the default * empty * namespace. */</span> String namespace() <span class="ReservedWord">default</span> <span class="String">"##default"</span>; <span class="Comment">/** * local name of the XML element. * <p/> * If the value is "##default", then the name is derived from * the * class name. */</span> String name() <span class="ReservedWord">default</span> <span class="String">"##default"</span>; }</pre></div></div><div class="section" title="10.4.1.2. Examples"><div class="titlepage"><div><div><h5 class="title" id="section-3077451588388276">10.4.1.2. Examples</h5></div></div></div><div class="example"><a name="d0e6079"></a><p class="title"><b>Example 27. <code class="literal">@javax.xml.bind.annotation.XmlRootElement</code> - Example</b></p><div class="example-contents"><pre class="programlisting"><span class="Annotation">@XmlRootElement(name = "addNumbers", namespace = "http://server.fromjava/")</span> <span class="Annotation">@XmlAccessorType(XmlAccessType.FIELD)</span> <span class="Annotation">@XmlType(name = "addNumbers", namespace = "http://server.fromjava/", propOrder = {"arg0", "arg1"})</span> <span class="ReservedWord">public</span> <span class="ReservedWord">class</span> AddNumbers { <span class="Annotation">@XmlElement(name = "arg0", namespace = "")</span> <span class="ReservedWord">private</span> <span class="ReservedWord">int</span> arg0; <span class="Annotation">@XmlElement(name = "arg1", namespace = "")</span> <span class="ReservedWord">private</span> <span class="ReservedWord">int</span> arg1; <span class="ReservedWord">public</span> <span class="ReservedWord">int</span> getArg0() { <span class="ReservedWord">return</span> <span class="ReservedWord">this</span>.arg0; } <span class="ReservedWord">public</span> <span class="ReservedWord">void</span> setArg0(<span class="ReservedWord">int</span> arg0) { <span class="ReservedWord">this</span>.arg0 = arg0; } <span class="ReservedWord">public</span> <span class="ReservedWord">int</span> getArg1() { <span class="ReservedWord">return</span> <span class="ReservedWord">this</span>.arg1; } <span class="ReservedWord">public</span> <span class="ReservedWord">void</span> setArg1(<span class="ReservedWord">int</span> arg1) { <span class="ReservedWord">this</span>.arg1 = arg1; } }</pre></div></div><br class="example-break"></div></div><div class="section" title="10.4.2. @javax.xml.bind.annotation.XmlAccessorType"><div class="titlepage"><div><div><h4 class="title" id="javax-xml-bind-annotation-xmlaccessortype-outline">10.4.2. <code class="literal">@javax.xml.bind.annotation.XmlAccessorType</code></h4></div></div></div><p>This annotation is used to specify whether fields or properties are serialized by default.</p><div class="table"><a name="d0e6092"></a><p class="title"><b>Table 21. <code class="literal">@javax.xml.bind.annotation.XmlAccessorType</code> - Description of Properties</b></p><div class="table-contents"><table summary="@javax.xml.bind.annotation.XmlAccessorType
 - Description of Properties" border="1"><colgroup><col width="16%"><col width="54%"><col width="30%"></colgroup><thead><tr><th>Property</th><th>Description</th><th>Default</th></tr></thead><tbody><tr><td><p><code class="literal">value</code></p></td><td><p>Specifies whether fields or properties are serialized by default. The value can be <code class="literal">XmlAccessType.FIELD</code> or <code class="literal">XmlAccessType.PROPERTY</code> or <code class="literal">XmlAccessType.PUBLIC_MEMBER</code> or <code class="literal">XmlAccessType.NONE</code></p></td><td><p><code class="literal">XmlAccessType.PROPERTY</code></p></td></tr></tbody></table></div></div><br class="table-break"><div class="section" title="10.4.2.1. Annotation Type Definition"><div class="titlepage"><div><div><h5 class="title" id="section-9211410647210394">10.4.2.1. Annotation Type Definition</h5></div></div></div><div class="informalexample"><pre class="programlisting"><span class="Annotation">@Inherited</span> <span class="Annotation">@Retention(RUNTIME)</span> <span class="Annotation">@Target({PACKAGE, TYPE})</span> <span class="ReservedWord">public</span> <span class="Annotation">@interface</span> XmlAccessorType { <span class="Comment">/** * Specifies whether fields or properties are serialized. * * @see XmlAccessType */</span> XmlAccessType value() <span class="ReservedWord">default</span> XmlAccessType.PUBLIC_MEMBER; }</pre><pre class="programlisting"><span class="Comment">/** * Used by XmlAccessorType to control serialization of fields or * properties. */</span> <span class="ReservedWord">public</span> enum XmlAccessType { <span class="Comment">/** * Every getter/setter pair in a JAXB-bound class will be * automatically * bound to XML, unless annotated by {@link XmlTransient}. * <p/> * Fields are bound to XML only when they are explicitly * annotated * by some of the JAXB annotations. */</span> PROPERTY, <span class="Comment">/** * Every non static, non transient field in a JAXB-bound class * will be automatically * bound to XML, unless annotated by {@link XmlTransient}. * <p/> * Getter/setter pairs are bound to XML only when they are * explicitly annotated * by some of the JAXB annotations. */</span> FIELD, <span class="Comment">/** * Every public getter/setter pair and every public field will * be * automatically bound to XML, unless annotated by {@link * XmlTransient}. * <p/> * Fields or getter/setter pairs that are private, protected, * or * defaulted to package-only access are bound to XML only when * they are * explicitly annotated by the appropriate JAXB annotations. */</span> PUBLIC_MEMBER, <span class="Comment">/** * None of the fields or properties is bound to XML unless they * are specifically annotated with some of the JAXB * annotations. */</span> NONE }</pre></div></div><div class="section" title="10.4.2.2. Examples"><div class="titlepage"><div><div><h5 class="title" id="section-6109125632205346">10.4.2.2. Examples</h5></div></div></div><div class="example"><a name="d0e6144"></a><p class="title"><b>Example 28. <code class="literal">@javax.xml.bind.annotation.XmlAccessorType</code> - Example</b></p><div class="example-contents"><pre class="programlisting"><span class="Annotation">@XmlRootElement(name = "addNumbers", namespace = "http://server.fromjava/")</span> <span class="Annotation">@XmlAccessorType(XmlAccessType.FIELD)</span> <span class="Annotation">@XmlType(name = "addNumbers", namespace = "http://server.fromjava/", propOrder = {"arg0", "arg1"})</span> <span class="ReservedWord">public</span> <span class="ReservedWord">class</span> AddNumbers { <span class="Annotation">@XmlElement(name = "arg0", namespace = "")</span> <span class="ReservedWord">private</span> <span class="ReservedWord">int</span> arg0; <span class="Annotation">@XmlElement(name = "arg1", namespace = "")</span> <span class="ReservedWord">private</span> <span class="ReservedWord">int</span> arg1; <span class="ReservedWord">public</span> <span class="ReservedWord">int</span> getArg0() { <span class="ReservedWord">return</span> <span class="ReservedWord">this</span>.arg0; } <span class="ReservedWord">public</span> <span class="ReservedWord">void</span> setArg0(<span class="ReservedWord">int</span> arg0) { <span class="ReservedWord">this</span>.arg0 = arg0; } <span class="ReservedWord">public</span> <span class="ReservedWord">int</span> getArg1() { <span class="ReservedWord">return</span> <span class="ReservedWord">this</span>.arg1; } <span class="ReservedWord">public</span> <span class="ReservedWord">void</span> setArg1(<span class="ReservedWord">int</span> arg1) { <span class="ReservedWord">this</span>.arg1 = arg1; } }</pre></div></div><br class="example-break"></div></div><div class="section" title="10.4.3. @javax.xml.bind.annotation.XmlType"><div class="titlepage"><div><div><h4 class="title" id="javax-xml-bind-annotation-xmltype-outline">10.4.3. <code class="literal">@javax.xml.bind.annotation.XmlType</code></h4></div></div></div><p>This annotation is used to map a value class to an XML Schema type. A value class is a data container for values represented by properties and fields. A schema type is a data container for values represented by schema components within a schema type's content model (e.g. Model groups, attributes etc).</p><div class="table"><a name="d0e6157"></a><p class="title"><b>Table 22. <code class="literal">@javax.xml.bind.annotation.XmlType</code> - Description of Properties</b></p><div class="table-contents"><table summary="@javax.xml.bind.annotation.XmlType -
 Description of Properties" border="1"><colgroup><col width="16%"><col width="54%"><col width="30%"></colgroup><thead><tr><th>Property</th><th>Description</th><th>Default</th></tr></thead><tbody><tr><td><p><code class="literal">name</code></p></td><td><p>Defines the local name of the XML type representing this class in the XML schema used by the WSDL of the web service</p></td><td>"<code class="literal">##default</code>"</td></tr><tr><td><p><code class="literal">namespace</code></p></td><td><p>Defines the namespace of the XML type representing this class in the XML schema used by the WSDL of the web service</p></td><td>"<code class="literal">##default</code>"</td></tr><tr><td><p><code class="literal">propOrder</code></p></td><td><p>Defines a list of names of JavaBean properties in the class. Each name in the list is the name of a Java identifier of the JavaBean property. The order in which JavaBean properties are listed is the order of XML Schema elements to which the JavaBean properties are mapped.</p><p>All of the JavaBean properties being mapped must be listed (i.e. if a JavaBean property mapping is prevented by <code class="literal">@XmlTransient</code> then it does not have to be listed). Otherwise, it is an error. By default, the JavaBean properties are ordered using a default order specified in the <a class="link" href="http://www.jcp.org/en/jsr/detail?id=222" target="_top">JAXB 2.0 specification</a>.</p></td><td><p>{""}</p></td></tr></tbody></table></div></div><br class="table-break"><div class="section" title="10.4.3.1. Annotation Type Definition"><div class="titlepage"><div><div><h5 class="title" id="section-7314416209576604">10.4.3.1. Annotation Type Definition</h5></div></div></div><div class="informalexample"><pre class="programlisting"><span class="Annotation">@Retention(RetentionPolicy.RUNTIME)</span> <span class="Annotation">@Target({ElementType.TYPE})</span> <span class="ReservedWord">public</span> <span class="Annotation">@interface</span> XmlType { <span class="Comment">/** * Name of the XML Schema type which the class is mapped. */</span> String name() <span class="ReservedWord">default</span> <span class="String">"##default"</span>; <span class="Comment">/** * Specifies the order for XML Schema elements when class is * mapped to a XML Schema complex type. * <p/> * <p> Refer to the table for how the propOrder affects the * mapping of class </p> * <p/> * <p> The propOrder is a list of names of JavaBean properties in * the class. Each name in the list is the name of a Java * identifier of the JavaBean property. The order in which * JavaBean properties are listed is the order of XML Schema * elements to which the JavaBean properties are mapped. </p> * <p> All of the JavaBean properties being mapped to XML Schema * elements * must be listed. * <p> A JavaBean property or field listed in propOrder must not * be transient or annotated with <tt>@XmlTransient</tt>. * <p> The default ordering of JavaBean properties is determined * by @{@link XmlAccessorOrder}. */</span> String[] propOrder() <span class="ReservedWord">default</span> {<span class="String">""</span>}; <span class="Comment">/** * Name of the target namespace of the XML Schema type. By * default, this is the target namespace to which the package * containing the class is mapped. */</span> String namespace() <span class="ReservedWord">default</span> <span class="String">"##default"</span>; <span class="Comment">/** * Class containing a no-arg factory method for creating an * instance of this class. The default is this class. * <p/> * <p>If <tt>factoryClass</tt> is DEFAULT.class and * <tt>factoryMethod</tt> is "", then there is no static factory * method. * <p/> * <p>If <tt>factoryClass</tt> is DEFAULT.class and * <tt>factoryMethod</tt> is not "", then * <tt>factoryMethod</tt> is the name of a static factory method * in this class. * <p/> * <p>If <tt>factoryClass</tt> is not DEFAULT.class, then * <tt>factoryMethod</tt> must not be "" and must be the name of * a static factory method specified in <tt>factoryClass</tt>. */</span> Class factoryClass() <span class="ReservedWord">default</span> DEFAULT.<span class="ReservedWord">class</span>; <span class="Comment">/** * Used in {@link XmlType#factoryClass()} to * signal that either factory mehod is not used or * that it's in the class with this {@link XmlType} itself. */</span> <span class="ReservedWord">static</span> <span class="ReservedWord">final</span> <span class="ReservedWord">class</span> DEFAULT { } <span class="Comment">/** * Name of a no-arg factory method in the class specified in * <tt>factoryClass</tt> factoryClass(). */</span> String factoryMethod() <span class="ReservedWord">default</span> <span class="String">""</span>; }</pre></div></div><div class="section" title="10.4.3.2. Examples"><div class="titlepage"><div><div><h5 class="title" id="section-3949542543211304">10.4.3.2. Examples</h5></div></div></div><div class="example"><a name="d0e6229"></a><p class="title"><b>Example 29. <code class="literal">@javax.xml.bind.annotation.XmlType</code> - Example</b></p><div class="example-contents"><pre class="programlisting"><span class="Annotation">@XmlRootElement(name = "addNumbers", namespace = "http://server.fromjava/")</span> <span class="Annotation">@XmlAccessorType(XmlAccessType.FIELD)</span> <span class="Annotation">@XmlType(name = "addNumbers", namespace = "http://server.fromjava/", propOrder = {"arg0", "arg1"})</span> <span class="ReservedWord">public</span> <span class="ReservedWord">class</span> AddNumbers { <span class="Annotation">@XmlElement(name = "arg0", namespace = "")</span> <span class="ReservedWord">private</span> <span class="ReservedWord">int</span> arg0; <span class="Annotation">@XmlElement(name = "arg1", namespace = "")</span> <span class="ReservedWord">private</span> <span class="ReservedWord">int</span> arg1; <span class="ReservedWord">public</span> <span class="ReservedWord">int</span> getArg0() { <span class="ReservedWord">return</span> <span class="ReservedWord">this</span>.arg0; } <span class="ReservedWord">public</span> <span class="ReservedWord">void</span> setArg0(<span class="ReservedWord">int</span> arg0) { <span class="ReservedWord">this</span>.arg0 = arg0; } <span class="ReservedWord">public</span> <span class="ReservedWord">int</span> getArg1() { <span class="ReservedWord">return</span> <span class="ReservedWord">this</span>.arg1; } <span class="ReservedWord">public</span> <span class="ReservedWord">void</span> setArg1(<span class="ReservedWord">int</span> arg1) { <span class="ReservedWord">this</span>.arg1 = arg1; } }</pre></div></div><br class="example-break"></div></div><div class="section" title="10.4.4. @javax.xml.bind.annotation.XmlElement"><div class="titlepage"><div><div><h4 class="title" id="section-147120285802621">10.4.4. <code class="literal">@javax.xml.bind.annotation.XmlElement</code></h4></div></div></div><p>This annotation is used to map a property contained in a class to a local element in the XML Schema complex type to which the containing class is mapped.</p><div class="table"><a name="d0e6242"></a><p class="title"><b>Table 23. <code class="literal">@javax.xml.bind.annotation.XmlElement</code> - Description of Properties</b></p><div class="table-contents"><table summary="@javax.xml.bind.annotation.XmlElement
 - Description of Properties" border="1"><colgroup><col width="16%"><col width="54%"><col width="30%"></colgroup><thead><tr><th>Property</th><th>Description</th><th>Default</th></tr></thead><tbody><tr><td><p><code class="literal">name</code></p></td><td><p>Defines the local name of the XML element representing the property of a JavaBean</p></td><td><p>"<code class="literal">##default</code>" - the element name is derived from the JavaBean property name.</p></td></tr><tr><td><p><code class="literal">namespace</code></p></td><td><p>Defines the namespace of the XML element representing the property of a JavaBean</p></td><td><p>"<code class="literal">##default</code>" - the namespace of the containing class</p></td></tr><tr><td><p><code class="literal">nillable</code></p></td><td><p>Not generated by JAX-WS</p></td><td><p></p></td></tr><tr><td><p><code class="literal">type</code></p></td><td><p>Not generated by JAX-WS</p></td><td><p></p></td></tr></tbody></table></div></div><br class="table-break"><div class="section" title="10.4.4.1. Annotation Type Definition"><div class="titlepage"><div><div><h5 class="title" id="section-585474581494925">10.4.4.1. Annotation Type Definition</h5></div></div></div><div class="informalexample"><pre class="programlisting"><span class="Annotation">@Retention(RetentionPolicy.RUNTIME)</span> <span class="Annotation">@Target({ElementType.FIELD, ElementType.METHOD, ElementType.PARAMETER})</span> <span class="ReservedWord">public</span> <span class="Annotation">@interface</span> XmlElement { <span class="Comment">/** * Name of the XML Schema element. * <p> If the value is "##default", then element name is derived from * the * JavaBean property name. */</span> String name() <span class="ReservedWord">default</span> <span class="String">"##default"</span>; <span class="Comment">/** * Customize the element declaration to be nillable. * <p>If nillable() is true, then the JavaBean property is * mapped to a XML Schema nillable element declaration. */</span> <span class="ReservedWord">boolean</span> nillable() <span class="ReservedWord">default</span> false; <span class="Comment">/** * Customize the element declaration to be required. * <p>If required() is true, then Javabean property is mapped to * an XML schema element declaration with minOccurs="1". * maxOccurs is "1" for a single valued property and "unbounded" * for a multivalued property. * <p>If required() is false, then the Javabean property is mapped * to XML Schema element declaration with minOccurs="0". * maxOccurs is "1" for a single valued property and "unbounded" * for a multivalued property. */</span> <span class="ReservedWord">boolean</span> required() <span class="ReservedWord">default</span> false; <span class="Comment">/** * XML target namespace of the XML Schema element. * <p/> * If the value is "##default", then the namespace is determined * as follows: * <ol> * <li> * If the enclosing package has {@link XmlSchema} annotation, * and its {@link XmlSchema#elementFormDefault() elementFormDefault} * is {@link XmlNsForm#QUALIFIED QUALIFIED}, then the namespace of * the enclosing class. * <p/> * <li> * Otherwise &#39;&#39; (which produces unqualified element in the * default * namespace. * </ol> */</span> String namespace() <span class="ReservedWord">default</span> <span class="String">"##default"</span>; <span class="Comment">/** * Default value of this element. * <p/> * <p/> * The <pre>'\u0000'</pre> value specified as a default of this * annotation element * is used as a poor-man's substitute for null to allow implementations * to recognize the 'no default value' state. */</span> String defaultValue() <span class="ReservedWord">default</span> <span class="String">"\u0000"</span>; <span class="Comment">/** * The Java class being referenced. */</span> Class type() <span class="ReservedWord">default</span> DEFAULT.<span class="ReservedWord">class</span>; <span class="Comment">/** * Used in {@link XmlElement#type()} to * signal that the type be inferred from the signature * of the property. */</span> <span class="ReservedWord">static</span> <span class="ReservedWord">final</span> <span class="ReservedWord">class</span> DEFAULT { } }</pre></div></div><div class="section" title="10.4.4.2. Examples"><div class="titlepage"><div><div><h5 class="title" id="section-3035378616552507">10.4.4.2. Examples</h5></div></div></div><div class="example"><a name="d0e6317"></a><p class="title"><b>Example 30. <code class="literal">@javax.xml.bind.annotation.XmlElement</code> - Example</b></p><div class="example-contents"><pre class="programlisting"><span class="Annotation">@XmlRootElement(name = "addNumbers", namespace = "http://server.fromjava/")</span> <span class="Annotation">@XmlAccessorType(XmlAccessType.FIELD)</span> <span class="Annotation">@XmlType(name = "addNumbers", namespace = "http://server.fromjava/", propOrder = {"arg0", "arg1"})</span> <span class="ReservedWord">public</span> <span class="ReservedWord">class</span> AddNumbers { <span class="Annotation">@XmlElement(name = "arg0", namespace = "")</span> <span class="ReservedWord">private</span> <span class="ReservedWord">int</span> arg0; <span class="Annotation">@XmlElement(name = "arg1", namespace = "")</span> <span class="ReservedWord">private</span> <span class="ReservedWord">int</span> arg1; <span class="ReservedWord">public</span> <span class="ReservedWord">int</span> getArg0() { <span class="ReservedWord">return</span> <span class="ReservedWord">this</span>.arg0; } <span class="ReservedWord">public</span> <span class="ReservedWord">void</span> setArg0(<span class="ReservedWord">int</span> arg0) { <span class="ReservedWord">this</span>.arg0 = arg0; } <span class="ReservedWord">public</span> <span class="ReservedWord">int</span> getArg1() { <span class="ReservedWord">return</span> <span class="ReservedWord">this</span>.arg1; } <span class="ReservedWord">public</span> <span class="ReservedWord">void</span> setArg1(<span class="ReservedWord">int</span> arg1) { <span class="ReservedWord">this</span>.arg1 = arg1; } }</pre></div></div><br class="example-break"></div></div><div class="section" title="10.4.5. @javax.xml.bind.annotation.XmlSeeAlso"><div class="titlepage"><div><div><h4 class="title" id="javax-xml-bind-annotation-xmlseealso">10.4.5. <code class="literal">@javax.xml.bind.annotation.XmlSeeAlso</code></h4></div></div></div><p>Instructs JAXB to also bind other classes when binding this class.</p><div class="table"><a name="d0e6330"></a><p class="title"><b>Table 24. <code class="literal">@javax.xml.bind.annotation.XmlSeeAlso</code> - Description of Properties</b></p><div class="table-contents"><table summary="@javax.xml.bind.annotation.XmlSeeAlso
 - Description of Properties" border="1"><colgroup><col width="16%"><col width="54%"><col width="30%"></colgroup><thead><tr><th>Property</th><th>Description</th><th>Default</th></tr></thead><tbody><tr><td><p><code class="literal">value</code></p></td><td><p>Other classes that JAXB can use when binding this class</p></td><td><p>{}</p></td></tr></tbody></table></div></div><br class="table-break"><div class="section" title="10.4.5.1. Annotation Type Definition"><div class="titlepage"><div><div><h5 class="title" id="section-4562047312606827">10.4.5.1. Annotation Type Definition</h5></div></div></div><div class="informalexample"><pre class="programlisting"><span class="Comment">/** * Instructs JAXB to also bind other classes when binding this class. * <p/> * Java makes it impractical/impossible to list all sub-classes of * a given class. This often gets in a way of JAXB users, as it JAXB * cannot automatically list up the classes that need to be known * to {@link JAXBContext}. * <p/> * For example, with the following class definitions: * <p/> * <pre> * class Animal {} * class Dog extends Animal {} * class Cat extends Animal {} * </pre> * <p/> * The user would be required to create {@link JAXBContext} as * <tt>JAXBContext.newInstance(Dog.class,Cat.class)</tt> * (<tt>Animal</tt> will be automatically picked up since <tt>Dog</tt> * and <tt>Cat</tt> refers to it.) * <p/> * {@link XmlSeeAlso} annotation would allow you to write: * <pre> * &#64;XmlSeeAlso({Dog.class,Cat.class}) * class Animal {} * class Dog extends Animal {} * class Cat extends Animal {} * </pre> * <p/> * This would allow you to do <tt>JAXBContext.newInstance(Animal.class) * </tt>. * By the help of this annotation, JAXB implementations will be able to * correctly bind <tt>Dog</tt> and <tt>Cat</tt>. * * @author Kohsuke Kawaguchi * @since JAXB2.1 */</span> <span class="Annotation">@Target({ElementType.TYPE})</span> <span class="Annotation">@Retention(RUNTIME)</span> <span class="ReservedWord">public</span> <span class="Annotation">@interface</span> XmlSeeAlso { Class[] value(); }</pre></div></div></div></div><div class="section" title="10.5. JSR 250 (Common Annotations) Annotations"><div class="titlepage"><div><div><h3 class="title" id="jsr-250-common-annotations">10.5. JSR 250 (Common Annotations) Annotations</h3></div></div></div><p>The following annotations are being documented because JAX-WS endpoints use them for resource injection, and as lifecycle methods. Please refer to sections 5.2.1 and 5.3 of the <a class="link" href="http://www.jcp.org/en/jsr/detail?id=224" target="_top">JAX-WS 2.0</a> specification for resource injection, and lifecycle management. For more information on these and other common annotations please refer to the <a class="link" href="http://www.jcp.org/en/jsr/detail?id=250" target="_top">JSR 250: <span class="emphasis"><em>Common Annotations for the Java TM Platform</em></span> </a>.</p><div class="section" title="10.5.1. @javax.annotation.Resource"><div class="titlepage"><div><div><h4 class="title" id="javax-xml-bind-annotation-xmlrootelement-outline1">10.5.1. <code class="literal">@javax.annotation.Resource</code></h4></div></div></div><p>This annotation is used to mark a WebServiceContext resource that is needed by a web service. It is applied to a field or a method for JAX-WS endpoints. The container will inject an instance of the WebServiceContext resource into the endpoint implementation when it is initialized.</p><div class="table"><a name="d0e6385"></a><p class="title"><b>Table 25. <code class="literal">@javax.annotation.Resource</code> - Description of Properties</b></p><div class="table-contents"><table summary="@javax.annotation.Resource -
 Description of Properties" border="1"><colgroup><col width="16%"><col width="54%"><col width="30%"></colgroup><thead><tr><th>Property</th><th>Description</th><th>Default</th></tr></thead><tbody><tr><td><p><code class="literal">type</code></p></td><td><p>Java type of the resource</p></td><td><p>For field annotations, the default is the type of the field. For method annotations, the default is the type of the JavaBeans property.</p></td></tr></tbody></table></div></div><br class="table-break"><div class="section" title="10.5.1.1. Annotation Type Definition"><div class="titlepage"><div><div><h5 class="title" id="section-26090909275792">10.5.1.1. Annotation Type Definition</h5></div></div></div><div class="informalexample"><pre class="programlisting"><span class="Annotation">@Target({ElementType.TYPE, ElementType.FIELD, ElementType.METHOD})</span> <span class="Annotation">@Retention(RetentionPolicy.RUNTIME)</span> <span class="ReservedWord">public</span> <span class="Annotation">@interface</span> Resource { <span class="Comment">// ...</span> <span class="Comment">/** * The Java type of the resource. For field annotations, * the default is the type of the field. For method annotations, * the default is the type of the JavaBeans property. * For class annotations, there is no default and this must be * specified. */</span> Class type() <span class="ReservedWord">default</span> java.lang.Object.<span class="ReservedWord">class</span>; }</pre></div></div><div class="section" title="10.5.1.2. Examples"><div class="titlepage"><div><div><h5 class="title" id="section-3989686945211064">10.5.1.2. Examples</h5></div></div></div><div class="example"><a name="d0e6423"></a><p class="title"><b>Example 31. <code class="literal">@javax.annotation.Resource</code> - Example</b></p><div class="example-contents"><pre class="programlisting"><span class="Annotation">@WebService</span> <span class="ReservedWord">public</span> <span class="ReservedWord">class</span> HelloImpl { <span class="Annotation">@Resource</span> <span class="ReservedWord">private</span> WebServiceContext context; <span class="ReservedWord">public</span> String echoHello(String name) { <span class="Comment">// ...</span> } }</pre></div></div><br class="example-break"></div></div><div class="section" title="10.5.2. @javax.annotation.PostConstruct"><div class="titlepage"><div><div><h4 class="title" id="javax-annotation-postconstruct">10.5.2. <code class="literal">@javax.annotation.PostConstruct</code></h4></div></div></div><p>This annotation is used on a method that needs to be executed after dependency injection is done to perform any initialization. This method MUST be invoked before the class is put into service.</p><div class="section" title="10.5.2.1. Annotation Type Definition"><div class="titlepage"><div><div><h5 class="title" id="section-944222438955486">10.5.2.1. Annotation Type Definition</h5></div></div></div><div class="informalexample"><pre class="programlisting"><span class="Comment">/** * The PostConstruct annotation is used on a method that needs to be * executed * after dependency injection is done to perform any initialization. This * method MUST be invoked before the class is put into service. This * annotation MUST be supported on all classes that support dependency * injection. The method annotated with PostConstruct MUST be invoked even * if the class does not request any resources to be injected. Only one * method can be annotated with this annotation. The method on which the * PostConstruct annotation is applied MUST fulfill all of the following * criteria - * - The method MUST NOT have any parameters except in the case of EJB * interceptors in which case it takes an InvocationC ontext object as * defined by the EJB specification. * - The return type of the method MUST be void. * - The method MUST NOT throw a checked exception. * - The method on which PostConstruct is applied MAY be public, protected, * package private or private. * - The method MUST NOT be static except for the application client. * - The method MAY be final. * - If the method throws an unchecked exception the class MUST NOT be * put into * service except in the case of EJBs where the EJB can handle exceptions * and * even recover from them. * * @see javax.annotation.PreDestroy * @see javax.annotation.Resource * @since Common Annotations 1.0 */</span> <span class="Annotation">@Documented</span> <span class="Annotation">@Retention(RetentionPolicy.RUNTIME)</span> <span class="Annotation">@Target(ElementType.METHOD)</span> <span class="ReservedWord">public</span> <span class="Annotation">@interface</span> PostConstruct { }</pre></div></div><div class="section" title="10.5.2.2. Examples"><div class="titlepage"><div><div><h5 class="title" id="section-76012616986007">10.5.2.2. Examples</h5></div></div></div><div class="example"><a name="d0e6445"></a><p class="title"><b>Example 32. <code class="literal">@javax.annotation.PostConstruct</code> - Example</b></p><div class="example-contents"><pre class="programlisting"><span class="Annotation">@WebService</span> <span class="ReservedWord">public</span> <span class="ReservedWord">class</span> HelloImpl { <span class="Annotation">@PostConstruct</span> <span class="ReservedWord">private</span> <span class="ReservedWord">void</span> init() { <span class="Comment">// ...</span> } <span class="ReservedWord">public</span> String echoHello(String name) { <span class="Comment">// ...</span> } }</pre></div></div><br class="example-break"></div></div><div class="section" title="10.5.3. @javax.annotation.PreDestroy"><div class="titlepage"><div><div><h4 class="title" id="section-930833968571058">10.5.3. <code class="literal">@javax.annotation.PreDestroy</code></h4></div></div></div><p>The PreDestroy annotation is used on methods as a callback notification to signal that the instance is in the process of being removed by the container. The method annotated with PreDestroy is typically used to release resources that it has been holding.</p><div class="section" title="10.5.3.1. Annotation Type Definition"><div class="titlepage"><div><div><h5 class="title" id="section-916789883737631">10.5.3.1. Annotation Type Definition</h5></div></div></div><div class="informalexample"><pre class="programlisting"><span class="Comment">/** * The PreDestroy annotation is used on methods as a callback * notification to * signal that the instance is in the process of being removed by the * container. The method annotated with PreDestroy is typically used to * release resources that it has been holding. This annotation MUST be * supported by all container managed objects that support PostConstruct * except the application client container in Java EE 5. The method on * which * the PreDestroy annotation is applied MUST fulfill all of the following * criteria - * - The method MUST NOT have any parameters except in the case of EJB * interceptors in which case it takes an InvocationContext object as * defined * by the EJB specification. * - The return type of the method MUST be void. * - The method MUST NOT throw a checked exception. * - The method on which PreDestroy is applied MAY be public, protected, * package private or private. * - The method MUST NOT be static. * - The method MAY be final. * - If the method throws an unchecked exception it is ignored except in * the * case of EJBs where the EJB can handle exceptions. * * @see javax.annotation.PostConstruct * @see javax.annotation.Resource * @since Common Annotations 1.0 */</span> <span class="Annotation">@Documented</span> <span class="Annotation">@Retention(RetentionPolicy.RUNTIME)</span> <span class="Annotation">@Target(ElementType.METHOD)</span> <span class="ReservedWord">public</span> <span class="Annotation">@interface</span> PreDestroy { }</pre></div></div><div class="section" title="10.5.3.2. Examples"><div class="titlepage"><div><div><h5 class="title" id="section-9258638457952977">10.5.3.2. Examples</h5></div></div></div><div class="example"><a name="d0e6468"></a><p class="title"><b>Example 33. <code class="literal">@javax.annotation.PreDestroy</code> - Example</b></p><div class="example-contents"><pre class="programlisting"><span class="Annotation">@WebService</span> <span class="ReservedWord">public</span> <span class="ReservedWord">class</span> HelloImpl { <span class="ReservedWord">public</span> String echoHello(String name) { <span class="Comment">// ...</span> } <span class="Annotation">@PreDestroy</span> <span class="ReservedWord">private</span> <span class="ReservedWord">void</span> release() { <span class="Comment">// ...</span> } }</pre></div></div><br class="example-break"></div></div></div></div><div lang="en" class="section" title="11. Why WS-Addressing?"><div class="titlepage"><div><div><h2 class="title" style="clear: both" id="users-guide-why-ws-addressing">11. Why WS-Addressing?</h2></div></div></div><div class="section" title="11.1. What is WS-Addressing?"><div class="titlepage"><div><div><h3 class="title" id="what-is-ws-addressing">11.1. What is WS-Addressing?</h3></div></div></div><p><a class="link" href="http://www.w3.org/2002/ws/addr/" target="_top">Web Services Addressing</a> provides transport-neutral mechanisms to address Web services and messages. The transport-neutrality is achieved by normalizing the information typically shared between transport protocols and messaging systems. To serve this purpose, WS-Addressing defines two new constructs, <span class="bold"><strong>Message Addressing Properties</strong></span> (MAPs) and <span class="bold"><strong>Endpoint Reference</strong></span> (EPR), that normalize the information independent of any particular transport or messaging system. MAPs convey end-to-end message characteristics including addressing for source and destination endpoints as well as message identity that allows uniform addressing of messages independent of the underlying transport. EPR convey the information needed to address a Web service endpoint.</p><p>The subsequent sections explain the different use cases served by WS-Addressing.</p><div class="section" title="11.1.1. Transport Neutrality"><div class="titlepage"><div><div><h4 class="title" id="transport-neutrality">11.1.1. Transport Neutrality</h4></div></div></div><p>This section describes how a message can be sent to a Web service endpoint in transport neutral manner.</p><div class="example"><a name="d0e6499"></a><p class="title"><b>Example 34. SOAP 1.2 message, without WS-Addressing, sent over HTTP</b></p><div class="example-contents"><div class="programlistingco"><pre class="programlisting">POST /fabrikam/Purchasing HTTP 1.1/POST <span class="co" id=""><img src="icons/callouts/1.png" alt="(1)"></span> Host: example.com SOAPAction: http://example.com/fabrikam/SubmitPO <span class="ReservedWord"><S:Envelope</span> <span class="co" id=""><img src="icons/callouts/2.png" alt="(2)"></span> <span class="Identifier">xmlns:S</span>=<span class="String">"http://www.w3.org/2003/05/soap-envelope"</span> <span class="Identifier">xmlns:wombat</span>=<span class="String">"http://wombat.org/"</span><span class="ReservedWord">></span> <span class="ReservedWord"><S:Header></span> <span class="ReservedWord"><wombat:MessageID></span> uuid:e197db59-0982-4c9c-9702-4234d204f7f4 <span class="ReservedWord"></wombat:MessageID></span> <span class="ReservedWord"></S:Header></span> <span class="ReservedWord"><S:Body></span> ... <span class="ReservedWord"></S:Body></span> <span class="ReservedWord"></S:Envelope></span></pre><div class="calloutlist"><table border="0" summary="Callout list"><tr><td width="5%" valign="top" align="left"><p><img src="icons/callouts/1.png" alt="1" border="0"></p></td><td valign="top" align="left"><p>HTTP transport headers.</p></td></tr><tr><td width="5%" valign="top" align="left"><p><img src="icons/callouts/2.png" alt="2" border="0"></p></td><td valign="top" align="left"><p>SOAP message in HTTP body.</p></td></tr></table></div></div><p>The host (<code class="literal">example.com</code>), the dispatch method (<code class="literal">POST</code>) and the URL to dispatch to (<code class="literal">/fabrikam/Purchasing</code>) are in the HTTP transport headers. The actual message and implied meaning (for example payload's <code class="literal">QName</code> or <code class="literal">SOAPAction</code>) is defined by the messaging system (<code class="literal">SOAP</code>) or transport protocol (<code class="literal">HTTP</code>). If the message is to be sent over an alternate transport, such as SMTP, then the information conveyed in HTTP transport headers need to be mapped to SMTP specific headers. On the server side, to dispatch successfully, a Web service stack has to gather the information from the SMTP (as opposed to HTTP) headers and the SOAP message.</p></div></div><br class="example-break"><p>Also in the above message, there is no standard header to establish the identity of a message. In this case, <code class="literal">MessageID</code> header defined in the namespace URI bound to <code class="literal">wombat</code> prefix is used but is application specific and is thus not re-usable.</p><p>WS-Addressing introduce Message Addressing Properties that collectively augment a message to normalize this information.</p><div class="example"><a name="d0e6550"></a><p class="title"><b>Example 35. SOAP 1.2 message, with WS-Addressing, sent over HTTP</b></p><div class="example-contents"><div class="programlistingco"><pre class="programlisting">POST /fabrikam/Purchasing HTTP 1.1/POST <span class="co" id=""><img src="icons/callouts/1.png" alt="(1)"></span> Host: example.com SOAPAction: http://example.com/fabrikam/SubmitPO <span class="ReservedWord"><S:Envelope</span> <span class="co" id=""><img src="icons/callouts/2.png" alt="(2)"></span> <span class="Identifier">xmlns:S</span>=<span class="String">"http://www.w3.org/2003/05/soap-envelope"</span> <span class="bold"><strong>xmlns:wsa="http://www.w3.org/2005/08/addressing/"</strong></span>> <span class="ReservedWord"><S:Header></span> <span class="bold"><strong><wsa:MessageID></strong></span> <span class="co" id=""><img src="icons/callouts/3.png" alt="(3)"></span><span class="bold"><strong> uuid:e197db59-0982-4c9c-9702-4234d204f7f4 </wsa:MessageID> <wsa:To> http://example.com/fabrikam/Purchasing </wsa:To> <wsa:Action> http://example.com/fabrikam/SubmitPO </wsa:Action></strong></span> <span class="ReservedWord"></S:Header></span> <span class="ReservedWord"><S:Body></span> ... <span class="ReservedWord"></S:Body></span> <span class="ReservedWord"></S:Envelope></span></pre><div class="calloutlist"><table border="0" summary="Callout list"><tr><td width="5%" valign="top" align="left"><p><img src="icons/callouts/1.png" alt="1" border="0"></p></td><td valign="top" align="left"><p>HTTP transport headers.</p></td></tr><tr><td width="5%" valign="top" align="left"><p><img src="icons/callouts/2.png" alt="2" border="0"></p></td><td valign="top" align="left"><p>SOAP message in HTTP body.</p></td></tr><tr><td width="5%" valign="top" align="left"><p><img src="icons/callouts/3.png" alt="3" border="0"></p></td><td valign="top" align="left"><p>Binding of Message Addressing Properties to SOAP 1.2 message.</p></td></tr></table></div></div><p>For example, <code class="literal">wsa:MessageID</code> is a binding of an abstract property that defines an absolute URI that uniquely identifies the message, <code class="literal">wsa:To</code> is binding of an abstract absolute URI representing the address of the intended receiver of this message and <code class="literal">wsa:Action</code> is binding of an abstract absolute IRI that uniquely identifies the semantics implied by this message. All the information earlier shared between transport protocols and messaging systems is now normalized into a uniform format that can be processed independent of transport or application.</p><p>If the exactly same message is to be sent/received using a different transport, for example asynchronously over SMTP, then the value of <code class="literal">wsa:To</code> header could be changed to <code class="literal">mailto:purchasing@example.com</code>. The updated <code class="literal">wsa:To</code> header looks like:</p><pre class="programlisting"><span class="ReservedWord"><wsa:To></span> <span class="bold"><strong>mailto:purchasing@example.com</strong></span> <span class="ReservedWord"></wsa:To></span></pre><p>On the server side, Web services stack can gather all the information from the SOAP message and then dispatch it correctly.</p></div></div><br class="example-break"></div><div class="section" title="11.1.2. Stateful Web service"><div class="titlepage"><div><div><h4 class="title" id="stateful-web-service">11.1.2. Stateful Web service</h4></div></div></div><p>Web services are usually stateless, i.e. the service endpoint receives a request and responds back without saving any processing state in between different requests. However making Web services stateful enables to share multiple instances of service endpoints. For example, consider a stateful Bank Web service. The client (say bank customer) can obtain a bank EPR, with relevant state information stored as reference parameters, and invoke a method on that EPR to do a series of banking operations. On the service endpoint, whenever a request is received, the reference parameters from the EPR are available as first-class SOAP headers allowing the endpoint to restore the state.</p><p>JAX-WS RI 2.2.7 enables <a class="link" href="http://jax-ws.java.net/nonav/jax-ws-21-ea2/docs/users-guide-stateful-webservice" target="_top">stateful Web services</a> to be annotated with <code class="literal">com.sun.xml.ws.developer.Stateful</code> annotation.</p></div><div class="section" title="11.1.3. Simple and Complex MEPs"><div class="titlepage"><div><div><h4 class="title" id="simple-and-complex-meps">11.1.3. Simple and Complex MEPs</h4></div></div></div><p>WS-Addressing defines standard <a class="link" href="http://www.w3.org/TR/2006/REC-ws-addr-core-20060509/#abstractmaps" target="_top">Message Addressing Properties</a> (MAPs) to support simple and complex message patterns. The SOAP Binding defines a mapping of these MAPs to SOAP headers and convey end-to-end message characteristics including addressing for source and destination endpoints as well as message identity. For example <code class="literal">destination</code> MAP represents an absolute IRI representing the address of the intended receiver of the message and is mapped to a SOAP header with <code class="literal">wsa:To</code> element name. <code class="literal">reply endpoint</code> represents an endpoint reference for the intended receiver for replies to this message and is mapped to a SOAP header with <code class="literal">wsa:ReplyTo</code> element name. In addition, WSDL Binding, also defines requirement on the presence of these MAPs for standard Message Exchange Patterns (MEPs) such as <a class="link" href="http://www.w3.org/TR/wsdl#_request-response" target="_top">request/response</a> and <a class="link" href="http://www.w3.org/TR/wsdl#_one-way" target="_top">one-way</a>.</p><p>Using these MAPs, complex MEPs can be created. For example:</p><div class="orderedlist"><ol class="orderedlist" type="1"><li class="listitem"><p><span class="bold"><strong>Asynchronous MEP</strong></span>: Using <code class="literal">reply endpoint</code> MAP, an asynchronous transport may be specified for a synchronous request. For example, a client application might send a request over HTTP and ask to receive the response through SMTP.</p></li><li class="listitem"><p><span class="bold"><strong>Conversation MEP</strong></span>: Using <code class="literal">relationship</code> MAP, that defines the relationship between two messages, a conversational MEP can be defined by correlating multiple request/response MEPs. For example a client sending a request to service endpoint receives a response with <code class="literal">wsa:RelatesTo</code> MAP. The service endpoint may optionally include <code class="literal">wsa:MessageID</code> in the response. This MAP can then be included by the client in <code class="literal">wsa:RelatesTo</code> MAP in next request to the service endpoint there by starting a conversation.</p></li><li class="listitem"><p><span class="bold"><strong>Distributed MEP</strong></span>: Using <code class="literal">reply endpoint</code> and <code class="literal">fault endpoint</code> MAP, a different transport/address can be specified for receiving normal and fault responses respectively.</p></li></ol></div></div><div class="section" title="11.1.4. Composability with other WS-* specifications"><div class="titlepage"><div><div><h4 class="title" id="composability-with-other-ws-specifications">11.1.4. Composability with other WS-* specifications</h4></div></div></div><p>There are several Web services specification (commonly known as <a class="link" href="http://en.wikipedia.org/wiki/WS-*" target="_top">WS-* specs</a>) that make use of the abstract properties defined by WS-Addressing. For example <a class="link" href="http://en.wikipedia.org/wiki/WS-MetadataExchange" target="_top">WS-Metadata Exchange</a> define a bootstrap mechanism for retrieving metadata before the business message exchange can take place. This mechanism involve sending a <a class="link" href="http://www.w3.org/Submission/WS-Transfer/" target="_top">WS-Transfer</a> request for the retrieval of a resource's representation. A typical request message looks like:</p><div class="programlistingco"><pre class="programlisting"><span class="ReservedWord"><s11:Envelope</span> <span class="co" id=""><img src="icons/callouts/1.png" alt="(1)"></span> <span class="Identifier">xmlns:s11</span>=<span class="String">"http://schemas.xmlsoap.org/soap/envelope/"</span> <span class="bold"><strong>xmlns:wsa="http://www.w3.org/2005/08/addressing"</strong></span>> <span class="co" id=""><img src="icons/callouts/2.png" alt="(2)"></span> <span class="ReservedWord"><s11:Header></span> <span class="ReservedWord"><wsa:Action></span> <span class="co" id=""><img src="icons/callouts/3.png" alt="(3)"></span> <span class="bold"><strong>http://schemas.xmlsoap.org/ws/2004/09/transfer/Get</strong></span> <span class="ReservedWord"></wsa:Action></span> <span class="ReservedWord"><wsa:To></span>http://example.org/metadata<span class="ReservedWord"></wsa10:To></span> <span class="ReservedWord"><wsa:ReplyTo></span> <span class="ReservedWord"><wsa:Address></span>http://www.w3.org/2005/08/addressing/anonymous <span class="ReservedWord"></wsa10:Address></span> <span class="ReservedWord"></wsa:ReplyTo></span> <span class="ReservedWord"><wsa:MessageID></span> uuid: 68da6b24-7fa1-4da2-8a06-e615bfa3d2d0 <span class="ReservedWord"></wsa:MessageID></span> <span class="ReservedWord"></s11:Header></span> <span class="ReservedWord"><s11:Body/></span> <span class="ReservedWord"></s11:Envelope></span></pre><div class="calloutlist"><table border="0" summary="Callout list"><tr><td width="5%" valign="top" align="left"><p><img src="icons/callouts/1.png" alt="1" border="0"></p></td><td valign="top" align="left"><p>SOAP request message to retrieve metadata about a Web service endpoint.</p></td></tr><tr><td width="5%" valign="top" align="left"><p><img src="icons/callouts/2.png" alt="2" border="0"></p></td><td valign="top" align="left"><p>WS-Addressing namespace URI bound to "<code class="literal">wsa</code>" prefix.</p></td></tr><tr><td width="5%" valign="top" align="left"><p><img src="icons/callouts/3.png" alt="3" border="0"></p></td><td valign="top" align="left"><p>The standard WS-Addressing MAPs used to convey the semantics (<code class="literal">wsa:Action</code>), receiver (<code class="literal">wsa:To</code>) of the message, intended receiver of reply (<code class="literal">wsa:ReplyTo</code>) message and identity (<code class="literal">wsa:MessageID</code>) information of the message</p></td></tr></table></div></div><p>This message has an empty SOAP Body and relies completely upon standard MAPs to convey all the information. Similarly, a WS-Metadata Exchange response message with metadata looks like:</p><div class="programlistingco"><pre class="programlisting"><span class="ReservedWord"><s11:Envelope</span> <span class="Identifier">xmlns:s11</span>=<span class="String">"http://schemas.xmlsoap.org/soap/envelope/"</span> <span class="bold"><strong>xmlns:wsa="http://www.w3.org/2005/08/addressing"</strong></span>> <span class="ReservedWord"><s11:Header></span> <span class="ReservedWord"><wsa:Action></span> <span class="co" id=""><img src="icons/callouts/1.png" alt="(1)"></span> <span class="bold"><strong>http://schemas.xmlsoap.org/ws/2004/09/transfer/GetResponse</strong></span> <span class="ReservedWord"></wsa:Action></span> <span class="ReservedWord"><wsa:RelatesTo></span> uuid: 68da6b24-7fa1-4da2-8a06-e615bfa3d2d0 <span class="ReservedWord"></wsa:RelatesTo></span> <span class="ReservedWord"></s11:Header></span> <span class="ReservedWord"><s11:Body/></span> <span class="co" id=""><img src="icons/callouts/2.png" alt="(2)"></span> ... <span class="ReservedWord"><s11:Body/></span> <span class="ReservedWord"></s11:Envelope></span></pre><div class="calloutlist"><table border="0" summary="Callout list"><tr><td width="5%" valign="top" align="left"><p><img src="icons/callouts/1.png" alt="1" border="0"></p></td><td valign="top" align="left"><p>The standard WS-Addressing MAPs used to convey the semantics (<code class="literal">wsa:Action</code>) of the response message and relationship (<code class="literal">wsa:RelatesTo</code>) to the request message.</p></td></tr><tr><td width="5%" valign="top" align="left"><p><img src="icons/callouts/2.png" alt="2" border="0"></p></td><td valign="top" align="left"><p>Abbreviated SOAP Body for simplicity which otherwise would contain the MEX response.</p></td></tr></table></div></div><p><a class="link" href="http://en.wikipedia.org/wiki/WS-ReliableMessaging" target="_top">WS-Reliable Messaging</a> describes a protocol that allows messages to be delivered reliably between distributed applications in the presence of software component, system or network failures. This specification defines protocol messages that must be exchanged between client and service endpoint, before the business message exchange, in order to deliver the messages reliably. For example, RM Source sends <code class="literal"><CreateSequence></code> request message to RM Destination to create an outbound sequence. The message looks like:</p><div class="programlistingco"><pre class="programlisting"><span class="ReservedWord"><s11:Envelope</span> <span class="Identifier">xmlns:s11</span>=<span class="String">"http://schemas.xmlsoap.org/soap/envelope/"</span> <span class="bold"><strong>xmlns:wsa=" http://www.w3.org/2005/08/addressing"</strong></span> xmlns:wsrm=" http://schemas.xmlsoap.org/ws/2005/02/rm"> <span class="ReservedWord"><s11:Body></span> <span class="co" id=""><img src="icons/callouts/1.png" alt="(1)"></span> <span class="ReservedWord"><wsrm:CreateSequence></span> <span class="bold"><strong><wsrm:AcksTo></strong></span> <span class="ReservedWord"><wsa:Address></span> http://www.w3.org/2005/08/addressing/anonymous <span class="ReservedWord"></wsa:Address></span> <span class="bold"><strong></wsrm:AcksTo></strong></span> <span class="ReservedWord"></wsrm:CreateSequence></span> <span class="ReservedWord"></s11:Body></span> <span class="ReservedWord"></s11:Envelope></span></pre><div class="calloutlist"><table border="0" summary="Callout list"><tr><td width="5%" valign="top" align="left"><p><img src="icons/callouts/1.png" alt="1" border="0"></p></td><td valign="top" align="left"><p>SOAP Body of the request message.</p></td></tr></table></div></div><p>The Body contains an element, <code class="literal">wsrm:AcksTo</code> (of the type Endpoint Reference), that specifies the endpoint reference to which <code class="literal"><SequenceAcknowledgement></code> messages and faults related to sequence creation are sent.</p><p>WS-Secure Conversation, WS-Trust, WS-Policy and other similar specifications use the constructs defined by WS-Addressing as building blocks.</p></div></div><div class="section" title="11.2. WS-Addressing Versions"><div class="titlepage"><div><div><h3 class="title" id="ws-addressing-versions">11.2. WS-Addressing Versions</h3></div></div></div><p>There are two prominent versions of WS-Addressing that are commonly used: </p><div class="itemizedlist"><ul class="itemizedlist" type="disc"><li class="listitem"><p><a class="link" href="http://www.w3.org/2002/ws/addr/" target="_top">W3C WS-Addressing</a></p></li><li class="listitem"><p><a class="link" href="http://www.w3.org/Submission/ws-addressing/" target="_top">Member Submission WS-Addressing</a></p></li></ul></div><p>Sun, IBM, BEA, Microsoft and SAP co-authored and submitted a WS-Addressing specification to W3C in August 2004. W3C chartered a new Working Group with a mission to produce a <a class="link" href="http://www.w3.org/2005/10/Process-20051014/tr.html#RecsW3C" target="_top">W3C Recommendation</a> for WS-Addressing by refining the submitted specification. The original specification submitted to W3C is referred as "Member Submission WS-Addressing" or "Submission WS-Addressing". The term <a class="link" href="http://www.w3.org/2005/10/Process-20051014/submission.html#Submission" target="_top">Member Submission</a> is defined by W3C.</p><p>The WG was <a class="link" href="http://www.w3.org/2006/10/ws-addr-charter.html#deliverables" target="_top">chartered</a> to deliver a W3C Recommendation for WS-Addressing <a class="link" href="http://www.w3.org/TR/ws-addr-core" target="_top">Core</a>, <a class="link" href="http://www.w3.org/TR/ws-addr-soap" target="_top">SOAP Binding</a> (mapping abstract properties defined in Core to SOAP 1.1 and 1.2) and <a class="link" href="http://www.w3.org/TR/ws-addr-wsdl" target="_top">WSDL Binding</a> (mechanisms to define property values in WSDL 1.1 and WSDL 2.0 service descriptions) specification. This separate between Core/Bindings is common methodology where Core is relevant to application developers and Binding (both SOAP and WSDL) is relevant for Web service stack implementers. This collective set of specifications is referred as "W3C WS-Addressing".</p><p>JAX-WS RI supports both versions out-of-the-box. Check <a class="link" href="http://jax-ws.java.net/nonav/jax-ws-21-ea2/docs/users-guide-overview" target="_top">Users Guide</a> on how to enable either of the versions on a service endpoint <a class="link" href="http://jax-ws.java.net/nonav/jax-ws-21-ea2/docs/users-guide-ws-addressing#Addressing_annotations" target="_top">starting from Java</a> or <a class="link" href="http://jax-ws.java.net/nonav/jax-ws-21-ea2/docs/users-guide-ws-addressing#Starting_from_WSDL" target="_top">starting from WSDL</a>.</p></div></div><div lang="en" class="section" title="12. WS-Addressing"><div class="titlepage"><div><div><h2 class="title" style="clear: both" id="users-guide-ws-addressing">12. WS-Addressing</h2></div></div></div><div class="section" title="12.1. WS-Addressing in JAX-WS RI"><div class="titlepage"><div><div><h3 class="title" id="ws-addressing-in">12.1. WS-Addressing in JAX-WS RI</h3></div></div></div><p><a class="link" href="http://www.w3.org/2002/ws/addr/" target="_top">Web Services Addressing</a> provides transport-neutral mechanisms to address Web services and messages. JAX-WS 2.2 specification requires support for W3C <a class="link" href="http://www.w3.org/TR/ws-addr-core" target="_top">Core</a>, <a class="link" href="http://www.w3.org/TR/ws-addr-soap" target="_top">SOAP Binding</a> and <a class="link" href="http://www.w3.org/TR/2007/REC-ws-addr-metadata-20070904" target="_top">Addressing 1.0 - Metadata</a> specifications and defines standard API to enable/disable W3C WS-Addressing on the client and service endpoint. In addition to that, JAX-WS RI also supports <a class="link" href="http://www.w3.org/Submission/ws-addressing/" target="_top">Member Submission</a> version of WS-Addressing. The member submission version is supported in an implementation specific way. For compatility with JAX-WS 2.1 behavior, JAX-WS RI 2.2.7 also supports wsdls conforming to <a class="link" href="http://www.w3.org/TR/ws-addr-wsdl" target="_top">WSDL Binding</a> specification. The subsequent sections describe how the two WS-Addressing versions can be enabled/disabled on client and server side .</p></div><div class="section" title="12.2. Why WS-Addressing?"><div class="titlepage"><div><div><h3 class="title" id="why-ws-addressing">12.2. Why WS-Addressing?</h3></div></div></div><p>This <a class="xref" href="#users-guide-why-ws-addressing" title="11. Why WS-Addressing?">Why WS-Addressing?</a> explains what is WS-Addressing and why it is required.</p></div><div class="section" title="12.3. Describing WS-Addressing in WSDL"><div class="titlepage"><div><div><h3 class="title" id="describing-ws-addressing-in-wsdl">12.3. Describing WS-Addressing in WSDL</h3></div></div></div><p>WS Addressing 1.0- Metadata defines standard ways to describe message addressing properties like Action, Destination in wsdl and also indicate the use of Addressing in wsdl. WS-Addressing Metadata specification replaces the previous <a class="link" href="http://www.w3.org/TR/2006/CR-ws-addr-wsdl-20060529/" target="_top">Web Services Addressing 1.0 - WSDL Binding</a> specification in candidate recommendation earlier. If you are still using wsdls conforming to WS Addressing 1.0 - WSDL Binding specification, skip to the next section. Still you may want to update your wsdls to use in standard ways defined by the W3C recommended Addressing 1.0 - Metadata specification for better interoperability. Also, There is no standard mechanism to describe Member Submission version support in the WSDL and some implementaions have used WS-Policy to indicate the support of member submission version and JAX-WS RI understands such assertion.</p><div class="section" title="12.3.1. WS-Addressing 1.0 - Metadata"><div class="titlepage"><div><div><h4 class="title" id="ws-addressing-1-0-metadata">12.3.1. WS-Addressing 1.0 - Metadata</h4></div></div></div><p><a class="link" href="http://www.w3.org/TR/2007/REC-ws-addr-metadata-20070904/" target="_top">Addressing 1.0 - Metadata</a> specification uses Web Services Policy Framework (<a class="link" href="http://www.w3.org/TR/2007/REC-ws-policy-20070904" target="_top">WS Policy 1.5</a>) and Web Services Policy - Attachment [ <a class="link" href="http://www.w3.org/TR/2007/REC-ws-policy-attach-20070904" target="_top">WS Policy 1.5 - Attachment</a>] specifications to express the support of Web Services Addressing 1.0. A new policy assertion <code class="literal"><wsam:Addressing></code> is defined to express the support of Addressing. The <code class="literal">wsam:Addressing</code> policy assertion applies to the endpoint policy subject and may be attached to <code class="literal">wsdl11:port</code> or <code class="literal">wsdl11:binding</code>.</p><p>Indicating the requirement of WS-Addressing: When </p><div class="informalexample"><pre class="programlisting"><span class="ReservedWord"><wsam:Addressing></span></pre></div><p>is present in a Policy alternative, one is required to use WS-Addressing to communicate with the subject.</p><p>Indicating the support of WS-Addressing: </p><div class="informalexample"><pre class="programlisting"><span class="ReservedWord"><wsam:Addressing</span> <span class="Identifier">wsp:Optional</span>=<span class="String">"true"</span><span class="ReservedWord">></span></pre></div><p>can be used to indicate support for WS-Addressing but does not require the use of it. In these cases, there are no restrictions about the use of WS-Adressing.</p><p>In certain cases, the endpoint can lay some restrictions to indicate the messages it can accept with WS-Addressing. Nested asertions can be used to restrict the use of response endpoint inside the <code class="literal"><wsam:Addressing></code> assertion.</p><p>Requiring the use of Non-Anonymous response endpoints:</p><div class="informalexample"><pre class="programlisting"><span class="ReservedWord"><wsam:Addressing></span> <span class="ReservedWord"><wsp:Policy></span> <span class="ReservedWord"><wsam:NonAnonymousResponses/></span> <span class="ReservedWord"></wsp:Policy></span> <span class="ReservedWord"></wsam:Addressing></span></pre></div><p>can be used to indicate that the subject requires WS-Addressing and requires the use of non-anonymous response EPRs. In this case, the response endpoint in the request messages will have to use something other than the anonymous URI as the value of address. This is typically used when the response needs to be sent to a third entity other than the client and service and the response is sent to the non-anonyous URI through a new connection Requiring the use of Anonymous response endpoints:</p><div class="informalexample"><pre class="programlisting"><span class="ReservedWord"><wsam:Addressing></span> <span class="ReservedWord"><wsp:Policy></span> <span class="ReservedWord"><wsam:AnonymousResponses/></span> <span class="ReservedWord"></wsp:Policy></span> <span class="ReservedWord"></wsam:Addressing></span></pre></div><p>can be used to indicate that the subject requires WS-Addressing and requires the use of anonymous responses. In this case, the endpoint requires request messages to use response endpoint EPRs that contain the anonymous URI ("<code class="literal">http://www.w3.org/2005/08/addressing/anonymous</code>") or None URI ("<code class="literal">http://www.w3.org/2005/08/addressing/none</code>") as the value of address.</p></div><div class="section" title="12.3.2. WS-Addressing WSDL Binding"><div class="titlepage"><div><div><h4 class="title" id="ws-addressing-wsdl-binding">12.3.2. WS-Addressing WSDL Binding</h4></div></div></div><p>W3C WS-Addressing WSDL Binding defines an extensibility element, <a class="link" href="http://www.w3.org/TR/2006/CR-ws-addr-wsdl-20060529/#uaee" target="_top">wsaw:UsingAddressing</a>, that can be used to indicate that an endpoint conforms to the WS-Addressing specification. JAX-WS RI generates this extension element in the WSDL if W3C WS-Addressing is enabled on the server-side. On the client side, the RI recognizes this extension element and enforce the rules defined by the W3C specification. This extensibility element may be augmented with <code class="literal">wsdl:required</code> attribute to indicate whether WS-Addressing is required (true) or not (false).</p><p>W3C WS-Addressing WSDL Binding defines <code class="literal">wsaw:Anonymous</code> element which when used in conjunction with <code class="literal">wsaw:UsingAddressing</code> define assertions regarding a requirement or a constraint in the use of anonymous URI in EPRs sent to the endpoint. The WSDL Binding defines three distinct values: <code class="literal">optional</code>, <code class="literal">required</code> and <code class="literal">prohibited</code> to express the assertion. The default value of <code class="literal">wsaw:Anonymous</code> (equivalent to not present) is <code class="literal">optional</code>. An operation with <code class="literal">required</code> <code class="literal">wsaw:Anonymous</code> value is shown below:</p><div class="informalexample"><pre class="programlisting"><span class="ReservedWord"><wsaw:UsingAddressing</span> <span class="Identifier">wsdl:required</span>=<span class="String">"true"</span><span class="ReservedWord">/></span> <span class="ReservedWord"><soap:binding</span> <span class="Identifier">transport</span>=<span class="String">"http://schemas.xmlsoap.org/soap/http"</span> <span class="Identifier">style</span>=<span class="String">"document"</span><span class="ReservedWord">/></span> <span class="ReservedWord"><operation</span> <span class="Identifier">name</span>=<span class="String">"addNumbers"</span><span class="ReservedWord">></span> <span class="ReservedWord"><soap:operation</span> <span class="Identifier">soapAction</span>=<span class="String">""</span><span class="ReservedWord">/></span> ... <span class="ReservedWord"><wsaw:Anonymous></span>required<span class="ReservedWord"></wsaw:Anonymous></span> <span class="ReservedWord"></operation></span> <span class="ReservedWord"><soap:binding></span></pre></div><p>In this case, a message received at the endpoint, for this operation, with a non-anonymous ReplyTo or FaultTo EPR will result in a fault message returned back to the client with <code class="literal">wsa:OnlyAnonymousAddressSupported</code> fault code. There is no such equivalent feature in Member Submission WS-Addressing.</p></div></div><div class="section" title="12.4. Configuring Addressing on Endpoint"><div class="titlepage"><div><div><h3 class="title" id="configuring-addressing-on-endpoint">12.4. Configuring Addressing on Endpoint</h3></div></div></div><p>This section describes how W3C and Member Submission WS-Addressing can be enabled/disabled on the server-side.</p><div class="section" title="12.4.1. Starting from WSDL"><div class="titlepage"><div><div><h4 class="title" id="starting-from-wsdl">12.4.1. Starting from WSDL</h4></div></div></div><p>Starting from WSDL, If the wsdl contains the above described metadata to indicate use addressing at endpoint scope, Addressing is enabled on the server-side. See <a class="xref" href="#describing-ws-addressing-in-wsdl" title="12.3. Describing WS-Addressing in WSDL">Describing WS-Addressing in WSDL</a> section for more details.</p></div><div class="section" title="12.4.2. Starting from Java"><div class="titlepage"><div><div><h4 class="title" id="starting-from-java-1">12.4.2. Starting from Java</h4></div></div></div><p>This section describes how WS-Addressing can be enabled/disabled if you develop an endpoint starting from a Java SEI.</p><p>By default, WS-Addressing is disabled on an endpoint starting from Java. If that is the expected behavior, then nothing else needs to be done. In that case any WS-Addressing headers received at the endpoint are treated like SOAP headers targeted for the appliaction and are ignored.</p><div class="section" title="12.4.2.1. Addressing annotations"><div class="titlepage"><div><div><h5 class="title" id="addressing-annotations">12.4.2.1. Addressing annotations</h5></div></div></div><p>If WS-Addressing support needs to be enabled on an endpoint, then along with <code class="literal">javax.jws.WebService</code> annotation, <code class="literal">javax.xml.ws.soap.Addressing</code> annotation need to be specified for enabling W3C WS-Addressing. If Member Submission WS-Addressing needs to be enabled then <code class="literal">com.sun.xml.ws.developer.MemberSubmissionAddressing</code> annotation needs to be specified on the service endpoint. For example, the service endpoint in <code class="literal">fromjava-wsaddressing</code> sample looks like:</p><div class="informalexample"><pre class="programlisting"><span class="Annotation">@javax.xml.ws.soap.Addressing</span> <span class="Annotation">@javax.jws.WebService</span> <span class="ReservedWord">public</span> <span class="ReservedWord">class</span> AddNumbersImpl { <span class="Comment">// ...</span> }</pre></div><p>To enable, Member Submission WS-Addressing, the SEI definition needs to be changed to:</p><div class="informalexample"><pre class="programlisting"><span class="Annotation">@com.sun.xml.ws.developer.MemberSubmissionAddressing</span> <span class="Annotation">@javax.jws.WebService</span> <span class="ReservedWord">public</span> <span class="ReservedWord">class</span> AddNumbersImpl { <span class="Comment">// ...</span> }</pre></div><p>Once WS-Addressing support is enabled on a service endpoint, then:</p><div class="itemizedlist"><ul class="itemizedlist" type="disc"><li class="listitem"><p>In the generated WSDL, corresponding metadata as described in section Describing Addressing in WSDL is generated.</p></li><li class="listitem"><p>All WS-Addressing headers are understood, i.e. if any WS-Addressing header is received with a <code class="literal">mustUnderstand="1"</code>, then a mustUnderstand fault is not thrown back.</p></li><li class="listitem"><p>All WS-Addressing headers received at the endpoint are checked for correct syntax, for example an error is returned back if <code class="literal">wsa:ReplyTo</code> header does not match the infoset defined in the corresponding specification.</p></li><li class="listitem"><p>If any WS-Addressing header received at the endpoint is not of correct cardinality, then an error is returned back to the client.</p></li><li class="listitem"><p>If <code class="literal">wsa:Action</code> header value does not match with that expected for that operation, then an error is returned back to the client.</p></li><li class="listitem"><p>Any response message sent back to the client contains the required WS-Addressing headers. </p></li></ul></div></div><div class="section" title="12.4.2.2. Is Addressing Optional or Required ?"><div class="titlepage"><div><div><h5 class="title" id="is-addressing-optional-or-required">12.4.2.2. Is Addressing Optional or Required ?</h5></div></div></div><p>Both <code class="literal">javax.xml.ws.soap.Addressing</code> and <code class="literal">com.sun.xml.ws.developer.MemberSubmissionAddressing</code> annotations take two optional Boolean parameters, <code class="literal">enabled</code> (default true) and <code class="literal">required</code> (default false). If <code class="literal">required</code> is specified true, then WS-Addressing rules are enforced. Otherwise the inbound message is inspected to find out if WS-A is engaged and then the rules are enforced. See <a class="xref" href="#when-is-ws-addressing-engaged" title="12.6. When is WS-Addressing engaged?">When is WS-Addressing engaged?</a> section for more details on enforcement during runtime.</p><p>For example, to enforce Member Submission WS-Addressing rules on the server side, the above code sample will change to:</p><div class="informalexample"><pre class="programlisting"><span class="Annotation">@com.sun.xml.ws.developer.MemberSubmissionAddressing(enabled = true, required = true)</span> <span class="Annotation">@javax.jws.WebServicepublic</span> <span class="ReservedWord">class</span> AddNumbersImpl { <span class="Comment">// ...</span> }</pre></div></div></div></div><div class="section" title="12.5. On the client side"><div class="titlepage"><div><div><h3 class="title" id="on-the-client-side">12.5. On the client side</h3></div></div></div><p>This section describes how WS-Addressing can be enabled/disabled on the client-side. JAX-WS RI follows the standard extensibility elements in WSDL to enable WS-Addressing support on the client side. In addition, it also allows the client to instruct JAX-WS RI to disable WS-Addressing processing. The assumption is that in this case the client has it's own WS-Addressing processing module. For example, a Dispatch-based client in MESSAGE mode may be used to perform non-anonymous ReplyTo/FaultTo processing.</p><div class="section" title="12.5.1. Implicit behavior"><div class="titlepage"><div><div><h4 class="title" id="implicit-behavior">12.5.1. Implicit behavior</h4></div></div></div><p>As defined in <a class="xref" href="#describing-ws-addressing-in-wsdl" title="12.3. Describing WS-Addressing in WSDL">Describing WS-Addressing in WSDL</a>, If the WSDL contains metadata about the support or requirement of WS-Addressing, JAX-WS RI runtime enables Addressing feature on the client-side.</p><div class="itemizedlist"><ul class="itemizedlist" type="disc"><li class="listitem"><p>Generates <code class="literal">Action</code>, <code class="literal">To</code>, <code class="literal">MessageID</code> and anonymous <code class="literal">ReplyTo</code> headers on the outbound request.</p></li><li class="listitem"><p>Any WS-Addressing headers received on the client are processed.</p></li></ul></div><p>There is no standard extensibility element for Member Submission WS-Addressing and so there is no implicit behavior defined. It can only be explicitly enabled as described in the next section. </p></div><div class="section" title="12.5.2. Explicit enabling"><div class="titlepage"><div><div><h4 class="title" id="explicit-enabling">12.5.2. Explicit enabling</h4></div></div></div><p>If a WSDL does not contain WS-Addressing standard extensibility element, then either W3C WS-Addressing or Member Submission WS-Addressing can be explicitly enabled using <code class="literal">createDispatch</code> and <code class="literal">getPort</code> methods on <code class="literal">javax.xml.ws.Service</code>. The following new APIs are added in JAX-WS 2.1:</p><div class="itemizedlist"><ul class="itemizedlist" type="disc"><li class="listitem"><div class="informalexample"><pre class="programlisting"><T> Dispatch<T> createDispatch(javax.xml.namespace.QName portName, java.lang.Class<T> type, Service.Mode mode, WebServiceFeature... features)</pre></div></li><li class="listitem"><div class="informalexample"><pre class="programlisting">Dispatch<java.lang.Object> createDispatch(javax.xml.namespace.QName portName, javax.xml.bind.JAXBContext context, Service.Mode mode, WebServiceFeature... features)</pre></div></li><li class="listitem"><div class="informalexample"><pre class="programlisting"><T> T getPort(java.lang.Class<T> serviceEndpointInterface, WebServiceFeature... features)</pre></div></li><li class="listitem"><div class="informalexample"><pre class="programlisting"><T> T getPort(javax.xml.namespace.QName portName, java.lang.Class<T> serviceEndpointInterface, WebServiceFeature... features)</pre></div></li></ul></div><p>Each method is a variation of an already existing method in JAX-WS 2.0. The only addition is an extra var-arg <code class="literal">javax.xml.ws.WebServiceFeature</code> parameter. A <code class="literal">WebServiceFeature</code> is a new class introduced in JAX-WS 2.1 specification used to represent a feature that can be enabled or disabled for a Web service.</p><p>The JAX-WS 2.1 specification defines <code class="literal">javax.xml.ws.soap.AddressingFeature</code> to enable W3C WS-Addressing on the client side. In addition, the JAX-WS RI also defines <code class="literal">com.sun.xml.ws.developer.MemberSubmissionAddressingFeature</code> to enable Member Submission WS-Addressing on the client side.</p><p>For example in <code class="literal">fromjava-wsaddressing</code> example, in order to enable W3C WS-Addressing on a proxy, <span class="command"><strong>wsimport</strong></span> is used to generate the <code class="literal">AddNumbersImplService</code> class. Then a port can be obtained using the <code class="literal">getAddNumbersImplPort</code> method and passing an instance of <code class="literal">javax.xml.ws.AddressingFeature</code>. The code looks like:</p><div class="informalexample"><pre class="programlisting">new AddNumbersImplService().getAddNumbersImplPort(new javax.xml.ws.AddressingFeature());</pre></div><p>Similarly, a <code class="literal">Dispatch</code> instance with Member Submission WS-Addressing can be created as:</p><div class="informalexample"><pre class="programlisting"><span class="ReservedWord">new</span> AddNumbersImplService().createDispatch( <span class="ReservedWord">new</span> QName(<span class="String">"http://server.fromjava_wsaddressing/"</span>, <span class="String">"AddNumbersImplPort"</span>), SOAPMessage.<span class="ReservedWord">class</span>, Service.Mode.MESSAGE, <span class="ReservedWord">new</span> com.sun.xml.ws.developer.MemberSubmissionAddressingFeature());</pre></div><p><span class="bold"><strong>Feature Parameters</strong></span></p><p>Both <code class="literal">javax.xml.ws.soap.AddressingFeature</code> and <code class="literal">com.sun.xml.ws.developer.MemberSubmissionAddressingFeature</code> take two optional Boolean parameters, <code class="literal">enabled</code> (default true) and <code class="literal">required</code> (default false). If enabled, all WS-Addressing headers are generated for an outbound message. If <code class="literal">required</code> is specified true, then WS-Addressing rules are enforced for inbound message. Otherwise the inbound message is inspected to find out if WS-A is engaged and then the rules are enforced.</p><p>For example, to enforce Member Submission WS-Addressing rules on the client side, the above code sample will change to:</p><div class="informalexample"><pre class="programlisting"><span class="ReservedWord">new</span> AddNumbersImplService().getAddNumbersImplPort(<span class="ReservedWord">new</span> com.sun.xml .ws.developer.MemberSubmissionAddressingFeature(true, true));</pre></div></div><div class="section" title="12.5.3. Explicit disabling"><div class="titlepage"><div><div><h4 class="title" id="explicit-disabling">12.5.3. Explicit disabling</h4></div></div></div><p>A client may like to instruct JAX-WS RI to disable WS-Addressing processing. The assumption is that in this case the client has it's own WS-Addressing processing module. For example, a Dispatch-based client in MESSAGE mode may be used to perform non-anonymous ReplyTo/FaultTo processing.</p><p>WS-Addressing processing can be explicitly disabled using one of new methods added to JAX-WS 2.1 specification as defined in Section 3.2. For example, W3C WS-Addressing processing can be disabled using the following code:</p><div class="informalexample"><pre class="programlisting"><span class="ReservedWord">new</span> AddNumbersImplService().getAddNumbersImplPort(<span class="ReservedWord">new</span> javax.xml.ws.AddressingFeature(false));</pre></div></div></div><div class="section" title="12.6. When is WS-Addressing engaged?"><div class="titlepage"><div><div><h3 class="title" id="when-is-ws-addressing-engaged">12.6. When is WS-Addressing engaged?</h3></div></div></div><p>W3C WS-Addressing SOAP Binding <a class="link" href="http://www.w3.org/TR/2006/REC-ws-addr-soap-20060509/#conformance" target="_top">defines</a> that if a receiver processes a message containing a <code class="literal">wsa:Action</code> header, then SOAP Binding is engaged, and the rules of the specification are enforced. In JAX-WS RI, if WS-Addressing is explicitly disabled then the RI does not follow the rules of engagement. However if WS-Addressing is either implicitly or explicitly enabled then JAX-WS RI engages WS-Addressing based upon the presence of <code class="literal">wsa:Action</code> header. JAX-WS RI follows same rule for Member Submission version as well.</p><p>In effect, if an endpoint advertises WS-Addressing is required in the WSDL and a client does not send any WS-Addressing header then no WS-Addressing fault is returned back to the client. However if the client send <code class="literal">wsa:Action</code> header then the endpoint will enforce all the rules of the specification. For example, if the <code class="literal">wsa:MessageID</code> header is missing for a request/response MEP then a fault with appropriate code and sub-code is thrown back to the client.</p></div><div class="section" title="12.7. Associating Action with an operation"><div class="titlepage"><div><div><h3 class="title" id="associating-action-with-an-operation">12.7. Associating Action with an operation</h3></div></div></div><div class="section" title="12.7.1. Implicit Action"><div class="titlepage"><div><div><h4 class="title" id="implicit-action">12.7.1. Implicit Action</h4></div></div></div><p>In most common cases, an implicit Action association, as defined by <a class="link" href="http://www.w3.org/TR/2007/REC-ws-addr-metadata-20070904/#actioninwsdl" target="_top">W3C WS-Addressing 1.0 - Metadata</a> and <a class="link" href="http://www.w3.org/Submission/ws-addressing/#_Toc77464327" target="_top">Member Submission</a>, will be sufficient. For such cases, only using the correct annotation to enable Addressing is required. The client looking at such a WSDL will send the implicit <code class="literal">wsa:Action</code> header. If only Addressing is enabled by using the appropriate annotation at the SEI, </p></div><div class="section" title="12.7.2. Explicit Action"><div class="titlepage"><div><div><h4 class="title" id="explicit-action">12.7.2. Explicit Action</h4></div></div></div><p>This section describes how an explicit Action Message Addressing Property can be associated with an operation in the SEI.</p><p>W3C WS-Addressing <a class="link" href="http://www.w3.org/TR/2007/REC-ws-addr-metadata-20070904/#actioninwsdl" target="_top">W3C WS-Addressing 1.0 - Metadata</a> and <a class="link" href="http://www.w3.org/Submission/ws-addressing/#_Toc77464325" target="_top">Member Submission WS-Addressing</a> define mechanisms to associate Action Message Addressing Property with an operation. JAX-WS 2.1 defines <code class="literal">javax.xml.ws.Action</code> and <code class="literal">javax.xml.ws.FaultAction</code> annotations to explicitly associate an Action with <code class="literal">input</code>, <code class="literal">output</code>, and <code class="literal">fault</code> messages of the mapped WSDL operation. For example, one of the methods in the <code class="literal">fromjava-wsaddressing</code> sample looks like:</p><div class="informalexample"><pre class="programlisting"><span class="Annotation">@Action(input = "http://example.com/input3", output = "http://example.com/output3", fault = {@FaultAction(className = AddNumbersException.class, value = "http://example.com/fault3")})</span> <span class="ReservedWord">public</span> <span class="ReservedWord">int</span> addNumbers3(<span class="ReservedWord">int</span> number1, <span class="ReservedWord">int</span> number2) <span class="ReservedWord">throws</span> AddNumbersException { <span class="Comment">// ...</span> }</pre></div><p>The generated WSDL fragment looks like:</p><div class="informalexample"><pre class="programlisting"><span class="ReservedWord"><operation</span> <span class="Identifier">name</span>=<span class="String">"addNumbers3"</span><span class="ReservedWord">></span> <span class="ReservedWord"><input</span> <span class="Identifier">wsam:Action</span>=<span class="String">"http://example.com/input3"</span> <span class="Identifier">message</span>=<span class="String">"tns:addNumbers3"</span><span class="ReservedWord">/></span> <span class="ReservedWord"><output</span> <span class="Identifier">wsam:Action</span>=<span class="String">"http://example.com/output3"</span> <span class="Identifier">message</span>=<span class="String">"tns:addNumbers3Response"</span><span class="ReservedWord">/></span> <span class="ReservedWord"><fault</span> <span class="Identifier">message</span>=<span class="String">"tns:AddNumbersException"</span> <span class="Identifier">name</span>=<span class="String">"AddNumbersException"</span> <span class="Identifier">wsam:Action</span>=<span class="String">"http://example.com/fault3"</span><span class="ReservedWord">/></span> <span class="ReservedWord"></operation></span></pre></div><p>where <code class="literal">wsam</code> is bound to W3C WS-Addressing 1.0 - Metadata namespace or Member Submission namespace depending upon the annotation used to enable Addressing. </p></div></div></div><div lang="en" class="section" title="13. Stateful Webservice"><div class="titlepage"><div><div><h2 class="title" style="clear: both" id="users-guide-stateful-webservice">13. Stateful Webservice</h2></div></div></div><div class="section" title="13.1. Introduction"><div class="titlepage"><div><div><h3 class="title" id="introduction-1">13.1. Introduction</h3></div></div></div><p>JAX-WS RI has a vendor extension that allows developers to bring back object state to the web service world. Normally, JAX-WS RI only creates one instance of a service class, and have it serve all incoming requests concurrently. This makes it essentially impossible to use instance fields of the service class for any meaningful purpose.</p><p>Because of this, people end up coding like C, in anti-OO fashion. Either that or you end up with writing boiler-plate code to dispatch a request to the right instance of your real domain object.</p><p>The stateful web service support in JAX-WS RI resolves this problem by having JAX-WS RI maintain multiple instances of a service. By using <a class="xref" href="#users-guide-ws-addressing" title="12. WS-Addressing">WS-Addressing</a> behind the scene, it provides a standard-based on-the-wire protocol and easy-to-use programming model.</p></div><div class="section" title="13.2. Usage"><div class="titlepage"><div><div><h3 class="title" id="usage">13.2. Usage</h3></div></div></div><p>Application service implementation classes (or providers) who'd like to use the stateful web service support must declare <code class="code">@Stateful</code> annotation on a class. It should also have a <span class="bold"><strong>public static</strong></span> method/field that takes <code class="code">StatefulWebServiceManager</code>.</p><div class="informalexample"><pre class="programlisting"><span class="Annotation">@Stateful</span> <span class="Annotation">@WebService</span> <span class="Annotation">@Addressing</span> <span class="ReservedWord">class</span> BankAccount { <span class="ReservedWord">protected</span> <span class="ReservedWord">final</span> <span class="ReservedWord">int</span> id; <span class="ReservedWord">private</span> <span class="ReservedWord">int</span> balance; BankAccount(<span class="ReservedWord">int</span> id) { <span class="ReservedWord">this</span>.id = id; } <span class="Annotation">@WebMethod</span> <span class="ReservedWord">public</span> <span class="ReservedWord">synchronized</span> <span class="ReservedWord">void</span> deposit(<span class="ReservedWord">int</span> amount) { balance += amount; } <span class="Comment">// either via a public static field</span> <span class="ReservedWord">public</span> <span class="ReservedWord">static</span> StatefulWebServiceManager<BankAccount> manager; <span class="Comment">// ... or via a public static method (the method name could be </span> <span class="Comment">// anything)</span> <span class="ReservedWord">public</span> <span class="ReservedWord">static</span> <span class="ReservedWord">void</span> setManager(StatefulWebServiceManager<BankAccount> manager) { <span class="Comment">// ...</span> } }</pre></div><p>After your service is deployed but before you receive a first request, the resource injection occurs on the field or the method.</p><p>A stateful web service class does not need to have a default constructor. In fact, most of the time you want to define a constructor that takes some arguments, so that each instance carries certain state (as illustrated in the above example).</p><p>Each instance of a stateful web service class is identified by an unique <code class="literal">EndpointReference</code>. Your application creates an instance of a class, then you'll have JAX-WS RI assign this unique EPR for the instance as follows:</p><div class="informalexample"><pre class="programlisting"><span class="Annotation">@WebService</span> <span class="ReservedWord">class</span> Bank { <span class="Comment">// this is ordinary stateless service</span> <span class="Annotation">@WebMethod</span> <span class="ReservedWord">public</span> <span class="ReservedWord">synchronized</span> W3CEndpointReference login(<span class="ReservedWord">int</span> accountId, <span class="ReservedWord">int</span> pin) { <span class="ReservedWord">if</span> (!checkPin(pin)) <span class="ReservedWord">throw</span> <span class="ReservedWord">new</span> AuthenticationFailedException(<span class="String">"invalid pin"</span>); BankAccount acc = <span class="ReservedWord">new</span> BankAccount(accountId); <span class="ReservedWord">return</span> BankAccount.manager.export(acc); } }</pre></div><p>Typically you then pass this EPR to remote systems. When they send messages to this EPR, JAX-WS RI makes sure that the particular exported instance associated with that EPR will receive a service invocation.</p></div><div class="section" title="13.3. Things To Consider"><div class="titlepage"><div><div><h3 class="title" id="things-to-consider">13.3. Things To Consider</h3></div></div></div><p>When you no longer need to tie an instance to the EPR, use <code class="literal">unexport(Object)</code> so that the object can be GC-ed (or else you'll leak memory). You may choose to do so explicitly, or you can rely on the time out by using <code class="literal">setTimeout(long, Callback)</code>.</p><p><code class="literal">StatefulWebServiceManager</code> is thread-safe. It can be safely invoked from multiple threads concurrently.</p></div></div><div lang="en" class="section" title="14. Catalog"><div class="titlepage"><div><div><h2 class="title" style="clear: both" id="users-guide-catalog">14. Catalog</h2></div></div></div><div class="section" title="14.1. Catalog Support"><div class="titlepage"><div><div><h3 class="title" id="section-529979392543239">14.1. Catalog Support</h3></div></div></div><p>Often times, such as for performance reason or your application specific needs, you have a need where you want to resolve the WSDL/Schema documents resolved from the copy of it you have either bundled with your client or server or just to resolve it not from where a WSDL/schema imports points to but rather from where you want it to be picked up.</p><div class="section" title="14.1.1. A Sample catalog file"><div class="titlepage"><div><div><h4 class="title" id="section-459374253706355">14.1.1. A Sample catalog file</h4></div></div></div><div class="example"><a name="d0e7409"></a><p class="title"><b>Example 36. <code class="filename">jax-ws-catalog.xml</code></b></p><div class="example-contents"><pre class="programlisting"><catalog xmlns="urn:oasis:names:tc:entity:xmlns:xml:catalog" prefer=" system"> ... < system systemId=" http://foo.org/hello?wsdl" uri="HelloService.wsdl"/> </catalog></pre></div></div><br class="example-break"><div class="section" title="14.1.1.1. Location of the catalog file"><div class="titlepage"><div><div><h5 class="title" id="section-695398485401359">14.1.1.1. Location of the catalog file</h5></div></div></div><div class="itemizedlist"><ul class="itemizedlist" type="disc"><li class="listitem"><p>For <span class="command"><strong>wsimport</strong></span> command-line or ant task </p><div class="itemizedlist"><ul class="itemizedlist" type="circle"><li class="listitem"><p>use <code class="option">-catalog</code> option to pass the catalog file. The name of the catalog file does not matter for <span class="command"><strong>wsimport</strong></span> tool but for consistency you may like to call it <code class="filename">jax-ws-catalog.xml</code></p></li><li class="listitem"><p>use </p><pre class="programlisting"><span class="ReservedWord"><wsimport</span> <span class="Identifier">catalog</span>=<span class="String">"''></span></pre><p>or</p><pre class="programlisting"><xmlcatalog ... /></pre><p>with <span class="command"><strong>wsimport</strong></span> ant task</p></li></ul></div></li><li class="listitem"><p>Client Runtime </p><div class="itemizedlist"><ul class="itemizedlist" type="circle"><li class="listitem"><p><code class="filename">META-INF/jax-ws-catalog.xml</code> picked up from classpath</p></li></ul></div></li><li class="listitem"><p>Lightweight HTTP server (j2se) based endpoints </p><div class="itemizedlist"><ul class="itemizedlist" type="circle"><li class="listitem"><p><code class="filename">META-INF/jax-ws-catalog.xml</code> picked up from classpath</p></li></ul></div></li><li class="listitem"><p>Servlet based endpoints or JSR 109 based Web Module </p><div class="itemizedlist"><ul class="itemizedlist" type="circle"><li class="listitem"><p><code class="filename">WEB-INF/jax-ws-catalog.xml</code></p></li></ul></div></li><li class="listitem"><p>JSR 109 based EJB Modules </p><div class="itemizedlist"><ul class="itemizedlist" type="circle"><li class="listitem"><p><code class="filename">META-INF/jax-ws-catalog.xml</code></p></li></ul></div></li></ul></div><p>For details on XML catalog see <a class="link" href="http://xml.apache.org/commons/components/resolver/resolver-article.html" target="_top">here</a>.</p></div></div></div></div><div lang="en" class="section" title="15. WAR File Packaging"><div class="titlepage"><div><div><h2 class="title" style="clear: both" id="users-guide-war-file-packaging">15. WAR File Packaging</h2></div></div></div><div class="section" title="15.1. The WAR Contents"><div class="titlepage"><div><div><h3 class="title" id="section-5694250262578">15.1. The WAR Contents</h3></div></div></div><p>Typically, one creates the WAR file with a GUI development tool or with the <code class="literal">ant</code> <code class="literal">war</code> task from the generated artifacts from <span class="command"><strong>wsimport</strong></span>, <span class="command"><strong>wsgen</strong></span>, or <span class="command"><strong>apt</strong></span> tools.</p><p>For example, a sample WAR file starting from a WSDL file:</p><div class="table"><a name="d0e7514"></a><p class="title"><b>Table 26. Files contained in WAR when starting from WSDL</b></p><div class="table-contents"><table summary="Files contained in WAR when starting from WSDL" border="1"><colgroup><col width="50%"><col width="50%"></colgroup><thead><tr><th>File</th><th>Description</th></tr></thead><tbody><tr><td><code class="code">WEB-INF/classes/hello/HelloIF.class</code></td><td><p>SEI</p></td></tr><tr><td><code class="code">WEB-INF/classes/hello/HelloImpl.class</code></td><td><p>Endpoint</p></td></tr><tr><td><code class="code">WEB-INF/sun-jaxws.xml</code></td><td><p>JAX-WS RI deployment descriptor</p></td></tr><tr><td><code class="code">WEB-INF/web.xml</code></td><td><p>Web deployment descriptor</p></td></tr><tr><td><code class="code">WEB-INF/wsdl/HelloService.wsdl</code></td><td><p>WSDL</p></td></tr><tr><td><code class="code">WEB-INF/wsdl/schema.xsd</code></td><td><p>WSDL imports this Schema</p></td></tr></tbody></table></div></div><br class="table-break"></div><div class="section" title="15.2. The sun-jaxws.xml File"><div class="titlepage"><div><div><h3 class="title" id="the-sun-jaxws-xml-file">15.2. The <code class="literal">sun-jaxws.xml</code> File</h3></div></div></div><p>The <code class="literal"><endpoints></code> element contain one or more <code class="literal"><endpoint></code> elements. Each endpoint represents a port in the WSDL and it contains all information about <code class="literal">implementation</code> class, servlet <code class="literal">url-pattern</code>, <code class="literal">binding</code>, <code class="literal">WSDL</code>, <code class="literal">service</code>, <code class="literal">port</code> QNames. The following shows a <code class="literal">sun-jaxws.xml</code> file for a simple <code class="literal">HelloWorld</code> service. <code class="filename">sun-jaxws.xml</code> is the schema instance of <a class="link" href="sun-jaxws.xsd" target="_top">sun-jaxws.xsd</a>.</p><div class="informalexample"><pre class="programlisting"><span class="hl-directive" style="color: maroon"><?xml version="1.0" encoding="UTF-8"?></span> <span class="ReservedWord"><endpoints</span> <span class="Identifier">xmlns</span>=<span class="String">"http://java.sun.com/xml/ns/jax-ws/ri/runtime"</span> <span class="Identifier">version</span>=<span class="String">"2.0"</span><span class="ReservedWord">></span> <span class="ReservedWord"><endpoint</span> <span class="Identifier">name</span>=<span class="String">"MyHello"</span> <span class="Identifier">implementation</span>=<span class="String">"hello.HelloImpl"</span> <span class="Identifier">url-pattern</span>=<span class="String">"/hello"</span><span class="ReservedWord">/></span> <span class="ReservedWord"></endpoints></span></pre></div><p>Endpoint can have the following attributes:</p><div class="table"><a name="d0e7616"></a><p class="title"><b>Table 27. <code class="literal">sun-jaxws.xml</code> - Endpoint element attributes.</b></p><div class="table-contents"><table summary="sun-jaxws.xml - Endpoint element
 attributes." border="1"><colgroup><col width="33%"><col width="33%"><col width="34%"></colgroup><thead><tr><th><p>Attribute</p></th><th><p>Optional</p></th><th><p>Use</p></th></tr></thead><tbody><tr><td><code class="code">name </code></td><td><p>N</p></td><td><p>Name of the endpoint</p></td></tr><tr><td><code class="code">wsdl </code></td><td><p>Y</p></td><td><p>Primary wsdl file location in the WAR file. For e.g. <code class="filename">WEB-INF/wsdl/HelloService.wsdl</code>. If this isn't specified, JAX-WS will create and publish a new WSDL. When the service is developed from Java, it is recommended to omit this attribute.</p></td></tr><tr><td><code class="code">service </code></td><td><p>Y</p></td><td><p>QName of WSDL service. For e.g. <code class="literal">{http://example.org/}HelloService</code>. When the service is developed from Java, it is recommended to omit this attribute.</p></td></tr><tr><td><code class="code">port </code></td><td><p>Y</p></td><td><p>QName of WSDL port. For e.g. <code class="literal">{http://example.org/}HelloPort</code>. When the service is developed from Java, it is recommended to omit this attribute.</p></td></tr><tr><td><code class="code">implementation </code></td><td><p>N</p></td><td><p>Endpoint implementation class name. For e.g: <code class="literal">hello.HelloImpl</code>. The class should have a <code class="literal">@WebService</code> annotation. Provider based implementation class should have a <code class="literal">@WebServiceProvider</code> annotation.</p></td></tr><tr><td><code class="code">url-pattern </code></td><td><p>N</p></td><td><p>Should match <code class="literal"><url-pattern></code> in <code class="filename">web.xml</code></p></td></tr><tr><td><code class="code">binding </code></td><td><p>Y</p></td><td><p>Binding id defined in the JAX-WS API. The possible values are:</p><div class="itemizedlist"><ul class="itemizedlist" type="disc"><li class="listitem"><p><code class="literal">"http://schemas.xmlsoap.org/wsdl/soap/http"</code></p></li><li class="listitem"><p><code class="literal">"http://www.w3.org/2003/05/soap/bindings/HTTP/"</code></p></li></ul></div><p>If omitted, it is considered <code class="literal">SOAP1.1</code> binding.</p></td></tr><tr><td><code class="code">enable-mtom </code></td><td><p>Y</p></td><td><p>Enables MTOM optimization. <code class="literal">true</code> or <code class="literal">false</code>. Default is <code class="literal">false</code>.</p></td></tr></tbody></table></div></div><br class="table-break"><p>Endpoint can have a optional <code class="literal">handler-chain</code> element:</p><div class="informalexample"><pre class="programlisting"><span class="hl-directive" style="color: maroon"><?xml version="1.0" encoding="UTF-8"?></span> <span class="ReservedWord"><endpoints</span> <span class="Identifier">...></span> <span class="Identifier"><endpoint</span> <span class="Identifier">...></span> <span class="Identifier"><handler-chain></span> <span class="Identifier"><handler-chain-name>somename</handler-chain-name></span> <span class="Identifier"><handler></span> <span class="Identifier"><handler-name>MyHandler</handler-name></span> <span class="Identifier"><handler-class>hello.MyHandler</handler-class></span> <span class="Identifier"></handler></span> <span class="Identifier"></handler-chain></span> <span class="Identifier"></endpoint></span> <span class="Identifier"></endpoints></span></pre></div></div><div class="section" title="15.3. The web.xml File"><div class="titlepage"><div><div><h3 class="title" id="section-42577169574826">15.3. The <code class="literal">web.xml</code> File</h3></div></div></div><p>The following shows a <code class="literal">web.xml</code> file for a simple <code class="literal">HelloWorld</code> service. It specifies JAX-WS RI specific listener, servlet classes. These classes are <code class="literal">com.sun.ws.transport.http.servlet.WSServletContextListener</code>, and <code class="literal">com.sun.xml.ws.transport.http.servlet.WSServlet</code> is servlet</p><div class="informalexample"><pre class="programlisting"><span class="hl-directive" style="color: maroon"><?xml version="1.0" encoding="UTF-8"?></span> <span class="Comment"><!DOCTYPE web-app PUBLIC "-//Sun Microsystems, Inc.//DTD Web Application 2.3//EN" "http://java.sun.com/j2ee/dtds/web-app_2_3.dtd"></span> <span class="ReservedWord"><web-app></span> <span class="ReservedWord"><listener></span> <span class="ReservedWord"><listener-class></span> com.sun.xml.ws.transport.http.servlet.WSServletContextListener <span class="ReservedWord"></listener-class></span> <span class="ReservedWord"></listener></span> <span class="ReservedWord"><servlet></span> <span class="ReservedWord"><servlet-name></span>hello<span class="ReservedWord"></servlet-name></span> <span class="ReservedWord"><servlet-class></span>com.sun.xml.ws.transport.http.servlet.WSServlet <span class="ReservedWord"></servlet-class></span> <span class="ReservedWord"><load-on-startup></span>1<span class="ReservedWord"></load-on-startup></span> <span class="ReservedWord"></servlet></span> <span class="ReservedWord"><servlet-mapping></span> <span class="ReservedWord"><servlet-name></span>hello<span class="ReservedWord"></servlet-name></span> <span class="ReservedWord"><url-pattern></span>/hello<span class="ReservedWord"></url-pattern></span> <span class="ReservedWord"></servlet-mapping></span> <span class="ReservedWord"><session-config></span> <span class="ReservedWord"><session-timeout></span>60<span class="ReservedWord"></session-timeout></span> <span class="ReservedWord"></session-config></span> <span class="ReservedWord"></web-app></span></pre></div><p>Remember these requirements when building a WAR:</p><div class="itemizedlist"><ul class="itemizedlist" type="disc"><li class="listitem"><p>WSDL and auxiliary WSDL, Schema files should be packaged under <code class="filename">WEB-INF/wsdl</code> dir. It is recommended that they need not be packaged when the service is started from Java</p></li><li class="listitem"><p>WebService implementation class should contain a <code class="literal">@WebService</code> annotation. Provider based endpoints should have a <code class="literal">@WebServiceProvider</code> annotation.</p></li><li class="listitem"><p><code class="literal">wsdl</code>, <code class="literal">service</code>, <code class="literal">port</code> attributes are mandatory for <code class="literal">Provider</code> based endpoints and can be specified in the <code class="literal">@WebServiceProvider</code> annotation or deployment descriptor (<code class="filename">sun-jaxws.xml</code>).</p></li></ul></div></div></div><div lang="en" class="section" title="16. Interoperability"><div class="titlepage"><div><div><h2 class="title" style="clear: both" id="users-guide-interoperability">16. Interoperability</h2></div></div></div><p>JAX-WS RI 2.2.7 provides a comprehensive interoperability platform to develop web services solutions. Here are the key interoperability features:</p><div class="section" title="16.1. WSDL and Message Level Interoperability"><div class="titlepage"><div><div><h3 class="title" id="section-4101350549640481">16.1. WSDL and Message Level Interoperability</h3></div></div></div><div class="itemizedlist"><ul class="itemizedlist" type="disc"><li class="listitem"><p>JAX-WS 2.1</p></li><li class="listitem"><p>JAXB 2.1</p></li><li class="listitem"><p>SAAJ</p></li><li class="listitem"><p>Stax</p></li><li class="listitem"><p>WS-I Basic Profile 1.2 and 2.0</p></li><li class="listitem"><p>WS-I Simple SOAP Binding Profile 1.0</p></li><li class="listitem"><p>WS-I Attachment Profile 1.0</p></li><li class="listitem"><p>SOAP 1.1 and SOAP 1.2</p></li><li class="listitem"><p>WSDL 1.1</p></li><li class="listitem"><p>Web Services Addressing 1.0 - Core, Web Services Addressing 1.0 - SOAP Binding and Web Services Addressing 1.0 - Metadata</p></li><li class="listitem"><p>MTOM and SOAP With Attachments</p></li></ul></div></div><div class="section" title="16.2. .NET 3.5 Interoperability"><div class="titlepage"><div><div><h3 class="title" id="section-325661411410258">16.2. .NET 3.5 Interoperability</h3></div></div></div><div class="itemizedlist"><ul class="itemizedlist" type="disc"><li class="listitem"><p>Provided thru <a class="link" href="http://wsit.java.net" target="_top">WSIT</a> plugins.</p></li><li class="listitem"><p>JAX-WS 2.2.7 and WSIT plugins are tightly integrated in to <a class="link" href="http://glassfish.java.net/public/downloadsjax-ws-ri-overview" target="_top">GF v3.1</a></p></li><li class="listitem"><p>Tested for interoperability with .NET 3.0</p></li><li class="listitem"><p>.NET 3.0 interoperable WS-* features supported through WSIT </p><div class="itemizedlist"><ul class="itemizedlist" type="circle"><li class="listitem"><p>WS-ReliableMessaging</p></li><li class="listitem"><p>WS-Policy</p></li><li class="listitem"><p>WS-MEX</p></li><li class="listitem"><p>WS-Security/WS-Security Policy</p></li><li class="listitem"><p>WS-Trust/WS-Secure Conversation</p></li><li class="listitem"><p>WS-AT/WS-Tx (Supported only on Glassfish v2)</p></li><li class="listitem"><p>WS-Addresssing</p></li><li class="listitem"><p>MTOM</p></li></ul></div></li><li class="listitem"><p>Get standalone consolidated bundle of JAX-WS 2.2.7 and WSIT from <a class="link" href="http://metro.java.net/" target="_top">Metro website</a>.</p></li></ul></div><p>Send your feedback to <a class="link" href="mailto:users@jax-ws.java.net" target="_top">users@jaxws.dev.java.net</a>.</p></div></div><div lang="en" class="section" title="17. Endpoint API"><div class="titlepage"><div><div><h2 class="title" style="clear: both" id="users-guide-endpoint-api">17. Endpoint API</h2></div></div></div><p>Web Service endpoints can be created and published programmatically using <code class="literal">javax.xml.ws.Endpoint</code> API. An endpoint consists of a Web Service Implementation object and some configuration information. The implementation hosts the web service endpoint using a light weight http server and clients can access the web service as if the endpoint is deployed in a J2EE container. This means that there is no need to have any J2EE servlet or EJB container to host the endpoint. The <code class="literal">Endpoint</code> API provides a way to configure the endpoint with the necessary binding, metadata (WSDL and schema documents), handlers etc.</p><div class="section" title="17.1. Endpoint"><div class="titlepage"><div><div><h3 class="title" id="section-0499646435494807">17.1. <code class="literal">Endpoint</code></h3></div></div></div><p>An endpoint can be created using any of the following constructors:</p><div class="informalexample"><pre class="programlisting">Endpoint.create(implementor)</pre></div><div class="informalexample"><pre class="programlisting">Endpoint.create(bindingId,implementor) </pre></div><div class="informalexample"><pre class="programlisting">Endpoint.publish(address, implementor) </pre></div><p>Once the <code class="literal">Endpoint</code> object is created using the first two constructors, it can be published using <code class="literal">Endpoint.publish()</code>. Any published <code class="literal">Endpoint</code> can be stopped using <code class="literal">Endpoint.stop()</code>. <a class="link" href="../samples/supplychain/src/supplychain/server/WarehouseLightWeight.java" target="_top"><span class="application">supplychain</span></a> sample shows creating and publishing an <code class="literal">Endpoint</code>.</p></div><div class="section" title="17.2. Endpoint and Properties"><div class="titlepage"><div><div><h3 class="title" id="section-2491869058427427">17.2. <code class="literal">Endpoint</code> and <code class="literal">Properties</code></h3></div></div></div><p>An endpoint can be configured to match service name and port name of WSDL using properties. This overwrites implementor object's serviceName, portName from <code class="literal">@WebService</code> annotation. The port address for an endpoint is patched only if the corresponding port's service name, and port name in WSDL are matched.</p><div class="example"><a name="d0e7989"></a><p class="title"><b>Example 37. <code class="literal">Endpoint</code> and <code class="literal">Properties</code> Example</b></p><div class="example-contents"><pre class="programlisting">Endpoint endpoint = ... Map<String, Object> map = <span class="ReservedWord">new</span> HashMap<String, Object>(); map.put(Endpoint.WSDL_SERVICE, <span class="ReservedWord">new</span> QName(...)); map.put(Endpoint.WSDL_PORT, <span class="ReservedWord">new</span> QName(...)); endpoint.setProperties(map);</pre></div></div><br class="example-break"></div><div class="section" title="17.3. Endpoint and Binding"><div class="titlepage"><div><div><h3 class="title" id="section-9038221558727715">17.3. <code class="literal">Endpoint</code> and <code class="literal">Binding</code></h3></div></div></div><p>An endpoint can be configured for different bindings using binding ids. These binding ids are defined in JAX-WS API and endpoint can be configured by specifying <code class="literal">@BindingType</code> annotation or using binding id in the <code class="literal">Endpoint()</code> constructors. The parameter in constructor overwrites binding defined by <code class="literal">@BindingType</code> annotation. If the binding is not specified using <code class="literal">@BindingType</code> or using a parameter in <code class="literal">Endpoint()</code> constructor, the default binding is <code class="literal">SOAP1.1</code>/<code class="literal">HTTP</code>. Binding object is used to configure MTOM, handler chain etc. SOAP binding object is used to configure SOAP binding specifics like roles.</p><p>For example:</p><div class="example"><a name="d0e8031"></a><p class="title"><b>Example 38. <code class="literal">Endpoint</code> and <code class="literal">Binding</code> Example</b></p><div class="example-contents"><p>The following configures the endpoint for <code class="literal">XML/HTTP</code> binding.</p><pre class="programlisting">Endpoint endpoint = Endpoint.create(HTTPBinding.HTTP_BINDING, implementor);</pre><p>Working with a <code class="literal">Binding</code> object:</p><pre class="programlisting"><span class="Comment">// setting MTOM</span> SOAPBinding binding = (SOAPBinding) endpoint.getBinding(); binding.setMTOMEnabled(true); <span class="Comment">// setting SOAP binding roles</span> binding.setRoles(...); <span class="Comment">// setting handler chain</span> binding.setHandlerChain(...);</pre></div></div><br class="example-break"></div><div class="section" title="17.4. Endpoint and metadata"><div class="titlepage"><div><div><h3 class="title" id="section-091994350952741">17.4. <code class="literal">Endpoint</code> and <code class="literal">metadata</code></h3></div></div></div><p>When the service endpoint is created using existing java classes, the implementation dynamically generates and publishes WSDL and schema documents. But when the service endpoint is created using existing WSDL documents, the same WSDL documents can be used for publishing using metadata facility. When a <code class="literal">Source</code> object is created, set <code class="literal">systemId</code> always and make sure the imports are resolvable w.r.t <code class="literal">systemId</code>s.</p><div class="example"><a name="d0e8071"></a><p class="title"><b>Example 39. <code class="literal">Endpoint</code> and <code class="literal">metadata</code> Example</b></p><div class="example-contents"><pre class="programlisting"><span class="Comment">// metadata processing for WSDL, schema files</span> List<File> metadataFile =... List<Source> metadata = <span class="ReservedWord">new</span> ArrayList<Source>(); <span class="ReservedWord">for</span> (File file : metadataFile) { Source source = <span class="ReservedWord">new</span> StreamSource(<span class="ReservedWord">new</span> FileInputStream(file)); source.setSystemId(file.toURL().toExternalForm()); metadata.add(source); } endpoint.setMetadata(metadata);</pre></div></div><br class="example-break"></div></div></div><div lang="en" class="chapter" title="Tools" id="tools"><div class="titlepage"><div><div><h2 class="title">Tools</h2></div></div></div><div class="toc"><p><b>Table of Contents</b></p><dl><dt><span class="section"><a href="#tools-overview">1. Overview</a></span></dt><dd><dl><dt><span class="section"><a href="#apttool">1.1. <span class="command"><strong>apt</strong></span></a></span></dt><dt><span class="section"><a href="#wscompiletool">1.2. <span class="command"><strong>wsimport</strong></span></a></span></dt><dt><span class="section"><a href="#wsdeploytool">1.3. <span class="command"><strong>wsgen</strong></span></a></span></dt><dt><span class="section"><a href="#how">1.4. How do I pick a tool?</a></span></dt></dl></dd><dt><span class="section"><a href="#tools-wsimport">2. <span class="command"><strong>wsimport</strong></span></a></span></dt><dd><dl><dt><span class="section"><a href="#wsimport-overview">2.1. <span class="command"><strong>wsimport</strong></span> Overview</a></span></dt><dt><span class="section"><a href="#launching-wsimport">2.2. Launching <span class="command"><strong>wsimport</strong></span></a></span></dt><dt><span class="section"><a href="#running-wsimport-on-jdk-6">2.3. Running <span class="command"><strong>wsimport</strong></span> on JDK 6</a></span></dt><dt><span class="section"><a href="#wsimport-syntax">2.4. <span class="command"><strong>wsimport</strong></span> Syntax</a></span></dt><dt><span class="section"><a href="#wsimport-example">2.5. <span class="command"><strong>wsimport</strong></span> Example</a></span></dt></dl></dd><dt><span class="section"><a href="#tools-wsimport-ant-task">3. <span class="command"><strong>wsimport</strong></span> Ant Task</a></span></dt><dd><dl><dt><span class="section"><a href="#wsimport-task-overview">3.1. <span class="command"><strong>wsimport</strong></span> Task Overview</a></span></dt><dt><span class="section"><a href="#using-wsimport-task">3.2. Using <span class="command"><strong>wsimport</strong></span> Task</a></span></dt><dt><span class="section"><a href="#running-wsimport-task-on-jdk-6">3.3. Running <span class="command"><strong>wsimport</strong></span> Task on JDK 6</a></span></dt><dt><span class="section"><a href="#examples">3.4. <span class="command"><strong>wsimport</strong></span> Examples</a></span></dt></dl></dd><dt><span class="section"><a href="#tools-wsgen">4. <span class="command"><strong>wsgen</strong></span></a></span></dt><dd><dl><dt><span class="section"><a href="#wsgen-overview">4.1. <span class="command"><strong>wsgen</strong></span> Overview</a></span></dt><dt><span class="section"><a href="#launching-wsgen">4.2. Launching <span class="command"><strong>wsgen</strong></span></a></span></dt><dt><span class="section"><a href="#running-wsgen-on-jdk-6">4.3. Running <span class="command"><strong>wsgen</strong></span> on JDK 6</a></span></dt><dt><span class="section"><a href="#wsgen-syntax">4.4. <span class="command"><strong>wsgen</strong></span> Syntax</a></span></dt><dt><span class="section"><a href="#wsgen-example">4.5. <span class="command"><strong>wsgen</strong></span> Example</a></span></dt></dl></dd><dt><span class="section"><a href="#tools-wsgen-ant-task">5. <span class="command"><strong>wsgen</strong></span> Ant Task</a></span></dt><dd><dl><dt><span class="section"><a href="#wsgen-task-overview">5.1. <span class="command"><strong>wsgen</strong></span> Task Overview</a></span></dt><dt><span class="section"><a href="#wsgen-task-attributes">5.2. <span class="command"><strong>wsgen</strong></span> Task Attributes</a></span></dt><dt><span class="section"><a href="#running-wsgen-task-on-jdk-6">5.3. Running <span class="command"><strong>wsgen</strong></span> Task on JDK 6</a></span></dt><dt><span class="section"><a href="#wsgen-task-example">5.4. <span class="command"><strong>wsgen</strong></span> Task Example</a></span></dt></dl></dd><dt><span class="section"><a href="#tools-apt">6. <span class="command"><strong>apt</strong></span></a></span></dt><dd><dl><dt><span class="section"><a href="#section-8324588054404016">6.1. <span class="command"><strong>apt</strong></span></a></span></dt><dt><span class="section"><a href="#running-apt-on-jdk-6">6.2. Running <span class="command"><strong>apt</strong></span> on JDK 6</a></span></dt><dt><span class="section"><a href="#moztocid408933">6.3. <span class="command"><strong>apt</strong></span> Syntax</a></span></dt></dl></dd><dt><span class="section"><a href="#tools-apt-ant-task">7. <span class="command"><strong>apt</strong></span> Ant Task</a></span></dt><dd><dl><dt><span class="section"><a href="#d0e9860">7.1. <span class="command"><strong>apt</strong></span> Task Overview</a></span></dt><dt><span class="section"><a href="#d0e9870">7.2. <span class="command"><strong>apt</strong></span> Task Attributes</a></span></dt><dt><span class="section"><a href="#running-apt-task-on-jdk-6">7.3. Running <span class="command"><strong>apt</strong></span> Task on JDK 6</a></span></dt><dt><span class="section"><a href="#section-26459256796099617">7.4. <span class="command"><strong>apt</strong></span> Task Examples</a></span></dt></dl></dd></dl></div><div lang="en" class="section" title="1. Overview"><div class="titlepage"><div><div><h2 class="title" style="clear: both" id="tools-overview">1. Overview</h2></div></div></div><div class="orderedlist"><ol class="orderedlist" type="1"><li class="listitem"><p><a class="xref" href="#apttool" title="1.1. apt"><span class="command"><strong>apt</strong></span></a></p></li><li class="listitem"><p><a class="xref" href="#wscompiletool" title="1.2. wsimport"><span class="command"><strong>wsimport</strong></span></a></p></li><li class="listitem"><p><a class="xref" href="#wsdeploytool" title="1.3. wsgen"><span class="command"><strong>wsgen</strong></span></a></p></li><li class="listitem"><p><a class="xref" href="#how" title="1.4. How do I pick a tool?">How do I pick a tool?</a></p></li></ol></div><div class="section" title="1.1. apt"><div class="titlepage"><div><div><h3 class="title" id="apttool">1.1. <span class="command"><strong>apt</strong></span></h3></div></div></div><p>The <span class="command"><strong>apt</strong></span> tool provides a facility for programmatically processing the annotations added to Java by <a class="link" href="http://www.jcp.org/en/jsr/detail?id=175" target="_top">JSR 175</a>, <span class="emphasis"><em>Metadata Facility for the Java</em></span> TM <span class="emphasis"><em>Programming Language</em></span>. In brief, JSR 175 allows programmers to declare new kinds of structured modifiers that can be associated with program elements, fields, methods, classes, etc.</p><p>The <span class="command"><strong>apt</strong></span> tool generates the portable artifacts used in JAX-WS services.</p><p>For more information on this tool please see: <a class="xref" href="#tools-apt" title="6. apt"><span class="command"><strong>apt</strong></span></a>.</p></div><div class="section" title="1.2. wsimport"><div class="titlepage"><div><div><h3 class="title" id="wscompiletool">1.2. <span class="command"><strong>wsimport</strong></span></h3></div></div></div><p>The <span class="command"><strong>wsimport</strong></span> tool generates JAX-WS portable artifacts used in JAX-WS clients and services. The tool reads a WSDL and generates all the required artifacts for web service development, deployment, and invocation.</p><p>For more information on this tool please see: <a class="xref" href="#tools-wsimport" title="2. wsimport"><span class="command"><strong>wsimport</strong></span></a>.</p></div><div class="section" title="1.3. wsgen"><div class="titlepage"><div><div><h3 class="title" id="wsdeploytool">1.3. <span class="command"><strong>wsgen</strong></span></h3></div></div></div><p>The <span class="command"><strong>wsgen</strong></span> tool reads a service endpoint implementation class and generates all of the portable artifacts for a JAX-WS web service..</p><p>For more information on this tool please see: <a class="xref" href="#tools-wsgen" title="4. wsgen"><span class="command"><strong>wsgen</strong></span></a>.</p><div class="section" title="1.3.1. Running on JDK6"><div class="titlepage"><div><div><h4 class="title" id="running-on-jdk6">1.3.1. Running on JDK6</h4></div></div></div><div class="itemizedlist"><ul class="itemizedlist" type="disc"><li class="listitem"><p>Copy <code class="filename">JAXWS_HOME/lib/jaxws-api.jar</code> to <code class="filename">$JDK6_HOME/jre/lib/endorsed</code> directory</p></li><li class="listitem"><p>Copy <code class="filename">JAXWS_HOME/lib/jaxb-api.jar</code> to <code class="filename">$JDK6_HOME/jre/lib/endorsed</code> directory</p></li></ul></div><p>For details see <a class="link" href="http://docs.oracle.com/javase/6/docs/technotes/guides/standards/" target="_top">Endorsed Directory Mechanism</a>. Above, <code class="filename">JAXWS_HOME</code> points to the root directory of the extracted JAX-WS RI bundle. <code class="filename">JDK6_HOME</code> points to JDK 6 installation directory.</p></div></div><div class="section" title="1.4. How do I pick a tool?"><div class="titlepage"><div><div><h3 class="title" id="how">1.4. How do I pick a tool?</h3></div></div></div><p>The following lists the process to create a web service starting from Java sources, classes, and a WSDL file (server side):</p><div class="orderedlist"><ol class="orderedlist" type="1"><li class="listitem"><p>Starting from Java sources: </p><div class="orderedlist"><ol class="orderedlist" type="a"><li class="listitem"><p>Use <span class="command"><strong>apt</strong></span> to generate the artifacts required by the JAX-WS specification.</p></li><li class="listitem"><p>Package the <code class="literal">web.xml</code>, <code class="literal">sun-jaxws.xml</code>, service endpoint interface and implementation class, value types, and generated classes, if any, into a WAR file,</p></li><li class="listitem"><p>Deploy the WAR to a web container.</p></li></ol></div></li><li class="listitem"><p>Starting from Java classes: </p><div class="orderedlist"><ol class="orderedlist" type="a"><li class="listitem"><p>Use <span class="command"><strong>wsgen</strong></span> to generate portable artifacts.</p></li><li class="listitem"><p>Package the <code class="literal">web.xml</code>, <code class="literal">sun-jaxws.xml</code>, service endpoint interface and implementation class, value types, and generated classes, if any, into a WAR file,</p></li><li class="listitem"><p>Deploy the WAR to a web container.</p></li></ol></div></li><li class="listitem"><p>Starting from a WSDL file: </p><div class="orderedlist"><ol class="orderedlist" type="a"><li class="listitem"><p>Use <span class="command"><strong>wsimport</strong></span> to generate portable artifacts.</p></li><li class="listitem"><p>Implement the service endpoint.</p></li><li class="listitem"><p>Package the WSDL file, schema documents, <code class="literal">web.xml</code>, <code class="literal">sun-jaxws.xml</code>, service endpoint interface and implementation class, value types, and generated classes, if any, into a WAR file.</p></li><li class="listitem"><p>Deploy the WAR to a web container.</p></li></ol></div></li></ol></div><p>The following lists the process to invoke a web service (client side):</p><div class="orderedlist"><ol class="orderedlist" type="1"><li class="listitem"><p>Starting from deployed web service's WSDL </p><div class="orderedlist"><ol class="orderedlist" type="a"><li class="listitem"><p>Use <span class="command"><strong>wsimport</strong></span> to generate the client-side artifacts.</p></li><li class="listitem"><p>Implement the client to invoke the web service.</p></li></ol></div></li></ol></div></div></div><div lang="en" class="section" title="2. wsimport"><div class="titlepage"><div><div><h2 class="title" style="clear: both" id="tools-wsimport">2. <span class="command"><strong>wsimport</strong></span></h2></div></div></div><div class="section" title="2.1. wsimport Overview"><div class="titlepage"><div><div><h3 class="title" id="wsimport-overview">2.1. <span class="command"><strong>wsimport</strong></span> Overview</h3></div></div></div><p>The <span class="command"><strong>wsimport</strong></span> tool generates JAX-WS portable artifacts, such as:</p><div class="itemizedlist"><ul class="itemizedlist" type="disc"><li class="listitem"><p>Service Endpoint Interface (SEI)</p></li><li class="listitem"><p>Service</p></li><li class="listitem"><p>Exception class mapped from <code class="literal">wsdl:fault</code> (if any)</p></li><li class="listitem"><p>Async Reponse Bean derived from response <code class="literal">wsdl:message</code> (if any)</p></li><li class="listitem"><p>JAXB generated value types (mapped java classes from schema types)</p></li></ul></div><p>These artifacts can be packaged in a WAR file with the WSDL and schema documents along with the endpoint implementation to be deployed. JAX-WS RI 2.2.7 also provides a <a class="xref" href="#tools-wsimport-ant-task" title="3. wsimport Ant Task"><span class="command"><strong>wsimport</strong></span> Ant Task</a>.</p></div><div class="section" title="2.2. Launching wsimport"><div class="titlepage"><div><div><h3 class="title" id="launching-wsimport">2.2. Launching <span class="command"><strong>wsimport</strong></span></h3></div></div></div><div class="itemizedlist"><ul class="itemizedlist" type="disc"><li class="listitem"><p><span class="bold"><strong>Solaris/Linux</strong></span> </p><div class="itemizedlist"><ul class="itemizedlist" type="circle"><li class="listitem"><pre class="programlisting">JAXWS_HOME/bin/wsimport.sh -help</pre></li></ul></div></li><li class="listitem"><p><span class="bold"><strong>Windows</strong></span> </p><div class="itemizedlist"><ul class="itemizedlist" type="circle"><li class="listitem"><pre class="programlisting">JAXWS_HOME\bin\wsimport.bat -help</pre></li></ul></div></li></ul></div></div><div class="section" title="2.3. Running wsimport on JDK 6"><div class="titlepage"><div><div><h3 class="title" id="running-wsimport-on-jdk-6">2.3. Running <span class="command"><strong>wsimport</strong></span> on JDK 6</h3></div></div></div><p>To run on JDK 6 follow these <a class="xref" href="#running-on-jdk6" title="1.3.1. Running on JDK6">Running on JDK6</a>.</p></div><div class="section" title="2.4. wsimport Syntax"><div class="titlepage"><div><div><h3 class="title" id="wsimport-syntax">2.4. <span class="command"><strong>wsimport</strong></span> Syntax</h3></div></div></div><div class="cmdsynopsis"><p><code class="command">wsimport</code> [OPTION]... <WSDL></p></div><p>The following table lists the <span class="command"><strong>wsimport</strong></span> options:</p><div class="informaltable"><table border="1"><colgroup><col width="50%"><col width="50%"></colgroup><thead><tr><th>Option</th><th>Description</th></tr></thead><tbody><tr><td><code class="literal">-d <directory></code></td><td>Specify where to place generated output files.</td></tr><tr><td><code class="literal">-b <path></code></td><td>Specify external JAX-WS or JAXB binding files or additional schema files (Each <code class="literal"><file></code> must have its own <code class="option">-b</code>).</td></tr><tr><td><code class="literal">-B <jaxbOption></code></td><td>Pass this option to JAXB schema compiler.</td></tr><tr><td><code class="literal">-catalog</code></td><td>Specify catalog file to resolve external entity references, it supports TR9401, XCatalog, and OASIS XML Catalog format. Please read the documentation of <a class="xref" href="#users-guide-catalog" title="14. Catalog">Catalog</a> and see catalog sample.</td></tr><tr><td><code class="literal">-extension</code></td><td>Allow vendor extensions (functionality not specified by the specification). Use of extensions may result in applications that are not portable or may not interoperate with other implementations.</td></tr><tr><td><code class="literal">-help</code></td><td>Display help.</td></tr><tr><td><code class="literal">-httpproxy:<host>:<port></code></td><td>Specify an HTTP proxy server (port defaults to 8080).</td></tr><tr><td><code class="literal">-keep</code></td><td>Keep generated source code files. It is enabled when <code class="option">-s</code> option.</td></tr><tr><td><code class="literal">-p <pkg></code></td><td>Specifying a target package via this command-line option, overrides any wsdl and schema binding customization for package name and the default package name algorithm defined in the specification.</td></tr><tr><td><code class="literal">-s <directory></code></td><td>Specify where to place generated source code files. keep is turned on with this option.</td></tr><tr><td><code class="literal">-encoding <encoding></code></td><td>Set the encoding name for generated sources, such as EUC-JP or UTF-8. If <code class="literal">-encoding</code> is not specified, the platform default encoding is used.</td></tr><tr><td><code class="literal">-verbose</code></td><td>Output messages about what the compiler is doing.</td></tr><tr><td><code class="literal">-version</code></td><td>Print version information.</td></tr><tr><td><code class="literal">-fullversion</code></td><td>Print full version information.</td></tr><tr><td><code class="literal">-clientjar <jarfile></code></td><td>Creates the jar file of the generated artifacts along with the WSDL metadata required for invoking the web service.</td></tr><tr><td><code class="literal">-wsdllocation <location></code></td><td><code class="literal">@WebServiceClient.wsdlLocation</code> value.</td></tr><tr><td><code class="literal">-target <version></code></td><td>Generate code as per the given JAX-WS specification version. For example, "<code class="literal">-target 2.0</code>" generates compliant code for JAX-WS 2.0 spec. Default value is 2.2.</td></tr><tr><td><code class="literal">-quiet</code></td><td>Suppress <span class="command"><strong>wsimport</strong></span> output.</td></tr><tr><td><code class="literal">-XadditionalHeaders</code></td><td>Map the headers not bound to request or response message to Java method parameters.</td></tr><tr><td><code class="literal">-Xauthfile</code></td><td>File to carry authorization information in the format <code class="uri">http://username:password@example.org/stock?wsdl</code>. Default value is <code class="filename">$HOME/.metro/auth</code></td></tr><tr><td><code class="literal">-Xdebug</code></td><td>Print debug information.</td></tr><tr><td><code class="literal">-XdisableAuthenticator</code></td><td>Disables Authenticator used by JAX-WS RI, <code class="literal">-Xauthfile</code> option will be ignored if <code class="literal">-XdisableAuthenticator</code> is set.</td></tr><tr><td><code class="literal">-Xno-addressing-databinding</code></td><td>Enable binding of W3C <code class="literal">EndpointReferenceType</code> to Java.</td></tr><tr><td><code class="literal">-Xnocompile</code></td><td>Do not compile generated Java files.</td></tr><tr><td><code class="literal">-XdisableSSLHostnameVerification</code></td><td>Disbales the SSL Hostname verification while fetching the wsdls.</td></tr></tbody></table></div><p>Multiple JAX-WS and JAXB binding files can be specified using <code class="option">-b</code> option and they can be used to customize various things like package names, bean names, etc. More information on JAX-WS and JAXB binding files can be found in the <a class="xref" href="#users-guide-wsdl-customization" title="9. WSDL Customization">WSDL Customization</a>.</p></div><div class="section" title="2.5. wsimport Example"><div class="titlepage"><div><div><h3 class="title" id="wsimport-example">2.5. <span class="command"><strong>wsimport</strong></span> Example</h3></div></div></div><div class="informalexample"><pre class="programlisting">wsimport -p stockquote http://stockquote.xyz/quote?wsdl</pre></div><p>This will generate the Java artifacts and compile them by importing the <a class="link" href="http://stockquote.org/quote?wsdl" target="_top">http://stockquote.xyz/quote?wsdl</a>.</p></div></div><div lang="en" class="section" title="3. wsimport Ant Task"><div class="titlepage"><div><div><h2 class="title" style="clear: both" id="tools-wsimport-ant-task">3. <span class="command"><strong>wsimport</strong></span> Ant Task</h2></div></div></div><div class="section" title="3.1. wsimport Task Overview"><div class="titlepage"><div><div><h3 class="title" id="wsimport-task-overview">3.1. <span class="command"><strong>wsimport</strong></span> Task Overview</h3></div></div></div><p>The <span class="command"><strong>wsimport</strong></span> generates JAX-WS portable artifacts, such as:</p><div class="itemizedlist"><ul class="itemizedlist" type="disc"><li class="listitem"><p>Service Endpoint Interface (SEI)</p></li><li class="listitem"><p>Service</p></li><li class="listitem"><p>Exception class mapped from <code class="literal">wsdl:fault</code> (if any)</p></li><li class="listitem"><p>Async Reponse Bean derived from response <code class="literal">wsdl:message</code> (if any)</p></li><li class="listitem"><p>JAXB generated value types (mapped java classes from schema types)</p></li></ul></div></div><div class="section" title="3.2. Using wsimport Task"><div class="titlepage"><div><div><h3 class="title" id="using-wsimport-task">3.2. Using <span class="command"><strong>wsimport</strong></span> Task</h3></div></div></div><p>To use this <span class="command"><strong>wsimport</strong></span> task, a <code class="literal"><taskdef></code> element needs to be added to the project as given below:</p><div class="informalexample"><pre class="programlisting"><span class="ReservedWord"><taskdef</span> <span class="Identifier">name</span>=<span class="String">"wsimport"</span> <span class="Identifier">classname</span>=<span class="String">"com.sun.tools.ws.ant.WsImport"</span><span class="ReservedWord">></span> <span class="ReservedWord"><classpath</span> <span class="Identifier">path</span>=<span class="String">"jaxws.classpath"</span><span class="ReservedWord">/></span> <span class="ReservedWord"></taskdef></span></pre></div><p>where <code class="literal">jaxws.classpath</code> is a reference to a <a class="link" href="http://ant.apache.org/manual/using.html#path" target="_top">path-like structure</a>, defined elsewhere in the build environment, and contains the list of classes required by the JAX-WS tools.</p><div class="informalexample"><pre class="programlisting"><span class="ReservedWord"><wsimport</span> <span class="Identifier">wsdl</span>=<span class="String">"..."</span> <span class="Identifier">destdir</span>=<span class="String">"directory for generated class files"</span> <span class="Identifier">sourcedestdir</span>=<span class="String">"directory for generated source files"</span> <span class="Identifier">keep</span>=<span class="String">"true|false"</span> <span class="Identifier">encoding</span>=<span class="String">"..."</span> <span class="Identifier">extension</span>=<span class="String">"true|false"</span> <span class="Identifier">verbose</span>=<span class="String">"true|false"</span> <span class="Identifier">wsdlLocation</span>=<span class="String">"..."</span> <span class="Identifier">clientJar</span>=<span class="String">"jar file"</span> <span class="Identifier">catalog</span>=<span class="String">"catalog file"</span> <span class="Identifier">package</span>=<span class="String">"package name"</span> <span class="Identifier">target</span>=<span class="String">"target release"</span> <span class="Identifier">binding</span>=<span class="String">"..."</span> <span class="Identifier">quiet</span>=<span class="String">"true|false"</span> <span class="Identifier">xadditionalHeaders</span>=<span class="String">"true|false"</span> <span class="Identifier">xauthfile</span>=<span class="String">"authorization file"</span> <span class="Identifier">xdisableAuthenticator</span>=<span class="String">"true|false"</span> <span class="Identifier">xdebug</span>=<span class="String">"true|false"</span> <span class="Identifier">xNoAddressingDatabinding</span>=<span class="String">"true|false"</span> <span class="Identifier">xnocompile</span>=<span class="String">"true|false"</span> <span class="Identifier"><binding</span> <span class="Identifier">dir</span>=<span class="String">"..."</span> <span class="Identifier">includes</span>=<span class="String">"..."</span><span class="ReservedWord"> /></span> <span class="ReservedWord"><arg</span> <span class="Identifier">value</span>=<span class="String">"..."</span><span class="ReservedWord">/></span> <span class="ReservedWord"><xjcarg</span> <span class="Identifier">value</span>=<span class="String">"..."</span><span class="ReservedWord">/></span> <span class="ReservedWord"><xmlcatalog</span> <span class="Identifier">refid</span>=<span class="String">"another catalog file"</span><span class="ReservedWord">/></span> <span class="ReservedWord"></wsimport></span></pre></div><div class="section" title="3.2.1. Environment Variables"><div class="titlepage"><div><div><h4 class="title" id="section-8164488302388055">3.2.1. Environment Variables</h4></div></div></div><div class="itemizedlist"><ul class="itemizedlist" type="disc"><li class="listitem"><p><a class="link" href="http://wiki.apache.org/ant/TheElementsOfAntStyle" target="_top">ANT_OPTS</a> - command-line arguments that should be passed to the JVM. For example, you can define system properties or set the maximum Java heap size here.</p></li></ul></div></div><div class="section" title="3.2.2. Parameter Attributes"><div class="titlepage"><div><div><h4 class="title" id="section-925990378001543">3.2.2. Parameter Attributes</h4></div></div></div><p><span class="command"><strong>wsimport</strong></span> supports the following parameter attributes.</p><div class="informaltable"><table border="1"><colgroup><col width="25%"><col width="25%"><col width="25%"><col width="25%"></colgroup><thead><tr><th><span class="bold"><strong>Attribute</strong></span></th><th><span class="bold"><strong>Description</strong></span></th><th><span class="bold"><strong>Required</strong></span></th><th><span class="bold"><strong>Command line</strong></span></th></tr></thead><tbody><tr><td><code class="literal">wsdl</code></td><td>WSDL file.</td><td>Yes.</td><td>WSDL location</td></tr><tr><td><code class="literal">destdir</code></td><td>Specify where to place output generated classes.</td><td>No. Defaults to current working directory.</td><td><code class="literal">-d</code></td></tr><tr><td><code class="literal">sourcedestdir</code></td><td>Specify where to place generated source code files, keep is turned on with this option.</td><td>No. Defaults to current working directory.</td><td><code class="literal">-s</code></td></tr><tr><td><code class="literal">encoding</code></td><td>Set the encoding name for generated sources, such as UTF-8.</td><td>No. Defaults to platform default.</td><td><code class="literal">-encoding</code></td></tr><tr><td><code class="literal">keep</code></td><td>Keep generated source code files, turned on with <code class="literal">sourcedestdir</code> option.</td><td>No. Defaults to false.</td><td><code class="literal">-keep</code></td></tr><tr><td><code class="literal">verbose</code></td><td>Output JAX-WS RI version and messages about what the compiler is doing</td><td>No. Defaults to false.</td><td><code class="literal">-verbose.</code></td></tr><tr><td><code class="literal">binding</code></td><td>Specify external JAX-WS or JAXB binding files or additional schema files (Each <code class="literal"><file></code> must have its own <code class="option">-b</code>).</td><td>No. No defaults.</td><td><code class="literal">-b</code></td></tr><tr><td><code class="literal">extension</code></td><td>allow vendor extensions (functionality not specified by the specification). Use of extensions may result in applications that are not portable or may not interoperate with other implementations.</td><td>No. Defaults to false.</td><td><code class="literal">-extension</code></td></tr><tr><td><code class="literal">wsdllocation</code></td><td>The wsdl URI passed thru this option will be used to set the value of <code class="literal">@WebService.wsdlLocation</code> and <code class="literal">@WebServiceClient.wsdlLocation</code> annotation elements on the generated SEI and Service interface.</td><td>No. Defaults to the wsdl URL passed to wsdl attribute.</td><td><code class="literal">-wsdllocation</code></td></tr><tr><td><code class="literal">clientJar</code></td><td>Creates the jar file of the generated artifacts along with the WSDL metadata required for invoking the web service.</td><td>No.</td><td><code class="literal">-clientJar</code></td></tr><tr><td><code class="literal">catalog</code></td><td>Specify catalog file to resolve external entity references, it supports TR9401, XCatalog, and OASIS XML Catalog format. Additionally, ant xmlcatalog type can be used to resolve entities, see <span class="bold"><strong>catalog</strong></span> sample and <a class="xref" href="#users-guide-catalog" title="14. Catalog">Catalog</a>.</td><td>No. No defaults.</td><td><code class="literal">-catalog</code></td></tr><tr><td><code class="literal">package</code></td><td>Specifies the target package.</td><td>No. It default to the WSDL/Schema targetNamespace to package mapping as defined by the JAXB 2.1 spec.</td><td><code class="literal">-p</code></td></tr><tr><td><code class="literal">target</code></td><td>Generate code as per the given JAXWS specification version. For example, 2.0 value generates compliant code for JAXWS 2.0 spec.</td><td>No. Defaults to 2.2.</td><td><code class="literal">-target</code></td></tr><tr><td><code class="literal">quiet</code></td><td>Suppress <span class="command"><strong>wsimport</strong></span> output.</td><td>No. Defaults to false.</td><td><code class="literal">-quiet</code></td></tr><tr><td><code class="literal">xadditionalHeaders</code></td><td>Map headers not bound to request or response message to Java method parameters.</td><td>No. Defaults to false.</td><td><code class="literal">-XadditionalHeaders</code></td></tr><tr><td><code class="literal">xauthfile</code></td><td>File to carry authorization information in the format <code class="uri">http://username:password@example.org/stock?wsdl</code>.</td><td>No. Defaults to <code class="filename">$HOME/.metro/auth</code>.</td><td><code class="literal">-Xauthfile</code></td></tr><tr><td><code class="literal">xdebug</code></td><td>Print debug information.</td><td>No. Defaults to false.</td><td><code class="literal">-Xdebug</code></td></tr><tr><td><code class="literal">xdisableAuthenticator</code></td><td>Disables Authenticator used by JAX-WS RI, <code class="literal">-Xauthfile</code> option will be ignored if <code class="literal">-XdisableAuthenticator</code> is set.</td><td>No. Defaults to false.</td><td><code class="literal">-XdisableAuthenticator</code></td></tr><tr><td><code class="literal">xNoAddressingDatabinding</code></td><td>Enable binding of W3C EndpointReferenceType to Java.</td><td>No. Defaults to false.</td><td><code class="literal">-Xno-addressing-databinding</code></td></tr><tr><td><code class="literal">xnocompile</code></td><td>Do not compile generated Java files.</td><td>No. Defaults to false.</td><td><code class="literal">-Xnocompile</code></td></tr></tbody></table></div></div><div class="section" title="3.2.3. Nested Elements"><div class="titlepage"><div><div><h4 class="title" id="section-5178368839933347">3.2.3. Nested Elements</h4></div></div></div><p><span class="command"><strong>wsimport</strong></span> supports the following nested element parameters.</p><div class="section" title="3.2.3.1. binding"><div class="titlepage"><div><div><h5 class="title" id="section-507914090467712">3.2.3.1. <code class="literal">binding</code></h5></div></div></div><p>To specify more than one external binding file at the same time, use a nested <code class="literal"><binding></code> element, which has the same syntax as <a class="link" href="http://jakarta.apache.org/ant/manual/CoreTypes/fileset.html" target="_top"><code class="literal"><fileset></code></a>.</p></div><div class="section" title="3.2.3.2. arg"><div class="titlepage"><div><div><h5 class="title" id="section-147957817602781">3.2.3.2. <code class="literal">arg</code></h5></div></div></div><p>Additional command line arguments passed to the <span class="command"><strong>wsimport</strong></span>. For details about the syntax, see <a class="link" href="http://ant.apache.org/manual/using.html#arg" target="_top">the relevant section</a> in the Ant manual. This nested element can be used to specify various options not natively supported in the <span class="command"><strong>wsimport</strong></span> Ant task. For example, currently there is no native support for the following <span class="command"><strong>wsimport</strong></span> command-line options:</p><div class="itemizedlist"><ul class="itemizedlist" type="disc"><li class="listitem"><p><code class="code">-XdisableSSLHostnameVerification</code></p></li></ul></div><p>This nested element can be used to pass the <code class="option">-X</code> command-line options directly like "-XadditionalHeaders". To use any of these features from the <span class="command"><strong>wsimport</strong></span> Ant task, you must specify the appropriate nested <code class="literal"><arg></code> elements.</p></div><div class="section" title="3.2.3.3. xjcarg"><div class="titlepage"><div><div><h5 class="title" id="section-459991967418923">3.2.3.3. <code class="literal">xjcarg</code></h5></div></div></div><p>The usage is similar to <code class="literal"><arg></code> nested element, except that these arguments are directly passed to the XJC tool (JAXB Schema Compiler), which will be used for compiling the schema referenced in the wsdl. For details about the syntax, see <a class="link" href="http://ant.apache.org/manual/using.html#arg" target="_top">the relevant section</a> in the Ant manual.</p></div><div class="section" title="3.2.3.4. xmlcatalog"><div class="titlepage"><div><div><h5 class="title" id="section-804917954967609">3.2.3.4. xmlcatalog</h5></div></div></div><p>The <a class="link" href="http://ant.apache.org/manual/CoreTypes/xmlcatalog.html" target="_top">xmlcatalog</a> element is used to resolve entities when parsing schema documents.</p></div></div></div><div class="section" title="3.3. Running wsimport Task on JDK 6"><div class="titlepage"><div><div><h3 class="title" id="running-wsimport-task-on-jdk-6">3.3. Running <span class="command"><strong>wsimport</strong></span> Task on JDK 6</h3></div></div></div><p><span class="bold"><strong>To run on JDK 6 follow these <a class="xref" href="#running-on-jdk6" title="1.3.1. Running on JDK6">Running on JDK6</a>.</strong></span></p></div><div class="section" title="3.4. wsimport Examples"><div class="titlepage"><div><div><h3 class="title" id="examples">3.4. <span class="command"><strong>wsimport</strong></span> Examples</h3></div></div></div><div class="informalexample"><pre class="programlisting"><span class="ReservedWord"><wsimport</span> <span class="Identifier">destdir</span>=<span class="String">"${build.classes.home}"</span> <span class="Identifier">debug</span>=<span class="String">"true"</span> <span class="Identifier">wsdl</span>=<span class="String">"AddNumbers.wsdl"</span> <span class="Identifier">binding</span>=<span class="String">"custom.xml"</span><span class="ReservedWord">/></span></pre></div><p>The above example generates client-side artifacts for <code class="filename">AddNumbers.wsdl</code>, stores <code class="literal">.class</code> files in the <code class="literal">${build.classes.home}</code> directory using the <code class="filename">custom.xml</code> customization file. The classpath used is <code class="filename">xyz.jar</code> and compiles with debug information on.</p><div class="informalexample"><pre class="programlisting"><span class="ReservedWord"><wsimport</span> <span class="Identifier">keep</span>=<span class="String">"true"</span> <span class="Identifier">sourcedestdir</span>=<span class="String">"${source.dir}"</span> <span class="Identifier">destdir</span>=<span class="String">"${build.classes.home}"</span> <span class="Identifier">extension</span>=<span class="String">"true"</span> <span class="Identifier">wsdl</span>=<span class="String">"AddNumbers.wsdl"</span><span class="ReservedWord">></span> <span class="ReservedWord"><xjcarg</span> <span class="Identifier">value</span>=<span class="String">"-cp"</span><span class="ReservedWord">/></span> <span class="ReservedWord"><xjcarg</span> <span class="Identifier">file</span>=<span class="String">"path/to/fluent-api.jar"</span><span class="ReservedWord"> /></span> <span class="ReservedWord"><xjcarg</span> <span class="Identifier">value</span>=<span class="String">"-Xfluent-api"</span><span class="ReservedWord">/></span> <span class="ReservedWord"></wsimport></span></pre></div><p>The above example shows how to generates artifacts for <code class="literal">AddNumbers.wsdl</code> while passing options to JAXB <span class="command"><strong>xjc</strong></span> tool for XML Schema to Java compilation using your JAXB plugin. Note extension attribute which is set to <code class="literal">true</code>. You need to set this to use JAXB plugins.</p><p>Multiple JAX-WS and JAXB binding files can be specified using <code class="option">-b</code> option and they can be used to customize various things like package names, bean names, etc. More information on JAX-WS and JAXB binding files can be found in the <a class="xref" href="#users-guide-wsdl-customization" title="9. WSDL Customization">WSDL Customization</a>.</p></div></div><div lang="en" class="section" title="4. wsgen"><div class="titlepage"><div><div><h2 class="title" style="clear: both" id="tools-wsgen">4. <span class="command"><strong>wsgen</strong></span></h2></div></div></div><div class="section" title="4.1. wsgen Overview"><div class="titlepage"><div><div><h3 class="title" id="wsgen-overview">4.1. <span class="command"><strong>wsgen</strong></span> Overview</h3></div></div></div><p>The <span class="command"><strong>wsgen</strong></span> tool generates JAX-WS portable artifacts used in JAX-WS web services. The tool reads a web service endpoint class and generates all the required artifacts for web service deployment, and invocation. JAX-WS RI 2.2.7 also provides a <a class="xref" href="#tools-wsgen-ant-task" title="5. wsgen Ant Task"><span class="command"><strong>wsgen</strong></span> Ant Task</a>.</p></div><div class="section" title="4.2. Launching wsgen"><div class="titlepage"><div><div><h3 class="title" id="launching-wsgen">4.2. Launching <span class="command"><strong>wsgen</strong></span></h3></div></div></div><div class="itemizedlist"><ul class="itemizedlist" type="disc"><li class="listitem"><p><span class="bold"><strong>Solaris/Linux</strong></span> </p><div class="itemizedlist"><ul class="itemizedlist" type="circle"><li class="listitem"><pre class="programlisting">JAXWS_HOME/bin/wsgen.sh -help</pre></li></ul></div></li><li class="listitem"><p><span class="bold"><strong>Windows</strong></span> </p><div class="itemizedlist"><ul class="itemizedlist" type="circle"><li class="listitem"><pre class="programlisting">JAXWS_HOME\bin\wsgen.bat -help</pre></li></ul></div></li></ul></div></div><div class="section" title="4.3. Running wsgen on JDK 6"><div class="titlepage"><div><div><h3 class="title" id="running-wsgen-on-jdk-6">4.3. Running <span class="command"><strong>wsgen</strong></span> on JDK 6</h3></div></div></div><p>To run on JDK 6 follow these <a class="xref" href="#running-on-jdk6" title="1.3.1. Running on JDK6">Running on JDK6</a>.</p></div><div class="section" title="4.4. wsgen Syntax"><div class="titlepage"><div><div><h3 class="title" id="wsgen-syntax">4.4. <span class="command"><strong>wsgen</strong></span> Syntax</h3></div></div></div><div class="cmdsynopsis"><p><code class="command">wsgen</code> [OPTION]... <SEI></p></div><p>The following table lists the <span class="command"><strong>wsgen</strong></span> options:</p><div class="informaltable"><table border="1"><colgroup><col width="50%"><col width="50%"></colgroup><thead><tr><th>Option</th><th>Description</th></tr></thead><tbody><tr><td><code class="literal">-classpath <path></code></td><td>Specify where to find input class files.</td></tr><tr><td><code class="literal">-cp <path></code></td><td>Same as <code class="literal">-classpath <path></code>.</td></tr><tr><td><code class="literal">-d <directory></code></td><td>Specify where to place generated output files.</td></tr><tr><td><code class="literal">-extension</code></td><td>Allow vendor extensions (functionality not specified by the specification). Use of extensions may result in applications that are not portable or may not interoperate with other implementations.</td></tr><tr><td><code class="literal">-help</code></td><td>Display help.</td></tr><tr><td><code class="literal">-keep</code></td><td>Keep generated files.</td></tr><tr><td><code class="literal">-r <directory></code></td><td>Used only in conjunction with the -<code class="option">wsdl</code> option. Specify where to place generated resource files such as WSDLs.</td></tr><tr><td><code class="literal">-s <directory></code></td><td>Specify where to place generated source files.</td></tr><tr><td><code class="literal">-encoding <encoding></code></td><td>Set the encoding name for generated sources, such as EUC-JP or UTF-8. If <code class="option">-encoding</code> is not specified, the platform default encoding is used.</td></tr><tr><td><code class="literal">-verbose</code></td><td>Output messages about what the compiler is doing.</td></tr><tr><td><code class="literal">-version</code></td><td>Print version information. Use of this option will ONLY print version information. Normal processing will not occur.</td></tr><tr><td><code class="literal">-fullversion</code></td><td>Print full version information. Use of this option will ONLY print version information. Normal processing will not occur.</td></tr><tr><td><code class="literal">-wsdl[:protocol]</code></td><td>By default <span class="command"><strong>wsgen</strong></span> does not generate a WSDL file. This flag is optional and will cause <span class="command"><strong>wsgen</strong></span> to generate a WSDL file and is usually only used so that the developer can look at the WSDL before the endpoint is deploy. The <code class="literal">protocol</code> is optional and is used to specify what protocol should be used in the <code class="literal">wsdl:binding</code>. Valid protocols include: <code class="literal">soap1.1</code> and <code class="literal">Xsoap1.2</code>. The default is <code class="literal">soap1.1</code>. <code class="literal">Xsoap1.2</code> is not standard and can only be used in conjunction with the <code class="option">-extension</code> option.</td></tr><tr><td><code class="literal">-servicename <name></code></td><td><p>Used only in conjunction with the <code class="option">-wsdl</code> option. Used to specify a particular <code class="literal">wsdl:service</code> name to be generated in the WSDL. Example:</p><pre class="programlisting">-servicename "{http://mynamespace/}MyService"</pre></td></tr><tr><td><code class="literal">-portname <name></code></td><td><p>Used only in conjunction with the <code class="option">-wsdl</code> option. Used to specify a particular <code class="literal">wsdl:port</code> name to be generated in the WSDL. Example:</p><pre class="programlisting">-portname "{http://mynamespace/}MyPort"</pre></td></tr><tr><td><code class="literal">-inlineSchemas</code></td><td>Used to inline schemas in a generated wsdl. Must be used in conjunction with the <code class="option">-wsdl</code> option.</td></tr></tbody></table></div></div><div class="section" title="4.5. wsgen Example"><div class="titlepage"><div><div><h3 class="title" id="wsgen-example">4.5. <span class="command"><strong>wsgen</strong></span> Example</h3></div></div></div><pre class="programlisting">wsgen -d stock -cp myclasspath stock.StockService</pre><p>This will generate the wrapper classes needed for <code class="literal">StockService</code> annotated with <code class="literal">@WebService</code> annotation inside the <code class="filename">stock</code> directory.</p><pre class="programlisting">wsgen -wsdl -d stock -cp myclasspath stock.StockService</pre><p>This will generate a SOAP 1.1 WSDL and schema for your Java class <code class="literal">stock.StockService</code> annotated with <code class="literal">@WebService</code> annotation.</p><pre class="programlisting">wsgen -wsdl:Xsoap1.2 -d stock -cp myclasspath stock.StockService</pre><p>Will generate a SOAP 1.2 WSDL.</p><div class="note" title="Note" style="margin-left: 0.5in; margin-right: 0.5in;"><h3 class="title">Note</h3><p>You don't have to generate WSDL at the development time as JAX-WS runtime will automatically generate a WSDL for you when you deploy your service.</p></div></div></div><div lang="en" class="section" title="5. wsgen Ant Task"><div class="titlepage"><div><div><h2 class="title" style="clear: both" id="tools-wsgen-ant-task">5. <span class="command"><strong>wsgen</strong></span> Ant Task</h2></div></div></div><div class="section" title="5.1. wsgen Task Overview"><div class="titlepage"><div><div><h3 class="title" id="wsgen-task-overview">5.1. <span class="command"><strong>wsgen</strong></span> Task Overview</h3></div></div></div><p><code class="literal">wsgen</code> generates JAX-WS portable artifacts used in JAX-WS web services. The tool reads a web service endpoint class and generates all the required artifacts for web service deployment, and invocation.</p></div><div class="section" title="5.2. wsgen Task Attributes"><div class="titlepage"><div><div><h3 class="title" id="wsgen-task-attributes">5.2. <span class="command"><strong>wsgen</strong></span> Task Attributes</h3></div></div></div><p>The attributes and elements supported by the Ant task are listed below:</p><div class="informalexample"><pre class="programlisting"><span class="ReservedWord"><wsgen</span> <span class="Identifier">sei</span>=<span class="String">"..."</span> <span class="Identifier">destdir</span>=<span class="String">"directory for generated class files"</span> <span class="Identifier">classpath</span>=<span class="String">"classpath"</span> <span class="Identifier">|</span> <span class="Identifier">cp</span>=<span class="String">"classpath"</span> <span class="Identifier">resourcedestdir</span>=<span class="String">"directory for generated resource files such as WSDLs"</span> <span class="Identifier">sourcedestdir</span>=<span class="String">"directory for generated source files"</span> <span class="Identifier">keep</span>=<span class="String">"true|false"</span> <span class="Identifier">encoding</span>=<span class="String">"..."</span> <span class="Identifier">verbose</span>=<span class="String">"true|false"</span> <span class="Identifier">genwsdl</span>=<span class="String">"true|false"</span> <span class="Identifier">protocol</span>=<span class="String">"soap1.1|Xsoap1.2"</span> <span class="Identifier">servicename</span>=<span class="String">"..."</span> <span class="Identifier">portname</span>=<span class="String">"..."</span><span class="ReservedWord">></span> extension="true|false" inlineSchemas="true|false" <span class="ReservedWord"><classpath</span> <span class="Identifier">refid</span>=<span class="String">"..."</span><span class="ReservedWord">/></span> <span class="ReservedWord"></wsgen></span></pre></div><div class="informaltable"><table border="1"><colgroup><col width="33%"><col width="33%"><col width="34%"></colgroup><thead><tr><th><span class="bold"><strong>Attribute</strong></span></th><th><span class="bold"><strong>Description</strong></span></th><th><span class="bold"><strong>Command line</strong></span></th></tr></thead><tbody><tr><td><code class="literal">sei</code></td><td>Name of the service endpoint implementation class.</td><td>SEI</td></tr><tr><td><code class="literal">destdir</code></td><td>Specify where to place output generated classes.</td><td><code class="literal">-d</code></td></tr><tr><td><code class="literal">classpath</code></td><td>Specify where to find input class files.</td><td><code class="literal">-classpath</code></td></tr><tr><td><code class="literal">cp</code></td><td>Same as <code class="literal">-classpath</code>.</td><td><code class="literal">-cp</code></td></tr><tr><td><code class="literal">resourcedestdir</code></td><td>Used only in conjunction with the -wsdl option. Specify where to place generated resource files such as WSDLs.</td><td><code class="literal">-r</code></td></tr><tr><td><code class="literal">sourcedestdir</code></td><td>Specify where to place generated source files.</td><td><code class="literal">-s</code></td></tr><tr><td><code class="literal">encoding</code></td><td>Set the encoding name for generated sources, such as UTF-8.</td><td><code class="literal">-encoding</code></td></tr><tr><td><code class="literal">keep</code></td><td>Keep generated files.</td><td><code class="literal">-keep</code></td></tr><tr><td><code class="literal">verbose</code></td><td>Output JAX_WS RI version and messages about what the compiler is doing.</td><td><code class="literal">-verbose</code></td></tr><tr><td><code class="literal">genwsdl</code></td><td>Specify that a WSDL file should be generated.</td><td><code class="literal">-wsdl</code></td></tr><tr><td><code class="literal">protocol</code></td><td>Used in conjunction with <code class="literal">genwsdl</code> to specify the protocol to use in the <code class="literal">wsdl:binding</code>. Value values are <code class="literal">"soap1.1"</code> or <code class="literal">"Xsoap1.2"</code>, default is <code class="literal">"soap1.1".</code> <code class="literal">"Xsoap1.2"</code> is not standard and can only be used in conjunction with the -extensions option.</td><td><code class="literal">-wsdl:soap11</code></td></tr><tr><td><code class="literal">servicename</code></td><td><p>Used in conjunction with the genwsdl option. Used to specify a particular <code class="literal">wsdl:service</code> name for the generated WSDL. Example:</p><pre class="programlisting">servicename="{http://mynamespace/}MyService"</pre></td><td><code class="literal">-servicename</code></td></tr><tr><td><code class="literal">portname</code></td><td><p>Used in conjunction with the genwsdl option. Used to specify a particular <code class="literal">wsdl:portname</code> name for the generated WSDL. Example:</p><pre class="programlisting">portname="{http://mynamespace/}MyPort"</pre></td><td><code class="literal">-servicename</code></td></tr><tr><td><code class="literal">extension</code></td><td>Allow vendor extensions (functionality not specified by the specification). Use of extensions may result in applications that are not portable or may not interoperate with other implementations.</td><td><code class="literal">-extension</code></td></tr><tr><td><code class="literal">inlineSchemas</code></td><td>Used to inline schemas in a generated wsdl. Must be used in conjunction with the <code class="literal">wsdl</code> option.</td><td><code class="literal">-inlineSchemas</code></td></tr></tbody></table></div><p>The <code class="literal">classpath</code> attribute is a <a class="link" href="http://ant.apache.org/manual/using.html#path" target="_top">path-like structure</a> and can also be set via nested <code class="literal"><classpath></code> elements. Before this task can be used, a <code class="literal"><taskdef></code> element needs to be added to the project as given below:</p><div class="informalexample"><pre class="programlisting"><span class="ReservedWord"><taskdef</span> <span class="Identifier">name</span>=<span class="String">"wsgen"</span> <span class="Identifier">classname</span>=<span class="String">"com.sun.tools.ws.ant.WsGen"</span><span class="ReservedWord">></span> <span class="ReservedWord"><classpath</span> <span class="Identifier">path</span>=<span class="String">"jaxws.classpath"</span><span class="ReservedWord">/></span> <span class="ReservedWord"></taskdef></span></pre></div><p>where <code class="literal">jaxws.classpath</code> is a reference to a <a class="link" href="http://ant.apache.org/manual/using.html#path" target="_top">path-like structure</a>, defined elsewhere in the build environment, and contains the list of classes required by the JAX-WS tools.</p></div><div class="section" title="5.3. Running wsgen Task on JDK 6"><div class="titlepage"><div><div><h3 class="title" id="running-wsgen-task-on-jdk-6">5.3. Running <span class="command"><strong>wsgen</strong></span> Task on JDK 6</h3></div></div></div><p>To run on JDK 6 follow these <a class="xref" href="#running-on-jdk6" title="1.3.1. Running on JDK6">Running on JDK6</a>.</p></div><div class="section" title="5.4. wsgen Task Example"><div class="titlepage"><div><div><h3 class="title" id="wsgen-task-example">5.4. <span class="command"><strong>wsgen</strong></span> Task Example</h3></div></div></div><div class="informalexample"><pre class="programlisting"><span class="ReservedWord"><wsgen</span> <span class="Identifier">resourcedestdir</span>=<span class="String">"${wsdl.dir}"</span> <span class="Identifier">sei</span>=<span class="String">"fromjava.server.AddNumbersImpl"</span><span class="ReservedWord">></span> <span class="ReservedWord"><classpath</span> <span class="Identifier">refid</span>=<span class="String">"compile.classpath"</span><span class="ReservedWord">/></span> <span class="ReservedWord"></wsgen></span></pre></div></div></div><div lang="en" class="section" title="6. apt"><div class="titlepage"><div><div><h2 class="title" style="clear: both" id="tools-apt">6. <span class="command"><strong>apt</strong></span></h2></div></div></div><div class="section" title="6.1. apt"><div class="titlepage"><div><div><h3 class="title" id="section-8324588054404016">6.1. <span class="command"><strong>apt</strong></span></h3></div></div></div><p>The <span class="command"><strong>apt</strong></span> tool provides a facility for programmatically processing the annotations added to Java by <a class="link" href="http://www.jcp.org/en/jsr/detail?id=175" target="_top">JSR 175</a>, <span class="emphasis"><em>Metadata Facility for the Java</em></span> TM <span class="emphasis"><em>Programming Language</em></span>. In brief, JSR 175 allows programmers to declare new kinds of structured modifiers that can be associated with program elements, fields, methods, classes, etc.</p><p>The <span class="command"><strong>apt</strong></span> tool generates the portable artifacts used in JAX-WS services.</p></div><div class="section" title="6.2. Running apt on JDK 6"><div class="titlepage"><div><div><h3 class="title" id="running-apt-on-jdk-6">6.2. Running <span class="command"><strong>apt</strong></span> on JDK 6</h3></div></div></div><p>To run on JDK 6 follow these <a class="xref" href="#running-on-jdk6" title="1.3.1. Running on JDK6">Running on JDK6</a>.</p></div><div class="section" title="6.3. apt Syntax"><div class="titlepage"><div><div><h3 class="title" id="moztocid408933">6.3. <span class="command"><strong>apt</strong></span> Syntax</h3></div></div></div><div class="cmdsynopsis"><p><code class="command">apt</code> [APT_AND_JAVAC_OPTION]... <SOURCE_FILE>... </p></div><p>The following table lists the <span class="command"><strong>apt</strong></span> options:</p><div class="informaltable"><table border="1"><colgroup><col width="50%"><col width="50%"></colgroup><thead><tr><th>Option</th><th>Description</th></tr></thead><tbody><tr><td><code class="literal">-classpath <path></code></td><td>Specifies where to find user class files and annotation processor factories.</td></tr><tr><td><code class="literal">-cp <path></code></td><td>Same as <code class="literal">-classpath <path></code>.</td></tr><tr><td><code class="literal">-d <path></code></td><td>Specifies where to place processor and <code class="literal">javac</code> generated class files.</td></tr><tr><td><code class="literal">-s <path></code></td><td>Specifies where to place processor generated source files.</td></tr><tr><td><code class="literal">-source <release></code></td><td>Provide source compatibility with the specified release.</td></tr><tr><td><code class="literal">-version</code></td><td>Version information.</td></tr><tr><td><code class="literal">-help</code></td><td>Print a synopsis of standard options; use <span class="command"><strong>javac -help</strong></span> for more options.</td></tr><tr><td><code class="literal">-X</code></td><td>Print a synopsis of non-standard options.</td></tr><tr><td><code class="literal">-J<flag></code></td><td>Pass <code class="literal"><flag></code> directly to the runtime system.</td></tr><tr><td><code class="literal">-A[key[=value]]</code></td><td>Options to pass to annotation processors.</td></tr><tr><td><code class="literal">nocompile</code></td><td>Do not compile source files to class files.</td></tr><tr><td><code class="literal">-print</code></td><td>Print out a textual representation of the specified types.</td></tr><tr><td><code class="literal">-factorypath <path></code></td><td>Specify where to find annotation processor factories.</td></tr><tr><td><code class="literal">-factory <class></code></td><td>Name of <code class="literal">AnnotationProcessorFactory</code> to use; bypasses default discovery process.</td></tr><tr><td><code class="literal">-g</code></td><td>Generate all debugging info.</td></tr><tr><td><code class="literal">-g:none</code></td><td>Generate no debugging info.</td></tr><tr><td><code class="literal">-g:{lines,vars,source}</code></td><td>Generate only some debugging info.</td></tr><tr><td><code class="literal">-nowarn</code></td><td>Generate no warnings.</td></tr><tr><td><code class="literal">-verbose</code></td><td>Output messages about what <span class="command"><strong>apt</strong></span> and <span class="command"><strong>javac</strong></span> are doing.</td></tr><tr><td><code class="literal">-deprecation</code></td><td>Output source locations where deprecated APIs are used.</td></tr><tr><td><code class="literal">-sourcepath <path></code></td><td>Specify where to find input source files.</td></tr><tr><td><code class="literal">-bootclasspath <path></code></td><td>Override location of bootstrap class files.</td></tr><tr><td><code class="literal">-endorseddirs <dirs></code></td><td>Override location of endorsed standards path.</td></tr><tr><td><code class="literal">-encoding <encoding></code></td><td>Specify character encoding used by source files.</td></tr><tr><td><code class="literal">-target <release></code></td><td>Generate class files for a specific virtual machine version.</td></tr></tbody></table></div><p>It is important when using <span class="command"><strong>apt</strong></span> with JAX-WS to specify all of the JAR files in the distributed JAX-WS bundle in the classpath passed to <span class="command"><strong>apt</strong></span>. The <code class="literal">-sourcepath <path></code> option must also be provided so that <span class="command"><strong>apt</strong></span> and the JAX-WS annotation processor can find all types referenced by a web service endpoint implementation class.</p><p>For more information on <span class="command"><strong>apt</strong></span> please refer to the <span class="command"><strong>apt</strong></span> documentation <a class="link" href="http://docs.oracle.com/javase/6/docs/technotes/guides/apt/index.html" target="_top">here</a>.</p></div></div><div lang="en" class="section" title="7. apt Ant Task"><div class="titlepage"><div><div><h2 class="title" style="clear: both" id="tools-apt-ant-task">7. <span class="command"><strong>apt</strong></span> Ant Task</h2></div></div></div><div class="section" title="7.1. apt Task Overview"><div class="titlepage"><div><div><h3 class="title" id="d0e9860">7.1. <span class="command"><strong>apt</strong></span> Task Overview</h3></div></div></div><p>An Ant task for the <span class="command"><strong>apt</strong></span> tool is provided with JAX-WS RI 2.2.7.</p></div><div class="section" title="7.2. apt Task Attributes"><div class="titlepage"><div><div><h3 class="title" id="d0e9870">7.2. <span class="command"><strong>apt</strong></span> Task Attributes</h3></div></div></div><p>The attributes and elements supported by the Ant task are listed below:</p><div class="informalexample"><pre class="programlisting"><span class="ReservedWord"><apt</span> <span class="Identifier">verbose</span>=<span class="String">"true|false"</span> <span class="Identifier">classpath</span>=<span class="String">"classpath"</span> <span class="Identifier">destdir</span>=<span class="String">"directory for generated class files"</span> <span class="Identifier">sourcedestdir</span>=<span class="String">"directory for generated source files"</span> <span class="Identifier">nocompile</span>=<span class="String">"true|false"</span> <span class="Identifier">print</span>=<span class="String">"true|false"</span> <span class="Identifier">factorypath</span>=<span class="String">"<path>"</span> <span class="Identifier">factory</span>=<span class="String">"name of AnnotationProcessorFactory to use"</span> <span class="Identifier">xlistannotationtypes</span>=<span class="String">"true|false"</span> <span class="Identifier">xlistdeclarations</span>=<span class="String">"true|false"</span> <span class="Identifier">xprintaptrounds</span>=<span class="String">"true|false"</span> <span class="Identifier">xprintfactoryinfo</span>=<span class="String">"true|false"</span> <span class="Identifier">xclassesasdecls</span>=<span class="String">"true|false"</span> <span class="Identifier">debug</span>=<span class="String">"true|false"</span> <span class="Identifier">debuglevel</span>=<span class="String">"lines|vars|source"</span> <span class="Identifier">nowarn</span>=<span class="String">"true|false"</span> <span class="Identifier">deprecaption</span>=<span class="String">"true|false"</span> <span class="Identifier">bootclasspath</span>=<span class="String">"<path>"</span> <span class="Identifier">extdirs</span>=<span class="String">"<path>"</span> <span class="Identifier">endorseddirs</span>=<span class="String">"<path>"</span> <span class="Identifier">sourcepath</span>=<span class="String">"<path>"</span> <span class="Identifier">encoding</span>=<span class="String">"specify character encoding used by source files"</span> <span class="Identifier">target</span>=<span class="String">"generate class files for specific virtual machine version"</span><span class="ReservedWord">></span> <span class="ReservedWord"><option</span> <span class="Identifier">key</span>=<span class="String">"keyname"</span> <span class="Identifier">value</span>=<span class="String">"keyvalue"</span><span class="ReservedWord">/></span> <span class="ReservedWord"><source</span> <span class="Identifier">...</span><span class="ReservedWord"> ></span> ... <span class="ReservedWord"></source></span> <span class="ReservedWord"><classpath</span> <span class="Identifier">...</span><span class="ReservedWord"> ></span> ... <span class="ReservedWord"></classpath></span> <span class="ReservedWord"></apt></span></pre></div><div class="informaltable"><table border="1"><colgroup><col width="33%"><col width="33%"><col width="34%"></colgroup><thead><tr><th>Attribute</th><th>Description</th><th>Command line</th></tr></thead><tbody><tr><td><code class="literal">verbose</code></td><td>Output messages about what the compiler is doing.</td><td><code class="literal">-verbose</code></td></tr><tr><td><code class="literal">classpath</code></td><td>Specify where to find user class files and annotation processor factories.</td><td><code class="literal">-classpath</code> or <code class="literal">-cp</code></td></tr><tr><td><code class="literal">destdir</code></td><td>Specify where to place processor and <span class="command"><strong>javac</strong></span> generated class files.</td><td><code class="literal">-d <path></code></td></tr><tr><td><code class="literal">sourcedestdir</code></td><td>Specify where to place processor generated source files.</td><td><code class="literal">-s <path></code></td></tr><tr><td><code class="literal">nocompile</code></td><td>Do not compile source files to class files.</td><td><code class="literal">-nocompile</code></td></tr><tr><td><code class="literal">print</code></td><td>Print out a textual representation of the specified types.</td><td><code class="literal">-print</code></td></tr><tr><td><code class="literal">factorypath</code></td><td>Specify where to find annotation processor factories.</td><td><code class="literal">-factorypath <path></code></td></tr><tr><td><code class="literal">factory</code></td><td>Name of the <code class="literal">AnnotationProcessorFactory</code> to use; bypasses default discovery process.</td><td><code class="literal">-factory <class></code></td></tr><tr><td><code class="literal">xlistannotationtypes</code></td><td>List the found annotation types.</td><td><code class="literal">-xlistannotationtypes</code></td></tr><tr><td><code class="literal">xlistdeclarations</code></td><td>List specified and included declarations.</td><td><code class="literal">-xlistdeclarations</code></td></tr><tr><td><code class="literal">xprintaptrounds</code></td><td>Print information about initial and recursive <span class="command"><strong>apt</strong></span> rounds.</td><td><code class="literal">-xprintaptrounds</code></td></tr><tr><td><code class="literal">xprintfactoryinfo</code></td><td>Print information about which annotations a factory is asked to process.</td><td><code class="literal">-xprintfactoryinfo</code></td></tr><tr><td><code class="literal">xclassesasdecls</code></td><td>Treat both class and source files as declarations to process.</td><td><code class="literal">-xclassesasdecls</code></td></tr><tr><td><code class="literal">debug</code></td><td>Generate all debugging info.</td><td><code class="literal">-g</code></td></tr><tr><td><code class="literal">debuglevel</code></td><td>Debug level: lines, vars, sources.</td><td><code class="literal">-g:{lines,vars,source}</code></td></tr><tr><td><code class="literal">nowarn</code></td><td>Generate no warnings.</td><td><code class="literal">-nowarn</code></td></tr><tr><td><code class="literal">deprecation</code></td><td>Output source locations where deprecated APIs are used.</td><td><code class="literal">-deprecation</code></td></tr><tr><td><code class="literal">bootclasspath</code></td><td>Override location of bootstrap class files.</td><td><code class="literal">-bootclasspath <path></code></td></tr><tr><td><code class="literal">extdirs</code></td><td>Override location of installed extensions.</td><td><code class="literal">-extdirs <dirs></code></td></tr><tr><td><code class="literal">endorseddirs</code></td><td>Override location of endorsed standards path.</td><td><code class="literal">-endorseddirs <dirs></code></td></tr><tr><td><code class="literal">sourcepath</code></td><td>Specify where to find input source files.</td><td><code class="literal">-sourcepath <path></code></td></tr><tr><td><code class="literal">encoding</code></td><td>Specify character encoding used by source files.</td><td><code class="literal">-encoding <encoding></code></td></tr><tr><td><code class="literal">target</code></td><td>Generate class files for a specific virtual machine version.</td><td><code class="literal">-target <release></code></td></tr><tr><td><code class="literal">option</code></td><td>Specify options to pass to annotation processors.</td><td><code class="literal">-Akey=value;</code></td></tr></tbody></table></div><p>The list of source files to be processed are specified via a nested <code class="literal"><source></code> element. That is, a <a class="link" href="http://ant.apache.org/manual/using.html#path" target="_top">path-like structure</a>. The classpath attribute is a <a class="link" href="http://ant.apache.org/manual/using.html#path" target="_top">path-like structure</a> and can also be set via nested <code class="literal"><classpath></code> elements. Before this task can be used, a <code class="literal"><taskdef></code> element needs to be added to the project as given below:</p><div class="informalexample"><pre class="programlisting"><span class="ReservedWord"><taskdef</span> <span class="Identifier">name</span>=<span class="String">"apt"</span> <span class="Identifier">classname</span>=<span class="String">"com.sun.tools.ws.ant.Apt"</span><span class="ReservedWord">></span> <span class="ReservedWord"><classpath</span> <span class="Identifier">refid</span>=<span class="String">"jaxws.classpath"</span><span class="ReservedWord">/></span> <span class="ReservedWord"></taskdef></span></pre></div><p>where <code class="literal">jaxws.classpath</code> is a reference to a <a class="link" href="http://ant.apache.org/manual/using.html#path" target="_top">path-like structure</a>, defined elsewhere in the build environment, and contains the list of classes required by the JAX-WS tools.</p></div><div class="section" title="7.3. Running apt Task on JDK 6"><div class="titlepage"><div><div><h3 class="title" id="running-apt-task-on-jdk-6">7.3. Running <span class="command"><strong>apt</strong></span> Task on JDK 6</h3></div></div></div><p>To run on JDK 6 follow these <a class="xref" href="#running-on-jdk6" title="1.3.1. Running on JDK6">Running on JDK6</a>.</p></div><div class="section" title="7.4. apt Task Examples"><div class="titlepage"><div><div><h3 class="title" id="section-26459256796099617">7.4. <span class="command"><strong>apt</strong></span> Task Examples</h3></div></div></div><div class="informalexample"><pre class="programlisting"><span class="ReservedWord"><apt</span> <span class="Identifier">destdir</span>=<span class="String">"${build.classes.home}"</span> <span class="Identifier">sourcedestdir</span>=<span class="String">"${build.classes.home}"</span> <span class="Identifier">sourcepath</span>=<span class="String">"${basedir}/src"</span><span class="ReservedWord">></span> <span class="ReservedWord"><classpath</span> <span class="Identifier">refid</span>=<span class="String">"jaxws.classpath"</span><span class="ReservedWord">/></span> <span class="ReservedWord"><source</span> <span class="Identifier">dir</span>=<span class="String">"${basedir}/src"</span> <span class="Identifier">includes</span>=<span class="String">"*.java"</span><span class="ReservedWord">/></span> <span class="ReservedWord"></apt></span></pre></div><p>The above example processes the Java source files in the <code class="literal">${basedir}/src</code> directory and generates the source and class files in <code class="literal">${build.classes.home}</code>. <code class="literal">${basedir}/src</code> is directory used to search for source files for multiple <span class="command"><strong>apt</strong></span> rounds. The classpath is a reference to a <a class="link" href="http://ant.apache.org/manual/using.html#path" target="_top">path-like structure</a> <code class="literal">jaxws.classpath</code>, defined elsewhere in the build environment.</p><div class="informalexample"><pre class="programlisting"><span class="ReservedWord"><apt</span> <span class="Identifier">debug</span>=<span class="String">"true"</span> <span class="Identifier">verbose</span>=<span class="String">"true"</span> <span class="Identifier">destdir</span>=<span class="String">"${build.classes.home}"</span> <span class="Identifier">sourcedestdir</span>=<span class="String">"${build.classes.home}"</span> <span class="Identifier">sourcepath</span>=<span class="String">"${basedir}/src"</span><span class="ReservedWord">></span> <span class="ReservedWord"><classpath</span> <span class="Identifier">refid</span>=<span class="String">"jaxws.classpath"</span><span class="ReservedWord">/></span> <span class="ReservedWord"><option</span> <span class="Identifier">key</span>=<span class="String">"r"</span> <span class="Identifier">value</span>=<span class="String">"${build.home}"</span><span class="ReservedWord">/></span> <span class="ReservedWord"><source</span> <span class="Identifier">dir</span>=<span class="String">"${basedir}/src"</span><span class="ReservedWord">></span> <span class="ReservedWord"><include</span> <span class="Identifier">name</span>=<span class="String">"**/server/*.java"</span><span class="ReservedWord">/></span> <span class="ReservedWord"></source></span> <span class="ReservedWord"></apt></span></pre></div><p>The above example processes the Java source files in <code class="literal">${basedir}/src/**/server</code>, generates the source and class files in <code class="literal">${build.classes.home}</code>, compiles with debug information on, prints a message about what the compiler is doing, and passes the <code class="literal">-Dr=${build.home}</code> option to the annotation processor(s). <code class="literal">${basedir}/src</code> is the directory used to search for source files for multiple <span class="command"><strong>apt</strong></span> rounds. The classpath is a reference to a <a class="link" href="http://ant.apache.org/manual/using.html#path" target="_top">path-like structure</a> <code class="literal">jaxws.classpath</code>, defined elsewhere in the build environment. This will also fork off the <span class="command"><strong>apt</strong></span> process using the default <code class="literal">java</code> executable.</p></div></div></div><div lang="en" class="chapter" title="Extensions" id="jax-ws-ri-extensions"><div class="titlepage"><div><div><h2 class="title">Extensions</h2></div></div></div><div class="toc"><p><b>Table of Contents</b></p><dl><dt><span class="section"><a href="#jax-ws-ri-extensions-extensions">1. Extensions</a></span></dt><dd><dl><dt><span class="section"><a href="#sending-and-receiving-soap-headers">1.1. Sending and Receiving SOAP Headers</a></span></dt><dt><span class="section"><a href="#message-logging">1.2. Message logging</a></span></dt><dt><span class="section"><a href="#propagation-of-server-side-stacktrace">1.3. Propagation of Server-side Stacktrace</a></span></dt></dl></dd></dl></div><div lang="en" class="section" title="1. Extensions"><div class="titlepage"><div><div><h2 class="title" style="clear: both" id="jax-ws-ri-extensions-extensions">1. Extensions</h2></div></div></div><p>This page contains information about JAX-WS RI 2.2.7 specific features and extensions:</p><div class="section" title="1.1. Sending and Receiving SOAP Headers"><div class="titlepage"><div><div><h3 class="title" id="sending-and-receiving-soap-headers">1.1. Sending and Receiving SOAP Headers</h3></div></div></div><p>At times you need a way to send and receive SOAP headers in your message - these headers may not be defined in the WSDL binding but your application needs to do it anyway. One approach has been to write a <code class="literal">SOAPHandler</code> to do it, but its more work and is expensive as <code class="literal">SOAPHandlers</code> work on <code class="literal">SOAPMesssage</code> which is DOM based and JAX-WS runtime would need to do conversion from its abstract <code class="literal">Message</code> representation to <code class="literal">SOAPMessage</code> and vice versa.</p><p>There is a way to do it on the client side by downcasting the proxy to <code class="literal">WSBindingProvider</code> and use methods on it.</p><div class="section" title="1.1.1. Sending SOAP Headers"><div class="titlepage"><div><div><h4 class="title" id="sending-soap-headers">1.1.1. Sending SOAP Headers</h4></div></div></div><p>You would downcasting the proxy to <code class="literal">WSBindingProvider</code> and set the <code class="literal">Outbound</code> headers.</p><div class="informalexample"><pre class="programlisting">HelloService helloService = <span class="ReservedWord">new</span> HelloService(); HelloPort port = helloService.getHelloPort(); WSBindingProvider bp = (WSBindingProvider) port; bp.setOutboundHeaders( <span class="Comment">// simple string value as a header, like stringValue</span> Headers.create(<span class="ReservedWord">new</span> QName(<span class="String">"simpleHeader"</span>), <span class="String">"stringValue"</span>), <span class="Comment">// create a header from JAXB object</span> Headers.create(jaxbContext, myJaxbObject));</pre></div></div><div class="section" title="1.1.2. Receiving SOAP Headers"><div class="titlepage"><div><div><h4 class="title" id="receiving-soap-headers">1.1.2. Receiving SOAP Headers</h4></div></div></div><div class="informalexample"><pre class="programlisting">List<Header> inboundHeaders = bp.getInboundHeaders();</pre></div></div></div><div class="section" title="1.2. Message logging"><div class="titlepage"><div><div><h3 class="title" id="message-logging">1.2. Message logging</h3></div></div></div><p>Web Services developers generally need to see SOAP Messages that are transferred between client and service for debugging. There are SOAP Monitors for this job, but you need modify the client or server code to use those tools. JAX-WS RI provides logging of SOAP messages</p><div class="section" title="1.2.1. On the client"><div class="titlepage"><div><div><h4 class="title" id="on-the-client">1.2.1. On the client</h4></div></div></div><p>Set system property</p><div class="informalexample"><pre class="programlisting">com.sun.xml.ws.transport.http.client.HttpTransportPipe.dump=true</pre></div></div><div class="section" title="1.2.2. On the server side"><div class="titlepage"><div><div><h4 class="title" id="on-the-server-side">1.2.2. On the server side</h4></div></div></div><p>Set system property</p><div class="informalexample"><pre class="programlisting">com.sun.xml.ws.transport.http.HttpAdapter.dump=true</pre></div></div></div><div class="section" title="1.3. Propagation of Server-side Stacktrace"><div class="titlepage"><div><div><h3 class="title" id="propagation-of-server-side-stacktrace">1.3. Propagation of Server-side Stacktrace</h3></div></div></div><p>This is a very useful feature while developing Web Services. Often the soap fault messages for not user defined faults does not convey enough information about the problem. JAX-WS RI relieves you from digging out the server logs to find out the stacktrace. Whole stacktrace (including nested exceptions) can be propagated in the SOAP Fault and the complete exception stacktrace can be made visible to the client as cause of <code class="literal">SOAPFaultException</code>.</p><div class="section" title="1.3.1. Enabling propagation of Server-side stacktrace"><div class="titlepage"><div><div><h4 class="title" id="enabling-propagation-of-server-side-stacktrace">1.3.1. Enabling propagation of Server-side stacktrace</h4></div></div></div><p>Propagation of Stack trace is off by default. To turn it on for your Web Service Application to send the complete stack trace, set the system property</p><div class="informalexample"><pre class="programlisting">com.sun.xml.ws.fault.SOAPFaultBuilder.captureStackTrace=true</pre></div></div></div></div></div><div lang="en" class="chapter" title="Samples" id="samples"><div class="titlepage"><div><div><h2 class="title">Samples</h2></div></div></div><div class="toc"><p><b>Table of Contents</b></p><dl><dt><span class="section"><a href="#samples-samples">1. Samples</a></span></dt><dd><dl><dt><span class="section"><a href="#a-1-0">1.1. Directory Structure</a></span></dt><dt><span class="section"><a href="#a-2-0">1.2. Prerequisites</a></span></dt><dt><span class="section"><a href="#a-3-0">1.3. Installing JAX-WS RI 2.2.7</a></span></dt><dt><span class="section"><a href="#a-4-0">1.4. Running the sample</a></span></dt></dl></dd></dl></div><div lang="en" class="section" title="1. Samples"><div class="titlepage"><div><div><h2 class="title" style="clear: both" id="samples-samples">1. Samples</h2></div></div></div><p>This document explains the samples that are bundled along with JAX-WS RI 2.2.7.</p><p>The samples included with JAX-WS RI that is distributed on Java.net documents how to use JAX-WS RI in a non-Java EE 5 servlet container using a proprietary deployment descriptor <code class="literal">sun-jaxws.xml</code> and servlet <code class="literal">com.sun.xml.ws.transport.http.servlet.WSServlet</code>. This means that you can these JAX-WS RI applications in any servlet container that has been enabled with JAX-WS RI. Applications that use the proprietary DD and servlet will run in a JAX-WS RI enabled Java EE 5 servlet container, but they will be non-portable. If you wish to use these JAX-WS RI samples in a Java EE container in a Java EE portable manner you need to modify them to use the standard Java EE 5 deployment descriptor; please refer to the <a class="link" href="http://java.sun.com/javaee/index.jsp" target="_top">Java EE 5</a> or <a class="link" href="http://glassfish.java.net/" target="_top">Glassfish</a> documentation/samples.</p><p>All these samples are tested to run on <a class="link" href="http://glassfish.java.net/downloads/v2.1-b60e.html" target="_top">Glassfish V2.1</a> build and on Apache Tomcat 5.x.</p><div class="section" title="1.1. Directory Structure"><div class="titlepage"><div><div><h3 class="title" id="a-1-0">1.1. Directory Structure</h3></div></div></div><p>This section explains the directory structure of the <code class="literal">samples</code> directory in the bundle:</p><div class="table"><a name="d0e10346"></a><p class="title"><b>Table 28. List of Samples</b></p><div class="table-contents"><table summary="List of Samples" border="1"><colgroup><col width="50%"><col width="50%"></colgroup><thead><tr><th>Sample</th><th>Description</th></tr></thead><tbody><tr><td><p><code class="literal">docs</code></p></td><td><p>jax-ws-ri-overview, this file</p></td></tr><tr><td><p><code class="literal">asyncservice</code></p></td><td><p>Demonstrates JAX-WS RI specific endpoint to achieve server side asynchrony. This sample requires Servlet 3.0 API supported container like Glassfish 3.0.</p></td></tr><tr><td><p><code class="literal">wsimport_clientjar</code></p></td><td><p>Demonstrates use of <code class="option">-clientjar</code> option of <span class="command"><strong>wsimport</strong></span>.</p></td></tr><tr><td><p><code class="literal">optional_webxml</code></p></td><td><p>Demonstrates the simplified deployment of web services using JAX-WS RI deployment by not requiring the configuration of web.xml.</p></td></tr><tr><td><p><code class="literal">fromwsdl-wsaddressing-policy</code></p></td><td><p>Starting from WSDL shows how to develop a WS-Addressing enabled endpoint using standardized Addressing Metadata support.</p></td></tr><tr><td><p><code class="literal">fromjava-wsaddressing</code></p></td><td><p>Starting from Java endpoint how to develop W3C WS-Addressing endpoint.</p></td></tr><tr><td><p><code class="literal">fromwsdl-wsaddressing</code></p></td><td><p>Starting from WSDL shows how to develop a WS-Addressing endpoint using WS-Addressing WSDL Binding. This sample uses non-standard wsdl extension, also see standards based <span class="application">fromwsdl-wsaddressing-policy</span> sample.</p></td></tr><tr><td><p><code class="literal">fromjava</code></p></td><td><p>Demonstrates how to build, deploy, and invoke a simple Web service starting from a Java service endpoint implementation using annotations.</p></td></tr><tr><td><p><code class="literal">fromjavahandler</code></p></td><td><p>Same as <span class="application">fromjava</span> sample but with a simple logging handler on the client and server.</p></td></tr><tr><td><p><code class="literal">fromwsdl</code></p></td><td><p>Demonstrates how to build, deploy, and invoke a simple Web service starting from a WSDL using external customizations.</p></td></tr><tr><td><p><code class="literal">fromwsdl_secure</code></p></td><td><p>Same as <span class="application">fromwsdl</span> sample but demonstrates how to build, deploy, and invoke an HTTPS Web service and client from a WSDL.</p></td></tr><tr><td><p><code class="literal">fromwsdlhandler</code></p></td><td><p>Same as <span class="application">fromwsdl</span> sample but with a simple logging handler on the client and server.</p></td></tr><tr><td><p><code class="literal">dispatch</code></p></td><td><p>Demonstrates how to dynamically invoke web service endpoints.</p></td></tr><tr><td><p><code class="literal">provider</code></p></td><td><p>Demonstrates how to build, deploy, and invoke <code class="literal">javax.xml.ws.Provider</code> based Web service endpoint.</p></td></tr><tr><td><p><code class="literal">asyncprovider</code></p></td><td><p>Demonstrates how to build, deploy, and invoke a server side asynchronous <code class="literal">Provider</code> based Web service endpoint.</p></td></tr><tr><td><p><code class="literal">annotations</code></p></td><td><p>Same as <span class="application">fromjava</span> but shows how to specify a different parameter name, operation name, targetNamespace, and other similar features.</p></td></tr><tr><td><p><code class="literal">async</code></p></td><td><p>Demonstrates how to generate async operations in a client SEI from a WSDL and invoke it from the client application.</p></td></tr><tr><td><p><code class="literal">efficient-handler</code></p></td><td><p>Demonstrates efficient handler using <code class="literal">com.sun.xml.ws.api.handler.MessageHandler</code>, which is an efficient protocol handler.</p></td></tr><tr><td><p><code class="literal">external-customize</code></p></td><td><p>Demonstrates how a client client application can customize a published WSDL using external binding file.</p></td></tr><tr><td><p><code class="literal">inline-customize</code></p></td><td><p>Demonstrates how a client application and server endpoint can be generated from a WSDL with embedded binding declarations.</p></td></tr><tr><td><p><code class="literal">mtom</code></p></td><td><p>Demonstrates how to enable MTOM and swaRef.</p></td></tr><tr><td><p><code class="literal">mtom-large</code></p></td><td><p>Demonstrates how to transfer large attachments in streaming fashion using MTOM.</p></td></tr><tr><td><p><code class="literal">mtom-soap12</code></p></td><td><p>Same as <span class="application">mtom</span> sample but shows how to specify SOAP 1.2 binding.</p></td></tr><tr><td><p><code class="literal">fromjava-soap12</code></p></td><td><p>Same as <span class="application">fromjava</span> sample but shows how to specify SOAP 1.2 binding.</p></td></tr><tr><td><p><code class="literal">fromwsdl-soap12</code></p></td><td><p>Same as <span class="application">fromwsdl</span> sample but shows how to specify SOAP 1.2 binding.</p></td></tr><tr><td><p><code class="literal">supplychain</code></p></td><td><p>Same as <span class="application">fromjava</span> sample but using JavaBeans as parameter and return types. Also the service can be built and deployed using Endpoint API.</p></td></tr><tr><td><p><code class="literal">mime</code></p></td><td><p>Demonstrates how a MIME binding is defined in the WSDL to send <code class="literal">wsdl:part</code> as MIME attachments. This requires that the development model is 'starting from WSDL'.</p></td></tr><tr><td><p><code class="literal">mime-large</code></p></td><td><p>Demonstrates how to transfer large attachment in streaming fashion using <code class="literal">wsi:swaref</code>.</p></td></tr><tr><td><p><code class="literal">wsimport_catalog</code></p></td><td><p>Demonstrates a how a WSDL and schema URI's can be resolved using catalog mechanism using <span class="command"><strong>wsimport</strong></span> ant tasks' catalog attribute and also using ant's core type <code class="literal">xmlcatalog</code>.</p></td></tr><tr><td><p><code class="literal">catalog</code></p></td><td><p>Shows the catalog capability on the client side; Catalog is used every time the implementation tries to access a resource identified by URI that is believed to contain either a WSDL document or any other document on which it depends .</p></td></tr><tr><td><p><code class="literal">restful</code></p></td><td><p>Shows an example of a REST Web Service implemented as a JAX-WS 2.0 <code class="literal">Provider</code> and accessed via a JAX-WS <code class="literal">Dispatch</code> client. The <code class="literal">Request</code> uses an HTTP <code class="literal">GET</code> Request Method and uses the JAX-WS <code class="literal">MessageContext</code> properties <code class="literal">PATH_INFO</code> and <code class="literal">QUERY_STRING</code>.</p></td></tr><tr><td><p><code class="literal">stateful</code></p></td><td><p>This sample shows the JAX-WS RI's stateful webservice support feature.</p></td></tr><tr><td><p><code class="literal">schema_validation</code></p></td><td><p>This sample demonstrates JAX-WS RI's validation feature that validates the incoming/outgoing messages are as per schema.</p></td></tr><tr><td><p><code class="literal">dual-binding</code></p></td><td><p>This sample demonstrates the JAX-WS RI's featuer to expose the same service class under <code class="literal">SOAP/HTTP</code> and <code class="literal">XML/HTTP</code> binding.</p></td></tr><tr><td><p><code class="literal">large_upload</code></p></td><td><p>This sample demonstrates uploading a large file to the server.</p></td></tr><tr><td><p><code class="literal">type_substitution</code></p></td><td><p>This sample demonstrates type substitution and sending java types that are not directly referenced by the WSDL.</p></td></tr><tr><td><p><code class="literal">xmlbind_datasource</code></p></td><td><p>This sample demonstrates a REST based webservices using <code class="literal">XML/HTTP</code> binding along with <code class="literal">Provider</code>/<code class="literal">Dispatch</code>.</p></td></tr></tbody></table></div></div><br class="table-break"></div><div class="section" title="1.2. Prerequisites"><div class="titlepage"><div><div><h3 class="title" id="a-2-0">1.2. Prerequisites</h3></div></div></div><p>Here is the list of prerequisites that needs to be met before any of the samples can be invoked:</p><div class="orderedlist"><ol class="orderedlist" type="1"><li class="listitem"><p>Download Java 2 Standard Edition 5.0 Update 2 or later ( <a class="link" href="http://java.sun.com/javase/downloads/index.jsp" target="_top">J2SE 5.0</a>). Set <code class="literal">JAVA_HOME</code> to the J2SE 5.0 installation directory.</p></li><li class="listitem"><p>Set <code class="literal">JAXWS_HOME</code> to the JAX-WS installation directory.</p></li></ol></div></div><div class="section" title="1.3. Installing JAX-WS RI 2.2.7"><div class="titlepage"><div><div><h3 class="title" id="a-3-0">1.3. Installing JAX-WS RI 2.2.7</h3></div></div></div><div class="itemizedlist"><ul class="itemizedlist" type="disc"><li class="listitem"><p>Follow the <a class="xref" href="#installation-instructions" title="5. Installation Instructions">Installation Instructions</a> from Release Notes.</p></li><li class="listitem"><p>Make sure that your container is configured for port 8080 as samples are hardcoded with this port info. Otherwise, you need to change samples to use the correct port by replacing '8080" with your port in all the files included in the sample.</p></li></ul></div></div><div class="section" title="1.4. Running the sample"><div class="titlepage"><div><div><h3 class="title" id="a-4-0">1.4. Running the sample</h3></div></div></div><p>Each sample has a <code class="filename">readme.txt</code> in its directory that details the instructions specific to the sample. Each sample can be built, deployed and invoked using the <code class="literal">ANT_HOME/bin/ant</code> and <code class="literal">build.xml</code> ant script in the root directory of the sample. Each ant script supports the following set of targets:</p><div class="informaltable"><table border="1"><colgroup><col width="50%"><col width="50%"></colgroup><thead><tr><th>Target</th><th>Description</th></tr></thead><tbody><tr><td><p><code class="literal">server</code></p></td><td><p>Builds and deploy the service endpoint WAR on Glassfish v2 installation referenced by <code class="literal">$AS_HOME</code></p></td></tr><tr><td><p><code class="literal">server -Dtomcat=true</code></p></td><td><p>Builds and deploy the service endpoint WAR on Tomcat installation referenced by <code class="literal">$CATALINA_HOME</code></p></td></tr><tr><td><p><code class="literal">client</code></p></td><td><p>Builds the client</p></td></tr><tr><td><p><code class="literal">run</code></p></td><td><p>Runs the client</p></td></tr></tbody></table></div><p>Some samples (e.g. <span class="application">fromjava</span>, <span class="application">supplychain</span>) can be built, deployed using <code class="literal">javax.xml.ws.Endpoint</code> API. These samples support extra targets:</p><div class="informaltable"><table border="1"><colgroup><col width="50%"><col width="50%"></colgroup><thead><tr><th>Target</th><th>Description</th></tr></thead><tbody><tr><td><p><code class="literal">server-j2se</code></p></td><td><p>Builds and deploys the <code class="literal">Endpoint</code> API based service endpoint (doesn't terminate until <span class="command"><strong>server-j2se-stop</strong></span> is called)</p></td></tr><tr><td><code class="literal">server-j2se-stop</code></td><td>Stops the <code class="literal">Endpoint</code> API based service endpoint (need to run from a different window)</td></tr></tbody></table></div><p>It is essential for the service endpoint to be deployed on Application Server before clients can be built because clients use the WSDL exposed from the service endpoint deployed in the Application Server. So please make sure that your Application Server is either running before the <code class="literal">server</code> target is invoked or run it after the <code class="literal">server</code> target is invoked. You will have to wait a few minutes for the Application Server to deploy the service endpoint correctly before building the client.</p><p>We appreciate your feedback, please send it to <a class="link" href="mailto:users@jax-ws.java.net" target="_top">users@jax-ws.java.net</a>.</p></div></div></div></div></body></html>