The Java API for XML-Based Web Services (JAX-WS) 2.

1
Maintenance Release May 7, 2007

Editors: Doug Kohlert Arun Gupta Comments to: jsr224-spec-comments@sun.com

Sun Microsystems, Inc. 4150 Network Circle Santa Clara, CA 95054 USA

ii

JAX-WS 2.1

May 7, 2007

Specification: JSR-000224 - Java™API for XML-Based Web Services (“Specification”) Version: 2.1 Status: Maintenance Release 2 Release: 7 May 2007 Copyright 2007 Sun Microsystems, Inc. 4150 Network Circle, Santa Clara, California 95054, U.S.A All rights reserved.

LIMITED LICENSE GRANTS 1. License for Evaluation Purposes. Sun hereby grants you a fully-paid, non-exclusive, non-transferable, worldwide, limited license (without the right to sublicense), under Sun’s applicable intellectual property rights to view, download, use and reproduce the Specification only for the purpose of internal evaluation. This includes (i) developing applications intended to run on an implementation of the Specification, provided that such applications do not themselves implement any portion(s) of the Specification, and (ii) discussing the Specification with any third party; and (iii) excerpting brief portions of the Specification in oral or written communications which discuss the Specification provided that such excerpts do not in the aggregate constitute a significant portion of the Specification. 2. License for the Distribution of Compliant Implementations. Sun also grants you a perpetual, non-exclusive, non-transferable, worldwide, fully paid-up, royalty free, limited license (without the right to sublicense) under any applicable copyrights or, subject to the provisions of subsection 4 below, patent rights it may have covering the Specification to create and/or distribute an Independent Implementation of the Specification that: (a) fully implements the Specification including all its required interfaces and functionality; (b) does not modify, subset, superset or otherwise extend the Licensor Name Space, or include any public or protected packages, classes, Java interfaces, fields or methods within the Licensor Name Space other than those required/authorized by the Specification or Specifications being implemented; and (c) passes the Technology Compatibility Kit (including satisfying the requirements of the applicable TCK Users Guide) for such Specification (“Compliant Implementation”). In addition, the foregoing license is expressly conditioned on your not acting outside its scope. No license is granted hereunder for any other purpose (including, for example, modifying the Specification, other than to the extent of your fair use rights, or distributing the Specification to third parties). Also, no right, title, or interest in or to any trademarks, service marks, or trade names of Sun or Sun’s licensors is granted hereunder. Java, and Java-related logos, marks and names are trademarks or registered trademarks of Sun Microsystems, Inc. in the U.S. and other countries. 3. Pass-through Conditions. You need not include limitations (a)-(c) from the previous paragraph or any other particular “pass through”requirements in any license You grant concerning the use of your Independent Implementation or products derived from it. However, except with respect to Independent Implementations (and products derived from them) that satisfy limitations (a)-(c) from the previous paragraph, You may neither: (a) grant or otherwise pass through to your licensees any licenses under Sun’s applicable intellectual property rights; nor (b) authorize your licensees to make any claims concerning their implementation’s compliance with the Specification in question. 4. Reciprocity Concerning Patent Licenses. a. With respect to any patent claims covered by the license granted under subparagraph 2 above that would be infringed by all technically feasible implementations of the Specification, such license is conditioned upon your offering on fair, reasonable and non-discriminatory terms, to any party seeking it from You, a perpetual, non-exclusive, nontransferable, worldwide license under Your patent rights which are or would be infringed by all technically feasible implementations of the Specification to develop, distribute and use a Compliant Implementation. b With respect to any patent claims owned by Sun and covered by the license granted under subparagraph 2, whether or not their infringement can be avoided in a technically feasible manner when implementing the Specification, such license shall terminate with respect to such claims if You initiate a claim against Sun that it has, in the course of performing its responsibilities as the Specification Lead, induced any other entity to infringe Your patent rights. c Also with respect to any patent claims owned by Sun and covered by the license granted under subparagraph 2 above, where the infringement of such claims can be avoided in a technically feasible manner when implementing

May 7, 2007

JAX-WS 2.1

iii

The Specification is subject to U.F. non-exclusive. applet and/or implementation. then the Government’s rights in the Software and accompanying documentation shall be only as set forth in this license.F. INDIRECT.S. WARRANTIES OF MERCHANTABILITY.S.S. offering to sell. Government: If this Specification is being acquired by or on behalf of the U. PROFITS OR DATA. LIMITATION OF LIABILITY TO THE EXTENT NOT PROHIBITED BY LAW. EITHER EXPRESS OR IMPLIED.S.S.7201 through 227. “javax”. 5. hold harmless.the Specification such license. and use without limitation the Feedback for any purpose. “com. NON-INFRINGEMENT (INCLUDING AS A CONSEQUENCE OF ANY PRACTICE OR IMPLEMENTATION OF THE SPECIFICATION). 2007 .sun”or their equivalents in any subsequent naming convention adopted by Sun through the Java Community Process. OR THAT THE CONTENTS OF THE SPECIFICATION ARE SUITABLE FOR ANY PURPOSE. SUN MAKES NO REPRESENTATIONS OR WARRANTIES. the Specification could include technical inaccuracies or typographical errors. irrevocable license. except with an appropriate and separate license from Sun. selling or importing a Compliant Implementation infringes Your patent rights.7202-4 (for Department of Defense (DoD) acquisitions) and with 48 C. Convention for the International Sale of Goods and the choice of law rules of any jurisdiction will not apply.N. DISCLAIMER OF WARRANTIES THE SPECIFICATION IS PROVIDED “AS IS”. 227. with respect to such claims. Government prime contractor or subcontractor (at any tier). LOST REVENUE. INCLUDING WITHOUT LIMITATION. RESTRICTED RIGHTS LEGEND U. You will indemnify. fully paid-up. shall terminate if You initiate a claim against Sun that its making. using. HOWEVER CAUSED AND REGARDLESS OF THE THEORY OF LIABILITY. (ii) the use or distribution of your Java application. INCLUDING BUT NOT LIMITED TO. “Licensor Name Space”shall mean the public class or interface declarations whose names begin with “java”. CONSEQUENTIAL. Definitions. to incorporate. GENERAL TERMS Any action related to this Agreement will be governed by California law and controlling U. OR FOR SPECIAL. and defend Sun and its licensors from any claims arising or resulting from: (i) your use of the Specification. with the right to sublicense through multiple levels of sublicensees. ARISING OUT OF OR RELATED IN ANY WAY TO YOUR HAVING.212 (for non-DoD acquisitions). 2. having made. or any recognized successors or replacements thereof. and “Technology Compatibility Kit”or “TCK”shall mean the test suite and accompanying TCK User’s Guide provided by Sun which corresponds to the Specification and that was available either (i) from Sun’s 120 days before the first release of Your Independent Implementation that allows its use for commercial purposes. This Agreement will terminate immediately without notice from Sun if you breach the Agreement or act outside the scope of the licenses granted above. INCIDENTAL OR PUNITIVE DAMAGES. worldwide. and (ii) grant Sun a perpetual.101 and 12. includes any of Sun’s source code or binary code materials. The U. EVEN IF SUN AND/OR ITS LICENSORS HAVE BEEN ADVISED OF THE POSSIBILITY OF SUCH DAMAGES. IN NO EVENT WILL SUN OR ITS LICENSORS BE LIABLE FOR ANY DAMAGES. this is in accordance with 48 C. FITNESS FOR A PARTICULAR PURPOSE. disclose.R. export control laws and may be subject to export or import regulations in other iv JAX-WS 2.R. or (ii) more recently than 120 days from such release but against which You elect to test Your implementation of the Specification. and/or (iii) any claims that later versions or releases of any Specification furnished to you are incompatible with the Specification provided to you under this license. In addition. you hereby: (i) agree that such Feedback is provided on a non-proprietary and non-confidential basis. IMPLEMENTING OR OTHERWISE USING THE SPECIFICATION.1 May 7. federal law. This document does not represent any commitment to release or implement any portion of the Specification in any product. Government or by a U. For the purposes of this Agreement: “Independent Implementation”shall mean an implementation of the Specification that neither derives from any of Sun’s source code or binary code materials nor. REPORT If you provide Sun with any comments or suggestions concerning the Specification (“Feedback”).

acknowledgment. unless in writing and signed by an authorized representative of each party. proposals. re-export or import as may be required after delivery to Licensee. 2007 JAX-WS 2. This Agreement is the parties’entire agreement relating to its subject matter. May 7. representations and warranties and prevails over any conflicting or additional terms of any quote.1 v .countries. or other communication between the parties relating to its subject matter during the term of this Agreement. conditions. order. No modification to this Agreement will be binding. Licensee agrees to comply strictly with all such laws and regulations and acknowledges that it has the responsibility to obtain such licenses to export. It supersedes all prior or contemporaneous oral or written communications.

1 May 7. 2007 .vi JAX-WS 2.

. . . . . . . . . . . . . . . . . . .2 2. . . . Standardized Transport Bindings . . .5 1. . . . . . . . . . . . . . . . . 10 Operation . . . . . . . . . . . . . . . . . . . . . . . . . . 1. . . . . . . . . . . . . . . . . . . . 1 1 3 3 3 3 4 4 4 4 5 5 5 5 5 6 7 7 9 9 Use Cases . . . . . . . . . . . . . . Customizable WSDL Mapping . . . . . . . . . . . . . . . .3. . . . Expert Group Members . . . . . Standardized Synchronous and Asynchronous Invocation . . . . . .7 1. .3. . . . . . . . . .9 1. . . . . . . . . . . . . . . . . . . . . . . . . . . . . .3 1. . . . . . . . . . .3. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .1 to Java Mapping 2. .1 vii May 7. . . . . 12 Parameter Order and Return Type . . . . . . . . . . . .3. . . . . . . . . . . . .1 Definitions . . . . . . . . .1 2. . . . . . . . . .1 Handler Framework . Standardized Handler Framework . .1 1. .1 1.3. . . . Non-Goals . Requirements . . . . 2007 . . . . . . . . . .2 2. . .3. . . . . . . . 15 Holder Class . . . . . . . Acknowledgements . . . . . . . . . . . . . . . . . . .5 1. . . . . . . . . . . . . . . . . . . . . . . . . . . . . Session Management . . . . . . .4 Relationship To JAXB . . . . .3. .3. . . . . . . 2 WSDL 1. . . . . . . . . . . . .3. . . . . . . . . . .2 1. . . . . . . . . . . . . . . . . . . . . . . . . .7 Conventions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Standardized Protocol Bindings . . . . . . . . . . . . . . . . . . 10 Port Type . . . . .2 1. . . . . . . . . . 2. . . . .3. . . .6 1. . . . . . . . . . . . . . . . . . . . . . .3 Message and Part . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .1 2. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .4. . . . . . . Versioning and Evolution . . . . . . . . .3. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .3 Extensibility . . . . . . . . .4 1. . . . . . . . .3 Goals . . . . . . . . . . . . . . .3. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .8 1. . . . . . . . . . 1. . . 17 JAX-WS 2. . . . . . . . . . . . . .1. . . . . . 11 2. . . . . . . . . . . . . . . . . . . Standardized WSDL Mapping . . .6 1. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1. . . .Contents 1 Introduction 1. . . . . . . . . .

. . . . . . . . . . . . . . . . . . . . . . . . . 33 3. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .1 Name Collisions . . . . . . . . . . . . . . . . . . . . . . . . . 43 Method and Parameters . . . . . . 31 3. . . . . . 22 2. . . . . . . 23 MIME Binding . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .8. . . . . . .2 Parameter and Return Type Classification . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .2 2. . . . 31 Class . . . . . . . . . . . . . . . . .6. . . . . . . . . . . . . . 26 2. . . . . . . . . . . . . . . . . . . . . 29 2. . . . . . . . . . . . . . . . . .5. . . . . . . . . . . . . .5 Method . . . . . . . . . . . . . . . . . . . . . . 34 3. . . . . . . . . . . . . . . . . . . . . . . 25 2. . . . 22 2. . .6. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .9 Generics . . . . . . . . . . . . . . . . . . . . . . . . . . 30 2. .11 Service and Ports . . . . . 31 3. . . . . . . . . . . 32 Interface . . . . . . . . . . . . . . . .1 2. . . . . . . . . . . . . . . . . . . . . . 37 3. . . .10. . . . . .2. . . . . 38 3. . . . . . . . . . . . . . . . . . .1 Example . . . . . . . . . . . . .1 Java Names . . . . . . . . .4 2. . . . . .1 W3CEndpointReference . . . . . . . . . . . . . . . . . . . . . . . . . . .6 Method Parameters and Return Type . . .4 Asynchrony . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 23 2. . . . . .2 Interface . . . . . .1 Name Collisions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 33 3. . . . . . . . . 23 2. . . . . . . 47 viii JAX-WS 2. . . . . . . . . . .6. . . . . . . . . . . . . . . . . . . . 21 2. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .5 Fault . . . . . 43 3. . . . . . . . . . . . . . . . . . . . . . . . . 33 3. . 30 31 3 Java to WSDL 1. . . . . . . . . . . . . . . . . . . . . . . . . . . . .3 3. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 41 Bindings . . . . . . . . . . .1 Example . . . . . . . . . . . . . .7 3. . . .10 SOAP HTTP Binding . . .5. . . . . . . . .1 Inheritance . . . .7 Service and Port . . . . . . . 17 Types . . . . . . . . . . . . . . . . .1 3. . . . . . . 42 3. . .4. . . . . . . .8 Service Specific Exception . . . . .1 May 7. . . . . . . . . . . . . .2 Method and Parameters . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 46 3. . . . . . . . . . . . . . .6 Binding . . . . .4.1 3. . . . . . . . . . . . . .2 3. .6. . .1 One Way Operations . . . . . .8. . . . . . . . . . . . . . . . . . . . . . .3.8. . . . . . . . .1 Mapping 3. . . . . . . . . . . . .1 Interface . . . 23 SOAP Binding . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 46 3. . . . . . . . . . . . . . . 37 Use of JAXB . . . . . . . . . . . . . . . . . . . . . . . . . 44 3. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .8 XML Names . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .6.4 Package . . . . .7. . . . . . . . . . . 2007 . . . . . . . . . . . . . . . . . . . . . . . . . . . . .3 General Considerations . . . . . 46 3. .1. .10.

. . . .2. . . . . . . . . . . . . .5 5.2. . . . . . . . . . . . . . . . . . . . . . . . .3. . . . . . . . . . . . . . . . .2 5. . . . . . . . . .2 5. . .4 4. .xml. . . . . . . . . 67 Publishing . . . . .3 5. . . . . 70 Endpoint Properties . . . . . . . . . . . . . . . . . . . . . . . . . . . .ws. . .ws.1. . . . . . . . . . . . . . . . . . .5 Catalog Facility . . . . . . . . . . .xml. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .2. . . . . . . . . . . . . . . . . . . . . . . .3 4.xml. . . . . . 51 4. . . . . . . . .1. . .1 4. .EndpointReference . . . . . . . . . . . . . . .ws. 70 Determining the Contract for an Endpoint . . . . .2 4. . . . . . .6 5. . . . . . . . . . . . . . . . . . . . . . .1.4 5. . .ws. . . . . . . . . . . . . . . . . . . .3. . . . . . . . .2 4. . . . . . .1 5.1 51 javax. . . . . . . 61 Using JAXB . . . . . . . . . . . . . . . . 65 5 Service APIs 5.xml. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .1 javax. .Provider 5. . . . . .3. . . . . . . . . . . . . . . . . . . . . . . . . . . . 70 Endpoint Metadata . . . . . . . . . . . . . . . . . . . . . . . . . . .4 4. . . .1. . . . . . . . . . . . . .EndpointReference . . . . . . . . . . . . . . . . . . . .4 Service Usage . . . . . . . . . . . . .Endpoint . . . . . . . . .2. . . . . 62 4. .2. . . . . . . . . . . . . . . . . . . . . . . . . . . . .xml. . . . . . . . . . . . . . . . . . . .8 Endpoint Usage . . . . . . . . . .Service . . . . . . . . . . . . . . . . . 74 javax. . . . . . . 63 javax.ws. . . . . . . . . . . . 74 Executor . . . . . . . .Dispatch . . . . . . . . .1 4. . . . . . . . . . . . . . . . . . . . . . .1. . . . . . . 66 javax. . . . . . . . 57 Proxies . . . . . . . . . . . . . . . . . 75 5. . . . . . . . . . . . .1 5. . .2. . . . . 60 Operation Invocation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .5 Configuration . . . . . . . . . .3.BindingProvider . . . . . . . . . . . . . . . . . . . .2.2. . . . . . . . . . . . . . . . . . . . . . . . . . . . . 62 Examples . . . . 54 4. . . . . .ws. . . . . . . . . . . . . . . . . . . . . . . . . . . 53 Handler Resolver . 64 65 . . . . . . . . . . . . .2. . . . . . . . . . . 58 4. . . . . . . . . . . . . . . . . . . . . . 68 Publishing Permission . . . . 2007 . . . . . . . . . .2. . . . .1. .3 javax. . . . . . . . . . . . . 53 Executor . . .1. . . 66 Examples . .2 javax. . . . .ws. . . . . . . . .2. . . . . . . . . . . . . . . . . . . . . . . . . . . . . .3 javax. . . . . . . . . . . .xml.ws. . . 57 Exceptions . . . . . . . . . 54 4. . . .1 ix May 7. . . . . . . . . . . . . . . . . . . . . . . . 59 4. . . . . 52 Provider and Service Delegate . . . . . . 67 5. . . . . . . . . . . . . . . . . . . . . . . 66 Configuration . . . . . . . . . . . . . . . . . . . . . .4 Client APIs 4. . . . 75 JAX-WS 2. . . . . .3 5. . . 54 Asynchronous Operations . . . . . . . . 60 Asynchronous Response . . . . . .2. .4 Configuration . .1 4. . . . . . . . . . . .xml. . . . . . . . . . . . . . . . . . .WebServiceContext .3 4. .2 4. . . . . . . . . .7 5. . . . . . . .3. . .xml. . . . . . . . . . . . . . . . . . . .2 Invocation . . . .3 4. . . . . . . . .

. . . . . . . . 94 x JAX-WS 2.WebEndpoint . . .1 6. . . . . . . . . . . . . . .10 javax. . 83 6. . . . . . . . . . .xml.3 7. . . . . . . 81 . . . .WebServiceProvider . .1 May 7. . .2. . .ws. .3 6. . . . . . . . . . . . . . . . .2. . . . . . . . . . . . . . .3. . . . . . . . . . . . . . 76 . . .9 javax. . . . . . . . .11 Annotations Defined by JSR-181 . 88 javax. . .2. . . .xml. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .Binding . .4. . . . . . . . . 80 Creating Endpoint Objects . . . .ws. 93 7. . . . . . . . . .2 Protocol Specific Exception Handling . . . . . . .spi. . . . .ws. . . . 89 javax. . . . .MTOMFeature . . . 91 7. . .AddressingFeature . . . . .5 javax. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 83 javax. . . . .ServiceDelegate Exceptions . . . . . . . . . . . . . . . . 79 6. . . . .5 Configuration . . . . . . . . . . . . .ws. . . . . 83 6. .5. . .xml. . . . .xml. . .WebServiceFeature . . . . . . . .4 6. . . . 91 javax. 82 One-way Operations . 88 javax.wsaddressing. . . . . . . . . . . . . .5 7. . . . . . . . . . . . . . . . . . . . . . . . . . . .4. . . . . . . . . .4 MessageContext . . . . .ResponseWrapper . . .2 7. . . . .4 7. . . . .1 6.1 6. 77 79 javax. . . . . .2 6. .ws. . . . .xml. . . . . .1 Example . . 90 7. . . . . . . 79 javax. . .spi. . 85 87 7 Annotations 7. . . . . . . . . . . . . . . .ws. . . . . . . . . . . . . . . . . . . . . . . . . .10. . . . . . . . 82 6. . . . . . . . . . .4 javax. . . . .9. . . . . . . . . . . . . . . . . . . .xml. . . .xml. . . . . . . . . . . .8 7. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .3 6. . . .ws. . . .1 6. .WebFault . . . . . . . . . .BindingType . . . . . . 2007 . . . . . . . 88 javax. . . . .1 7. . . 81 Getting Port Objects . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .xml. .3 javax.xml. . . . . .ws. . . . . . . . . . . . . . . . . . . . . . . . . . . . . .1 Example . 89 7. . . . . . . . .ws. . . . . . . . . . . . . . . . . . . . 81 6. .ws. . . .7 7. . . . .soap. . . . . . . . . . . . . . . . 90 javax. . . . . . .6 javax. . . .ws. . . .5. . . . . . . . . . . .xml. . .5. . . .xml. . . . . . . . . . . . . . .WebServiceRefs . . .soap. . . . . .1 Example . 84 javax.RespectBindingFeature . . .W3CEndpointReferenceBuilder 6 Core APIs 6. . . . . . . 92 7. . . . . . . . . . . . . 80 Creating ServiceDelegate Objects . . . . . . . . . . . . . . . . . . .1 5. . . . . . . . . . . . .ServiceMode . . . . . . . . . . . . . . . . . . . . . . .2. . . . . . . . . . . . . . . .xml. . .2. . . . . .xml. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .2 6. . .ws. . . . . . . . . . . . . .xml. . .6. . . . . . . . . . . . . .xml. . . . . . . . .WebServiceClient . . . . . . . . .xml. . . . . . . . . . . . .xml.ws. . . . . . 93 7. . .ws. . . . . .ws. . . . . 89 javax. . .RequestWrapper . . . . . . . . . .ws. . . .xml. . . . 81 EndpointReferences . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .ws. . . . . . . . . . . . . . . . . . . . . .WebServiceRef . .ws. . . . . .2 javax. . . . .5. . . . .Provider . . .

. . . . . . . . .14. . . 95 7. . . . . . . .3 javax. . . . . . . . . . . . . . .WebServiceFeatureAnnotation . .11.xml. . . . . . . . . . . . . . . . .11. . . . . . . . . . . . . . . . . . . . . . . . . . . . .7. 107 Service . . . . . . . . . . . . . . . . . . . . . . . . . . .3 8. . . .soap. . . . . 99 Binding Declaration Container . . . . . . . . .4 javax. . . . .7. . . . . . .xml. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .jws. . . . . .6 8.7 javax. .2 8. . . . . .ws. . . . . .WebParam . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .7 8. . 102 Scoping of Bindings . . . . . . . .14 javax. . . . . . . . . . . . . . . . . . 99 Embedded Binding Declarations . . . . . .xml. . . .HandlerChain . 94 7. . . . . . . . . .jws. . . .11.ws. 95 7. . . . . . . . . . . . . .WebService . .FaultAction . . . . . . .jws. . . . . . . 108 111 9 Handler Framework 9. . . . . . . . . . . . . . 94 7. . . . . . . . . . 104 8. . . . 105 PortType Operation . . .2 javax. . . . . . . . . . . .5 javax. . . . . . . . . . . . .6 8.11. . . . . .ws. . . . .1 Example . . . . . . . . . . . .13 javax. .7. . . . . . 104 Standard Binding Declarations . . . . . . . . . . . . . . . . . . . . . . .1 8. . . .7. . . 100 8. . . . . . . 95 7. . . . . . . . . . . . .xml. .jws. . . . . . . . . . 98 8 Customizations 8. . . . . . 104 PortType . . . .7. . . . 106 PortType Fault Message . . . . . . . . . . . . . . . . . . . . .MTOM . . . . . .RespectBinding . . . . . .7. . . . . . . . . . . . . . . . 96 7. . 100 8. . . . . . . . . . . . .1 xi May 7. . . . . . . . . . . . . . . . .5 8. . . . . . . . . . . . . .8 Definitions . . . . . . . . .SOAPBinding . . . . . .12 javax. . . . . . . .7.11. . . . . . . . . . . . . . . . . . . . . 107 Binding . . . . . . . . . 94 7.4. . . . . . . . . 96 7. . . . . . . . . . . . . . . . . . . . . .3 99 Binding Language . . . . . . . . .14. . . . . . . . . . . . . . .Addressing . . .WebMethod . . . . . . . . . . . . . . . . . . .1 javax. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 97 7. . . . . . . . . . . . . . 107 Binding Operation . . . . . .1 8. .Action . . . . . . . . . . . . . . . . . . . .4 8. . . 97 7.3 javax. . . . . .7. . 2007 . . . . . . . . . . . . . . . . .jws. 111 JAX-WS 2. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .2 javax. . . . . . . . . . . .jws. . . . 95 7. . . . . .ws. . . . . . . . . . . . . . . . . . . . . .14. . . . . . . . . . . . . . . . . . . . . . . . . 100 8. . . . . . . . .1 javax. . . . . . . . . . . . .WebResult . . . . . . . 108 Port . . . . . . . .soap. .spi. . . . . . . . . . . . . . . . . .2 8. . . . . . . . . . . . .11. . . . . . . .jws. . .11.3. 102 8. . 94 7. . . .5 8. .4 External Binding File . . . .6 javax. .xml. . . . . .ws. . . . . . . .7. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .1 Example . . . . . . . . . . . . . . . . . . . . .OneWay . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .1 Architecture . . . . . . . .ws. .7 Using JAXB Binding Declarations . . . . . . . . . . .xml. . . . . . . . .

. .1. . . . . . . . . . . . . 116 9. . . . . . . . . .9. . 123 125 10 SOAP Binding 10. .3. . . . . . . . . .3. . . 111 Binding Responsibilities . . . . . . . . .1. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 120 javax. . . . . . . . . . . .3. . .1 Configuration . . . . . . . . . . . . . . .xml. . . . . . . 128 10. . . . 136 xii JAX-WS 2. . . . . . . . . . . . . . . .2. . . . . . . . 129 11 HTTP Binding 133 11. . . . . . . . . . 119 9. . . . . . . . . . . . . . . . 114 Deployment Model . . . . . . . . . . . . . . . . . .1 9. . . . . . . . 119 9. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .ws. . . . . . . . . . . . . . . . . . . . . . . . . . 127 10. . . . . 114 9. . . . . . . . . . . . . . .1 9. . . . . . . . . . . . . . . . . . . . . . . 135 11. 125 10. . . . . . .MessageContext . . . . .2. . . . . . . . . . . . . . . . . . . . . . . . . . . . . .1. . . . . . . . . . . . . . .2 Deployment Model . . . .handler. . . . . . . . 117 Handler Implementation Considerations . . . . . . . . . . . . . . . . . . . . . . . .1 Programmatic Configuration . . . 133 11. .2 Security . . .3 Session Management . . . . . . . . . . . . . . . . . . . . 120 Relationship to Application Contexts . . . . . . . . . .1 May 7. .2 9. . . . . . . . . . . . . . . . . . . . . .4.1 Programmatic Configuration . .2 9. . . . . . .xml. . . . . . . . . . . . . . . 116 Handler Execution . . . . . . . . . . .3 javax.4. . . . . . . . . . . . . . . . . . . . . . . . . 134 11. . . . . . . . . . . 133 11. . . . . . . . . . . . . . . . .1. . . . . . . . . . . . . . . . . . . .1 Configuration . . . . . . . . 135 11. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 136 11. . . . . . . . . . . . . . . . . 112 Configuration . . . . . . . . . . . . . . . . . . . .LogicalMessageContext .3. . . . . . . . . . . .1 One-way Operations . . . . . . . . . . . . .2 Deployment Model . . . . . . . . . . . . . . . 125 10. . . . .3 Processing Model . . . . . . . . . . . . . . . . . 134 11. . . . . . .2. . . . . . . . . . . . . .1. . . . . . . . . .1 SOAP mustUnderstand Processing . . . . 127 10. . .3 HTTP Support . . . . . . . .2 Exception Handling . . . . . . . . . . . . . . . . . . . . . . . . . . . . .2 Types of Handler . . . .3 SOAP Message Context . . .2 Programmatic Configuration . . . . . . . . . . . . . . . . . . .2 Processing Model . . 2007 . . . . . . . .1 9. . . . . . . . . . . . . 129 10. . . . . .1 HTTP . . . . . . . . . . . . . . . . . .4. . . . . . . . . . . . . . . . . . . . . .1 9. . . . . . . .4 SOAP Transport and Transfer Bindings .handler. . . . . . . .1 Exception Handling . . . . . . . . 134 11. .4. . . . . . . . . . . . . . . . . . . . . . . . . . .2. . . . . . 127 10. . . . . . . . . . .2 9. . . . . . . . . . . . . . . . . . . . . . . . . .3. . .ws. . . . . . . . . 129 10. . . . . . . . . . .3. . . . . . . . . . . .2 Processing Model . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .1. . . . . .3 Handler Lifecycle . 116 9. . . . . .4 Message Context . . . . .2. . . . . . . . . . . . . . . . . . . . . . . . . .

. . 2007 JAX-WS 2. . . . . . . . . . . . . . . . . . . . . 148 B. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .3 Changes since Public Draft . . . . . .5 Changes Since Early Draft 2 . . . . . . . . . . . . . .1 xiii .6 Changes Since Early Draft 1 . 143 B. . . . . . . . .4 Changes Since Early Draft 3 . . . . . . 145 B. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 147 B. . . . . .1 Changes since Final Draft . . . . . . . . . . . . . . . . . .2 Changes since Proposed Final Draft . . . . . . . . 148 Bibliography 151 May 7. . . . . . . . . . . . . . . . . . . . . . . . 144 B. . .A Conformance Requirements B Change Log 137 143 B. .

xiv

JAX-WS 2.1

May 7, 2007

Chapter 1

Introduction
XML[1] is a platform-independent means of representing structured information. XML Web Services use XML as the basis for communication between Web-based services and clients of those services and inherit XML’s platform independence. SOAP[2, 3, 4] describes one such XML based message format and “defines, using XML technologies, an extensible messaging framework containing a message construct that can be exchanged over a variety of underlying protocols.” WSDL[5] is “an XML format for describing network services as a set of endpoints operating on messages containing either document-oriented or procedure-oriented information.” WSDL can be considered the defacto service description language for XML Web Services. JAX-RPC 1.0[6] defined APIs and conventions for supporting RPC oriented XML Web Services in the Java™ platform. JAX-RPC 1.1[7] added support for the WS-I Basic Profile 1.0[8] to improve interoperability between JAX-RPC implementations and with services implemented using other technologies. JAX-WS 2.0 (this specification) is a follow-on to JAX-RPC 1.1, extending it as described in the following sections.

1.1

Goals

Since the release of JAX-RPC 1.0[6], new specifications and new versions of the standards it depends on have been released. JAX-WS 2.0 relates to these specifications and standards as follows: JAXB Due primarily to scheduling concerns, JAX-RPC 1.0 defined its own data binding facilities. With the release of JAXB 1.0[9] there is no reason to maintain two separate sets of XML mapping rules in the Java™ platform. JAX-WS 2.0 will delegate data binding-related tasks to the JAXB 2.0[10] specification that is being developed in parallel with JAX-WS 2.0. JAXB 2.0[10] will add support for Java to XML mapping, additional support for less used XML schema constructs, and provide bidirectional customization of Java ⇔ XML data binding. JAXWS 2.0 will allow full use of JAXB provided facilities including binding customization and optional schema validation. JAX-WS 2.1 requires JAXB 2.1[11] which is being developed in parallel with JAX-WS 2.1. SOAP 1.2 Whilst SOAP 1.1 is still widely deployed, it’s expected that services will migrate to SOAP 1.2[3, 4] now that it is a W3C Recommendation. JAX-WS 2.0 will add support for SOAP 1.2 whilst requiring continued support for SOAP 1.1. May 7, 2007 JAX-WS 2.1 1

Chapter 1. Introduction

WSDL 2.0 The W3C is expected to progress WSDL 2.0[12] to Recommendation during the lifetime of this JSR. JAX-WS 2.0 will add support for WSDL 2.0 whilst requiring continued support for WSDL 1.1. Note: The expert group for the JSR decided against this goal for this release . We will look at adding support in a future revision of the JAX-WS specification. WS-I Basic Profile 1.1 JAX-RPC 1.1 added support for WS-I Basic Profile 1.0. WS-I Basic Profile 1.1 is expected to supersede 1.0 during the lifetime of this JSR and JAX-WS 2.0 will add support for the additional clarifications it provides. A Metadata Facility for the Java Programming Language (JSR 175) JAX-WS 2.0 will define the use of Java annotations[13] to simplify the most common development scenarios for both clients and servers. Web Services Metadata for the Java Platform (JSR 181) JAX-WS 2.0 will align with and complement the annotations defined by JSR 181[14]. Implementing Enterprise Web Services (JSR 109) The JSR 109[15] defined jaxrpc-mapping-info deployment descriptor provides deployment time Java ⇔ WSDL mapping functionality. In conjunction with JSR 181[14], JAX-WS 2.0 will complement this mapping functionality with development time Java annotations that control Java ⇔ WSDL mapping. Web Services Security (JSR 183) JAX-WS 2.0 will align with and complement the security APIs defined by JSR 183[16]. JAX-WS 2.0 will improve support for document/message centric usage: Asynchrony JAX-WS 2.0 will add support for client side asynchronous operations. Non-HTTP Transports JAX-WS 2.0 will improve the separation between the XML message format and the underlying transport mechanism to simplify use of JAX-WS with non-HTTP transports. Message Access JAX-WS 2.0 will simplify client and service access to the messages underlying an exchange. Session Management JAX-RPC 1.1 session management capabilities are tied to HTTP. JAX-WS 2.0 will add support for message based session management. JAX-WS 2.0 will also address issues that have arisen with experience of implementing and using JAX-RPC 1.0: Inclusion in J2SE JAX-WS 2.0 will prepare JAX-WS for inclusion in a future version of J2SE. Application portability is a key requirement and JAX-WS 2.0 will define mechanisms to produce fully portable clients. Handlers JAX-WS 2.0 will simplify the development of handlers and will provide a mechanism to allow handlers to collaborate with service clients and service endpoint implementations. Versioning and Evolution of Web Services JAX-WS 2.0 will describe techniques and mechanisms to ease the burden on developers when creating new versions of existing services.

2

JAX-WS 2.1

May 7, 2007

1.1 Relationship To JAXB JAX-WS describes the WSDL ⇔ Java mapping.2 Non-Goals The following are non-goals: Backwards Compatibility of Binary Artifacts Binary compatibility between JAX-RPC 1.3 Requirements 1.0 JAX-WS 2..g.1 encoding optional and defer description of it to JAX-RPC 1.1 encoding is supported in JAX-RPC 1.2 Encoding[4] is optional in SOAP 1. This capability is provided independently by JAXR[17].0 will maintain the capability to selectively disable data binding to provide an XML based fragment suitable for use as input to alternative data binding technologies. Service Registration and Discovery It is not a goal of JAX-WS 2.0 implementation runtimes.2 and JAX-WS 2.3.g.3. Therefore JAX-WS 2.0. either in the RPC or document style.1[5] as clarified by the WS-I Basic Profile[8. the JAXB binding language) are incorporated into JAX-WS..g.1 3 . Support for the SOAP 1. Instead. to avoid name collisions and to be able to control schema validation on serialization and deserialization.0 and JAXB 1. It is not a goal to support JAX-WS 2.0.0 on Java versions prior to J2SE 5. However.x client source code is not a goal.0 relies on many of the Java language features added in J2SE 5. Pluggable data binding JAX-WS 2.2. SOAP Encoding Support Use of the SOAP encoding is essentially deprecated in the web services community. JAX-WS 2.0 will not add support for SOAP 1.1 but its support in JAX-WS 2. but data binding is delegated to JAXB[10]. the WS-I Basic Profile[8] excludes SOAP encoding. e.0 and 1. 18] May 7.1. literal usage is preferred. Generating source code that works with unmodified JAX-RPC 1. SOAP 1.0 will make support for SOAP 1.2 Standardized WSDL Mapping WSDL is the de-facto service description language for XML Web Services. 1. The specification must specify a standard WSDL ⇔ Java mapping..2 encoding.x and JAX-WS 2. 2007 JAX-WS 2. Backwards Compatibility of Generated Artifacts JAX-RPC 1. it is not a goal to provide a plug-in API to allow other types of data binding technologies to be used in place of JAXB. JAX-WS is required to be able to influence the JAXB binding. Support for Java versions prior to J2SE 5.0 runs counter to the goal of delegation of data binding to JAXB. The specification must clearly designate where JAXB rules apply to the WSDL ⇔ Java mapping without reproducing those rules and must describe how JAXB capabilities (e.0 will defer data binding to JAXB[10].0 bind XML to Java in different ways. e. Non-Goals 1. The following versions of WSDL must be supported: • WSDL 1.0 to describe registration and discovery of services via UDDI or ebXML RR.1.

4 JAX-WS 2.5 Standardized Transport Bindings The specification must describe standard bindings to the following protocols: • HTTP/1.2[3.3. Introduction The standardized WSDL mapping will describe the default WSDL ⇔ Java mapping.4 Standardized Protocol Bindings The specification must describe standard bindings to the following protocols: • SOAP 1.1[2] as clarified by the WS-I Basic Profile[8. 1.3. The default mapping may be overridden using customizations as described below. Handler Context The framework will describe a mechanism for communicating properties between handlers and the associated service clients and service endpoint implementations.6 Standardized Handler Framework The specification must include a standardized handler framework that describes: Data binding for handlers The framework will offer data binding facilities to handlers and will support handlers that are decoupled from the SAAJ API.Chapter 1. The specification must not prevent non-standard bindings to other transports. 1. Unified Response and Fault Handling The handleResponse and handleFault methods will be unified and the the declarative model for handlers will be improved.1[19]. 2007 .1. 1. The annotations will support mapping from WSDL 1.3 Customizable WSDL Mapping The specification must provide a standard way to customize the WSDL ⇔ Java mapping. The following customization methods will be specified: Java Annotations In conjunction with JAXB[10] and JSR 181[14].1 May 7.3. the specification will define a set of standard annotations that may be used in Java source files to specify the mapping from Java artifacts to their associated WSDL components. 4] The specification must not prevent non-standard bindings to other protocols. The annotations will support mapping to WSDL 1. 1.3. the specification will define a set of standard annotations that may be used either within WSDL documents or as in an external form to specify the mapping from WSDL components to their associated Java artifacts. The specification must describe the precedence rules governing combinations of the customization methods. WSDL Annotations In conjunction with JAXB[10] and JSR 181[14].1. 18] • SOAP 1.

1. 1.4.. The facilities must allow new versions of an interface to be deployed whilst maintaining compatibility for existing clients.2 Message Logging A developer wishes to log incoming and outgoing messages for later analysis. 2007 JAX-WS 2. 1. 1.1 Reliable Messaging Support A developer wishes to add support for a reliable messaging SOAP feature to an existing service endpoint.1. The support takes the form of a JAX-WS handler.1.4. Both forms of invocation will support a user configurable timeout period.3.3. 1.3. checking messages using the WS-I testing tools.g.1 Handler Framework 1.1. May 7.9 Session Management The specification must describe a standard session management mechanism including: Session APIs Definition of a session interface and methods to obtain the session interface and initiate sessions for handlers and service endpoint implementations. Use Cases 1.8 Standardized Synchronous and Asynchronous Invocation There must be a detailed description of the generated method signatures to support both asynchronous and synchronous method invocation in stubs generated by JAX-WS.4 Use Cases 1.4. 1. HTTP based sessions The session management mechanism must support HTTP cookies and URL rewriting.7 Versioning and Evolution The specification must describe techniques and mechanisms to support versioning of service endpoint interfaces.1 5 . SOAP based sessions The session management mechanism must support SOAP based session information. e.4.4.3 WS-I Conformance Checking A developer wishes to check incoming and outgoing messages for conformance to one or more WS-I profiles at runtime.

‘SHOULD’.1.xmlsoap.w3.Chapter 1.’ represent application or context-dependent URIs (see RFC 2396[19]).1: Prefixes and Namespaces used in this specification. Introduction 1.com/.w3.0[24] schema xsd wsdl soap jaxb jaxws wsa http://www. ‘SHOULD NOT’.org/2001/XMLSchema http://schemas. Prefix env Namespace http://www. Note that the choice of any namespace prefix is arbitrary and not semantically significant (see XML Infoset[21]). conformance requirements are called out from the main text as follows: ♦ Conformance (Example): Implementations MUST do something.com/xml/ns/jaxb http://java. } } Non-normative notes are formatted as shown below.org/2003/05/soap-envelope.org/...sun. ‘MUST NOT’.1: Example Java Code 1 2 3 4 5 6 7 package com. and ‘OPTIONAL’ in this document are to be interpreted as described in RFC 2119[20].w3.org/2003/05/soap-envelope Notes A normative XML Schema[22.example. For convenience. notes and sections explicitly marked as ‘Non-Normative’. This specification uses a number of namespace prefixes throughout.out. public class Hello { public static void main(String args[]) { System.5 Conventions The keywords ‘MUST’. ‘MAY’. ‘SHALL NOT’.. 23] document for the http://www.sun.org/wsdl/soap/ http://java. ‘REQUIRED’.w3. A list of all such conformance requirements can be found in appendix A.org/2005/08/addressing Table 1. The namespace of the XML schema[22.org/2003/05/soap-envelope namespace can be found at http://www. Java code and XML fragments are formatted as shown in figure 1.xmlsoap.1: Figure 1. Namespace names of the general form ‘http://example. 6 JAX-WS 2.com/xml/ns/jaxws http://www. with the exception of examples.org/wsdl/ http://schemas. 23] specification The namespace of the WSDL schema[5] The namespace of the WSDL SOAP binding schema[22.. 23] The namespace of the JAXB [9] specification The namespace of the JAX-WS specification The namespace of the WS-Addressing 1. ‘SHALL’.w3. they are listed in Table 1. Note: This is a note.println("Hello World"). 2007 .’ and ‘http://example. All parts of this specification are normative. ‘RECOMMENDED’.1 May 7.hello.

Inc. Inc) Daniel Kulp (IONA Technologies PLC) Sunil Kunisetty (Oracle) Changshin Lee (Tmax Soft. Mark Hapner. Expert Group Members 1. Eduardo Pelegri-Llopart.) Jim Frost (Art Technology Group Inc) Alastair Harwood (Cap Gemini) Marc Hadley (Sun Microsystems. Rama Pulavarthi. Vivek Pandey. Inc) Sebastien Sahuc (Intalio. Jones (Developmentor) Anish Karmarkar (Oracle) Toshiyuki Kimura (NTT Data Corp) Jim Knutson (IBM) Doug Kohlert (Sun Microsystems. Inc. Bill Shannon.6 Expert Group Members The following people have contributed to this specification: Chavdar Baikov (SAP AG) Russell Butek (IBM) Manoj Cheenath (BEA Systems) Shih-Chang Chen (Oracle) Claus Nyhus Christensen (Trifork) Ugo Corda (SeeBeyond Technology Corp) Glen Daniels (Sonic Software) Alan Davies (SeeBeyond Technology Corp) Thomas Diesler (JBoss. May 7. 2007 JAX-WS 2. and Kathy Walsh (all from Sun Microsystems) have provided invaluable technical input to the JAX-WS 2. Arun Gupta. Santiago Pericas-Geertsen.1. Inc) Carlo Marcoli (Cap Gemini) Srividya Natarajan (Nokia Corporation) Sanjay Patil (SAP AG) Greg Pavlik (Oracle) Bjarne Rasmussen (Novell. Jitendra Kotamraju. Inc.6.) Kevin R. John (WebMethods Corporation) Mark Stewart (ATG) Neal Yin (BEA Systems) Brian Zotter (BEA Systems) 1.) Rahul Sharma (Motorola) Rajiv Shivane (Pramati Technologies) Richard Sitze (IBM) Dennis M.1 7 . Sosnoski (Sosnoski Software) Christopher St. Paul Sandoz.0 specification. Graham Hamilton.7 Acknowledgements Robert Bissett.

Introduction 8 JAX-WS 2.Chapter 1. 2007 .1 May 7.

1 to Java Mapping This chapter describes the mapping from WSDL 1.6 describes binding dependent mappings. ♦ Conformance (Definitions mapping): In the absence of customizations. the Java package name is mapped from the value of a wsdl:definitions element’s targetNamespace attribute using the algorithm defined by JAXB[10].1 9 .1 construct to the equivalent Java construct. In WSDL 1. this specification requires generated Java classes and interfaces to be annotated with the Web service annotations described in section 7. In order to enable annotations to be used at runtime for method dispatching and marshalling. 2007 JAX-WS 2.11. Bindings impact the mapping between WSDL elements used in the abstract port type definition and Java method parameters. May 7.1. This mapping is used when generating web service interfaces for clients and endpoints from a WSDL 1. the separation between the abstract port type definition and the binding to a protocol is not complete. ♦ Conformance (Annotations on generated classes): The values of all the properties of all the generated annotations MUST be consistent with the information in the source WSDL document and the applicable external binding files.3) or an external binding file (see section 8. as well as the customizations embedded in them and those specified via any external binding files.1 to Java mapping using the JAX-WS binding language defined in chapter 8. An application MAY customize the mapping using embedded binding declarations (see section 8. The annotations present on a generated class MUST faithfully reflect the information in the WSDL document(s) that were given as input to the mapping process. Section 2.1 support): Implementations MUST support mapping WSDL 1. A wsdl:definitions element and its associated targetNamespace attribute is mapped to a Java package. ♦ Conformance (Customization required): Implementations MUST support customization of the WSDL 1.Chapter 2 WSDL 1. The following sections describe the default mapping from each WSDL 1. ♦ Conformance (WSDL 1. this algorithm is used to map the value of a wsdl:definitions element’s targetNamespace attribute to a Java package name. 2.1 description. By default. JAXB[10] (see appendix D) defines a standard mapping from a namespace URI to a Java package name.1 to Java.1 to Java.1 Definitions A WSDL document has a root wsdl:definitions element.4).

1[18] defined mechanisms (See R2001. ♦ Conformance (WSDL and XML Schema import directives): Implementations MUST support the WS-I Basic Profile 1. JAX-WS specifies the mapping to Java of the extensibility elements and attributes defined for the SOAP and MIME bindings. ♦ Conformance (Optional WSDL extensions): An implementation MAY support mapping of additional WSDL extensibility elements and attributes not described in JAX-WS. implementations should support WSDL that uses the WSDL and XML Schema import directives.1 allows extension elements and attributes to be added to many of its constructs.xml. and R2003) for use of WSDL and XML Schema import directives.Chapter 2. An application MAY customize this mapping using the jaxws:class binding declaration defined in section 8.1.xml.1 Extensibility WSDL 1. ♦ Conformance (javax. No specific authoring style is required for the input WSDL document.jws. JAX-WS does not address mapping of any other extensibility elements or attributes and does not provide a standard extensibility framework though which such support could be added in a standard way.jws. 2.bind.1 for a description of wsdl:definitions mapping).WebService required): A mapped SEI MUST be annotated with a javax. the name of an SEI MUST be the value of the name attribute of the corresponding wsdl:portType element mapped according to the rules described in section 2. ♦ Conformance (javax. A Java interface mapped from a wsdl:portType is called a Service Endpoint Interface or SEI for short. Note that such support may limit interoperability and application portability. WSDL 1.1 May 7. ♦ Conformance (SEI naming): In the absence of customizations. 2. 10 JAX-WS 2. 2007 .2.WebService annotation.bind.XmlSeeAlso required): An SEI generated from a WSDL that defines types not directly referenced by the Port MUST contain the javax.XmlSeeAlso annotation with all of the additional types referenced either directly or indirectly.7. R2002. The javax.1. A wsdl:portType element is mapped to a Java interface in the package mapped from the wsdl:definitions element (see section 2.1 to Java Mapping An application MAY customize this mapping using the jaxws:package binding declaration defined in section 8.8. Future versions of JAX-WS might add additional support for standard extensions as these become available.xml.2 Port Type A WSDL port type is a named set of abstract operation definitions. A WSDL may define additional types via type substitution that are not referenced by a service directly but may still need to be marshalled by JAX-WS.XmlSeeAlso annotation from JAXB is used on the generated SEI to specify any additional types from the WSDL.bind.7.

7. ♦ Conformance (Method naming): In the absence of customizations. C.3. } package example2.WebMethod annotation.jws.8.ObjectFactory. The annotation MAY be omitted if all its properties would have the default values. 2007 JAX-WS 2..3.1 11 .1: Directly and indirectly @XmlSeeAlso annotated SEI Figure 2.. public class C extends A { . Operation 1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 // Types generated when importing WSDL package example. see section 2. the name of a mapped Java method MUST be the value of the name attribute of the wsdl:operation element mapped according to the rules described in section 2. The WS-I Basic Profile[18] R2304 requires that operations within a wsdl:portType have unique values for their name attribute so mapping of WS-I compliant WSDL descriptions will not generate Java interMay 7.bind. ♦ Conformance (javax. example2. 2.xml.1 does not support port type inheritance so each generated SEI will contain methods for all operations in the corresponding port type.2.3 Operation Each wsdl:operation in a wsdl:portType is mapped to a Java method in the corresponding Java service endpoint interface. } package example1. An SEI contains Java methods mapped from the wsdl:operation child elements of the corresponding wsdl:portType.class.class..WebMethod required): A mapped Java method MUST be annotated with a javax.3 for further details on wsdl:operation mapping. WSDL 1..jws. This figures shows some of the types that may have been created while importing a WSDL and the different approaches to annotating the SEI. } // Directly annotated SEI with classes B and C @WebService @XmlSeeAlso({B. } Figure 2.class}) public interface MyService { public A echo(A a).class}) public interface MyService { public A echo(A a)..ObjectFactory..XmlSeeAlso. public class B extends A { .1 shows how an SEI can be annotated with javax. public class A { . An application MAY customize this mapping using the jaxws:method binding declaration defined in section 8. } // Indirectly annotated SEI using generated JAXB ObjectFatories @XmlSeeAlso({example1.

jws. The annotation MAY be omitted if all its properties would have the default values (i. Parameters of an SEI method MUST contain the appropriate JAXB annotations to assure that the proper 12 JAX-WS 2. for backwards compatibility. ♦ Conformance (Using javax.5). ♦ Conformance (Transmission primitive support): An implementation MUST support mapping of operations that use the one-way and request-response transmission primitives. A JAXB annotation on the method is used to specify the binding of a methods return type while an annotation on the parameter specifies the binding of that parameter.jws. 2. ♦ Conformance (Using javax.1 Message and Part Each wsdl:operation refers to one or more wsdl:message elements via child wsdl:input.jws. WSDL 1.jws.3. In order to remove these ambiguities. Note that the binding of a port type can affect the mapping of that port type to Java. see section 2.6 for details.jws. document/literal/wrapped).WebResult annotation. output.OneWay): A Java method mapped from a one-way operation MUST be annotated with a javax. Fault messages are mapped to application specific exceptions (see section 2. If the style is rpc or if the style is Document and the parameter style is BARE then the partName element of javax. ♦ Conformance (use of JAXB annotations): An SEI method MUST contain the appropriate JAXB annotations to assure that the proper XML infoset is used when marshalling/unmarshalling the return type. JAX-WS supports operation name overloading provided the overloading does not cause conflicts (as specified in the Java Language Specification[25]) in the mapped Java service endpoint interface declaration. encoding and parameter style.WebResult): Generated Java methods MUST be annotated with a javax. Mapping of notification and solicit-response operations is out of scope. occasionally ambiguities occur on what XML infoset should be used to represent a method’s return value or parameters. Each operation can specify one input message.SOAPBinding annotation describing the choice of style. JAXB annotations may need to be generated on methods and method parameters to assure that the return value and the parameters are marshalled with the proper XML infoset.jws. The two mapping styles are described in the following subsections.e. and fault messages for the operation respectively. zero or one output message. 2007 .1 to Java Mapping faces with overloaded methods. If the style is rpc or if the style is Document and the parameter style is BARE then the partName element of javax.WebParam): Generated Java method parameters MUST be annotated with a javax.OneWay annotation.1 May 7. no JAXB annotations are needed. ♦ Conformance (Using javax. If the default XML infoset for the return type or parameters correctly represents the XML infoset.WebParam MUST refer to the wsdl:part name of the parameter.Chapter 2.jws. and zero or more fault messages.SOAPBinding): An SEI mapped from a port type that is bound using the WSDL SOAP binding MUST be annotated with a javax. The annotation MAY be omitted if all its properties would have the default values.jws. When generating an SEI from WSDL and XML schema.WebResult MUST refer to the wsdl:part name of the parameter. The contents of input and output messages are mapped to Java method parameters using two different styles: non-wrapper style and wrapper style. However. and wsdl:fault elements that describe the input.WebParam annotation.jws. wsdl:output. ♦ Conformance (Using javax.jws.

in/out The message part is mapped to a method parameter using a holder class.annotation. out The message part is mapped to a method parameter using a holder class (see section 2. message parts are mapped to Java parameters according to their classification as follows: in The message part is mapped to a method parameter.3.3.XmlJavaTypeAdapter.XmlAttachementRef.annotation.3. Using non-wrapper style.xml.3.annotation.XmlList. javax.3) or is mapped to the method return type. out The message part is present only in the operation’s output message.1. Section 2. the name of a mapped Java method parameter MUST be the value of the name attribute of the wsdl:part element mapped according to the rules described in sections 2.3.3.1.8 and 2.bind.XmlMimeType and javax.1.xml. javax.1 13 .xml.8.adapters.2 Wrapper Style A WSDL operation qualifies for wrapper style mapping only if the following criteria are met: (i) The operation’s input and output messages (if present) each contain only a single part (ii) The input message part refers to a global element declaration whose localname is equal to the operation name (iii) The output message (if present) part refers to a global element declaration (iv) The elements referred to by the input and output message (if present) parts (henceforth referred to as wrapper elements) are both complex types defined using the xsd:sequence compositor May 7. 2007 JAX-WS 2.7.xml. An application MAY customize this mapping using the jaxws:parameter binding declaration defined in section 8. Message parts are classified as follows: in The message part is present only in the operation’s input message. in/out The message part is present in both the operation’s input message and output message.bind. Two parts are considered equal if they have the same values for their name attribute and they reference the same global element or type.2 defines rules that govern the ordering of parameters in mapped Java methods and identification of the part that is mapped to the method return type. Operation XML infoset is used when marshalling/unmarshalling the parameters of the method.2. 2. ♦ Conformance (Non-wrapped parameter naming): In the absence of any customizations.1 Non-wrapper Style A wsdl:message is composed of zero or more wsdl:part elements.bind. The set of JAXB annotations that MUST be supported are: javax.bind. 2.

see section 2. The annotation MAY be omitted if all its properties would have the default values. Using wrapper style.RequestWrapper): If wrapper style is used. An application MAY customize this mapping using the jaxws:parameter binding declaration defined in section 8.ResponseWrapper annotation.8 and 2. generated Java methods MUST be annotated with a javax.xml. out The wrapper child is mapped to a method parameter using a holder class (see section 2. WSDL 1. generated Java methods MUST be annotated with a javax.ws.1 to Java Mapping (v) The wrapper elements only contain child elements. furthermore. either by disabling wrapper style mapping. 14 JAX-WS 2. modifying the source WSDL or by specifying a customized parameter name mapping. the child elements of the wrapper element (henceforth called wrapper children) are mapped to Java parameters. xsd:choice. 2007 . The mapping depends on the classification of the wrapper child as follows: in The wrapper child is mapped to a method parameter.1 May 7. the name of a mapped Java method parameter MUST be the value of the local name of the wrapper child mapped according to the rules described in sections 2. wrapper children are classified as follows: in The wrapper child is only present in the input message part’s wrapper element. in/out The wrapper child is present in both the input and output message part’s wrapper element. substitution groups (element references are not permitted) or attributes.xml.8. In some cases use of the wrapper style mapping can lead to undesirable Java method signatures and use of non-wrapper style mapping would be preferred.xml.7.xml.3).3. Two wrapper children are considered equal if they have the same local name. they MUST not contain other structures such as wildcards (element or attribute).ws. ♦ Conformance (Parameter name clash): If the mapping results in two Java parameters with the same name and one of those parameters is not mapped to the method return type. the same XML schema type and the same Java type after mapping (see section 2. ♦ Conformance (Using javax.3) or is mapped to the method return value. ♦ Conformance (Default mapping mode): Operations that do not meet the criteria above MUST be mapped using non-wrapper style.7.4 for XML Schema to Java type mapping rules). in/out The wrapper child is mapped to a method parameter using a holder class.Chapter 2. The annotation MAY be omitted if all its properties would have the default values.2.ResponseWrapper): If wrapper style is used. they MUST not be nillable. then this is reported as an error and requires developer intervention to correct.ws.3.3.ws. ♦ Conformance (Disabling wrapper style): An implementation MUST support use of the jaxws:enableWrapperStyle binding declaration to enable or disable the wrapper style mapping of operations (see section 8.RequestWrapper annotation. out The wrapper child is only present in the output message part’s wrapper element. ♦ Conformance (Wrapped parameter naming): In the absence of customization. ♦ Conformance (Using javax.1.

• Parameters that are mapped from wrapper children (wrapper style mapping only) are unlisted. otherwise the return type is void. 2007 JAX-WS 2. Wrapper style mapping If there is a single out wrapper child then it forms the method return type. Parameters mapped from out parts appear in the same order the corresponding parts appear in the output message. • Listed parameters appear first in the method signature in the order in which their corresponding parts are listed in the parameterOrder attribute. • Unlisted parameters either form the return type or follow the listed parameters • The return type is determined as follows: Non-wrapper style mapping Only parameters that are mapped from parts in the abstract output message may form the return type. parameters that are mapped from unlisted parts are unlisted.g.1 [18] requires that if the parameterOrder attribute is present then at most one part may be unlisted. Parameters mapped from in and in/out parts appear in the same order the corresponding parts appear in the input message. However. 2. otherwise it is unlisted.3. 2.1 15 .2 Parameter Order and Return Type A wsdl:operation element may have a parameterOrder attribute that defines the ordering of parameters in a mapped Java method as follows: • Message parts are either listed or unlisted. annotations are omitted.2. Operation 2. For readability.2.3 Example Figure 2. Parameters mapped from in and in/out wrapper children (wrapper style mapping only) appear in the same order as the corresponding elements appear in the wrapper. May 7. Parameters mapped from out wrapper children (wrapper style mapping only) appear in the same order as the corresponding wrapper children appear in the wrapper. otherwise the return type is void. Parameters that are mapped from listed parts are listed.1) do not qualify. if there is an out wrapper child with a local name of “return” then it forms the method return type.3. Note: R2305 in WS-I Basic Profile 1. 4. If the value of a wsdl:part element’s name attribute is present in the parameterOrder attribute then the part is listed. 3.3.2 shows a WSDL extract and the Java method that results from using wrapper and non-wrapper mapping styles. the algorithm outlined in this section supports WSDLs that do not conform with this requirement.1. section 2. • Unlisted parameters that do not form the return type follow the listed parameters in the following order: 1. If there is a single unlisted out part in the abstract output message then it forms the method return type.6. parts from other messages (see e. • Parameters that are mapped from message parts are either listed or unlisted.

// wrapper style mapping void setLastTradePrice(String tickerSymbol. Figure 2.WSDL extract --> <types> <xsd:element name="setLastTradePrice"> <xsd:complexType> <xsd:sequence> <xsd:element name="tickerSymbol" type="xsd:string"/> <xsd:element name="lastTradePrice" type="xsd:float"/> </xsd:sequence> </xsd:complexType> </xsd:element> <xsd:element name="setLastTradePriceResponse"> <xsd:complexType> <xsd:sequence/> </xsd:complexType> </xsd:element> </types> <message name="setLastTradePrice"> <part name="setLastTradePrice" element="tns:setLastTradePrice"/> </message> <message name="setLastTradePriceResponse"> <part name="setLastTradePriceResponse" element="tns:setLastTradePriceResponse"/> </message> <portType name="StockQuoteUpdater"> <operation name="setLastTradePrice"> <input message="tns:setLastTradePrice"/> <output message="tns:setLastTradePriceResponse"/> </operation> </portType> // non-wrapper style mapping SetLastTradePriceResponse setLastTradePrice( SetLastTradePrice setLastTradePrice). WSDL 1.Chapter 2.1 to Java Mapping 1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 <!-. 2007 . float lastTradePrice).2: Wrapper and non-wrapper mapping styles 16 JAX-WS 2.1 May 7.

7.ws. a client side asynchronous mapping is also supported. Response extends Future<T> to provide asynchronous result polling capabilities.lang.1 Standard Asynchronous Interfaces The following standard interfaces are used in the asynchronous operation mapping: javax. ♦ Conformance (Asynchronous mapping required): An implementation MUST support the asynchronous mapping.Holder<T>.3.Response A generic interface that is used to group the results of a method invocation with the response context.3. Operation 2.1 JSR-181 currently does not define annotations that can be used to mark a method as being asynchronous. Editors Note 2. It is expected that the asynchronous mapping will be useful in some but not all cases and therefore generation of the client side asynchronous methods should be optional at the users discretion. 2. JAX-WS defines a generic holder class (javax.3 to enable and disable the asynchronous mapping.1 17 . javax. May 7.2 Operation Each wsdl:operation is mapped to two additional methods in the corresponding service endpoint interface: Polling method A polling method returns a typed Response<ResponseBean> that may be polled using methods inherited from Future<T> to determine when the operation has completed and to retrieve the results.g..xml.Integer>.2. xsd:int to int) are instead mapped to a Holder whose type parameter is bound to the Java wrapper class corresponding to the primitive type.g. They provide a mutable wrapper for otherwise immutable object references.AsyncHandler A generic interface that clients implement to receive results in an asyn- chronous callback.ws.3.xml. E. with the exception of a out part that has been mapped to the method’s return type.3.3 Holder Class Holder classes are used to support out and in/out parameters in mapped method signatures.4 Asynchrony In addition to the synchronous mapping of wsdl:operation described above. ♦ Conformance (Asynchronous mapping option): An implementation MUST support use of the jaxws:enableAsyncMapping binding declaration defined in section 8.xml..Holder<T>) that can be used for any Java class.ws. 2.4. See below for further details on ResponseBean.xml. an out or in/out parameter whose XML data type would normally be mapped to a Java int is instead mapped to Holder<java.3.ws.4. Parameters whose XML data type would normally be mapped to a Java primitive type (e. 2. 2007 JAX-WS 2. ♦ Conformance (Use of Holder): Implementations MUST map out and in/out method parameters using javax.

Chapter 2.4.4. see section 2.3.8 and 2. the name of the polling and callback methods MUST be the value of the name attribute of the wsdl:operation suffixed with “Async” mapped according to the rules described in sections 2. An application MAY customize this mapping using the jaxws:method binding declaration defined in section 8.8.3.8 and 2.3.1.get() has no standard type. out The part or wrapper child is mapped to a property of the response bean (see below).1.8.1. 2. ♦ Conformance (Asynchronous parameter naming): The name of the method parameter for the callback handler MUST be “asyncHandler”. The global element declaration is formed as follows (in order of preference): • If the operation’s output message contains a single part and that part refers to a global element declaration then use the referenced global element.5.1. 2.7.1 to Java Mapping Callback method A callback method takes an additional final parameter that is an instance of a typed AsyncHandler<ResponseBean> and returns a wildcard Future<?> that may be polled to determine when the operation has completed. in/out The part or wrapper child is mapped to a method parameter (no holder class) and to a property of the response bean. Errors that occur during the invocation are reported when the client attempts to retrieve the results of the operation. ♦ Conformance (Asynchronous method naming): In the absence of customizations.1 May 7.3 Message and Part The asynchronous mapping supports both wrapper and non-wrapper mapping styles. Client code should not attempt to cast the object to any particular type as this will result in non-portable behavior. ♦ Conformance (Response bean naming): In the absence of customizations. see section 2. the name of a response bean MUST be the value of the name attribute of the wsdl:operation suffixed with “Response” mapped according to the rules described in sections 2. The object returned from Future<?>.3.4.4 Response Bean A response bean is a mapping of an operation’s output message. an implementation MUST throw a WebServiceException1. WSDL 1. A response bean is mapped from a global element declaration following the rules described in section 2. 1 18 JAX-WS 2. but differs in how it maps out and in/out parts or wrapper children: in The part or wrapper child is mapped to a method parameter as described in section 2.3.4. 2007 .8. it contains properties for each out and in/out message part or wrapper child. ♦ Conformance (Failed method invocation): If there is any error prior to invocation of the operation. Parameter name collisions require user intervention to correct.

2.5 describes the mapping.4. StockQuote quoteService = (StockQuote)service. • Asynchronous polling use.concurrent.. a Response instance throws an ExecutionException whose cause is set to an instance of the service specific exception mapped from the corresponding WSDL fault.4. 2.3.4). 2007 JAX-WS 2.3 shows an example of the asynchronous operation mapping.7 Usage Examples • Synchronous use. int to Integer) to enable its use with Response. Each output message part is mapped to a child of the synthesized element as follows: – Each global element referred to by an output part is added as a child of the sequence.. ♦ Conformance (Asychronous fault cause): An ExecutionException that is thrown by the get method of Response as a result of a WSDL fault MUST have as its cause the service specific exception mapped from the WSDL fault.ExecutionException is thrown when a client attempts to retrieve the results of an asynchronous method invocation via the Response. Float quote = quoteService.5 Faults Mapping of WSDL faults to service specific exceptions is identical for both asynchronous and synchronous cases. mapped asynchronous methods do not throw service specific exceptions directly. Response is a static generic interface whose get method cannot throw service specific exceptions.get.6 Mapping Examples Figure 2.get method.concurrent. if the property is a Java primitive type then it is boxed using the Java wrapper type (e. Instead of throwing a service specific exception. Operation • Synthesize a global element declaration of a complex type defined using the xsd:sequence compositor. 1 2 3 Service service = .3. Instead a java.4. In this case. 2.3.2. otherwise the ProtocolException mapped from the WSDL fault (see 6.ExecutionException thrown when the client calls Response.util. section 2. if there is one.getPort(portName).3. ♦ Conformance (Asynchronous fault reporting): A WSDL fault that occurs during execution of an asynchronous method invocation MUST be mapped to a java.getPrice(ticker).1 19 . – Each part that refers to a type is added as a child of the sequence by creating an element in no namespace whose localname is the value of the name attribute of the wsdl:part element and whose type is the value of the type attribute of the wsdl:part element If the resulting response bean has only a single property then the bean wrapper should be discarded in method signatures.g. Note that the mapping uses Float instead of a response bean wrapper (GetPriceResponse) since the synthesized global element declaration for the operations output message (lines 17–24) maps to a response bean that contains only a single property.. May 7. However.util.

WSDL extract --> <message name="getPrice"> <part name="ticker" type="xsd:string"/> </message> <message name="getPriceResponse"> <part name="price" type="xsd:float"/> </message> <portType name="StockQuote"> <operation name="getPrice"> <input message="tns:getPrice"/> <output message="tns:getPriceResponse"/> </operation> </portType> <!-.Synthesized response bean element --> <xsd:element name="getPriceResponse"> <xsd:complexType> <xsd:sequence> <xsd:element name="price" type="xsd:float"/> </xsd:sequence> </xsd:complexType> </xsd:element> // synchronous mapping @WebService public interface StockQuote { float getPrice(String ticker).1 to Java Mapping 1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 <!-.Chapter 2.1 May 7. AsyncHandler<Float>). WSDL 1. } Figure 2. Response<Float> getPriceAsync(String ticker). Future<?> getPriceAsync(String ticker. } // asynchronous mapping @WebService public interface StockQuote { float getPrice(String ticker). 2007 .3: Asynchronous operation mapping 20 JAX-WS 2.

an implementation MUST use the JAXB class based mapping with generateValueClass set to true and generateElementClass set to false when mapping WSDL types to Java. E. JAX-WS strips any JAXBElement<T> wrapper off the type of a method parameter if the normal JAXB mapping would result in one2 .5.get().isDone()) { // do something while we wait } Float quote = response. a parameter that JAXB would map to JAXBElement<Integer> is instead be mapped to Integer.3. myPriceHandler).g... section 2.3. May 7.get().. StockQuote quoteService = (StockQuote)service. MyPriceHandler myPriceHandler = new MyPriceHandler(). ♦ Conformance (JAXB customization clash): To avoid clashes. • Asynchronous callback use. Response<Float> response = quoteService. The contents of a wsdl:types section is passed to JAXB along with any additional type or element declarations (e.1 21 .4 Types Mapping of XML Schema types to Java is described by the JAXB 2. StockQuote quoteService = (StockQuote)service. 2 JAXB maps an element declaration to a Java instance that implements JAXBElement. Types 1 2 3 4 5 6 7 Service service = . In addition. JAXB supports mapping XML types to either Java interfaces or classes.4. public void handleResponse(Response<Float> response) { Float price = response.1 specification[11].g.getPort(portName). 2007 JAX-WS 2.getPriceAsync(ticker).. E. 2.. // do something with the result } } Service service = ..g.. for ease of use. By default JAX-WS uses the class based mapping of JAXB but also allows use of the interface based mapping.getPriceAsync(ticker. if a user customizes the mapping. ♦ Conformance (JAXB class mapping): In the absence of user customizations. 1 2 3 4 5 6 7 8 9 10 11 12 class MyPriceHandler implements AsyncHandler<Float> { .4) required to map other WSDL constructs to Java. ♦ Conformance (JAXB customization use): An implementation MUST support use of JAXB customizations during mapping as detailed in section 8. while (!response... an implementation MUST NOT add the default class based mapping customizations. see section 2.4 defines an algorithm for synthesizing additional global element declarations to provide a mapping from WSDL operations to asynchronous Java method signatures.getPort(portName).. quoteService.2.

bind.xml.1 by default does not map wsa:EndpointReference to the javax.xml.Exception and contains the following methods: WrapperException(String message. Faults defined within the same service are equivalent if the values of their message attributes are equal. FaultBean faultInfo) A constructor where WrapperException is replaced with the name of the generated wrapper exception and FaultBean is replaced by the name of the generated fault bean. using the mapping described in section 2.ws.1 May 7.wsaddressing.xml. An application MAY customize this mapping using the jaxws:class binding declaration defined in section 8.W3CEndpointReference): Any schema element of the type wsa:EndpointReference MUST be mapped to javax. 2. 2. Multiple operations within the same service can define equivalent faults.ws.AttachmentUnmarshaller classes. 2007 . The contract between JAXB and an MTOM/XOP package processor is defined by the javax.ws. ♦ Conformance (javax.Marshaller). The global element declaration3 referred to by that part is mapped to a Java bean.8.1.xml.5 Fault A wsdl:fault element is mapped to a Java exception.Unmarshaller (resp.bind. A wsdl:fault element refers to a wsdl:message that contains a single part.ws.ws. ♦ Conformance (Fault equivalence): An implementation MUST map equivalent faults within a service to a single Java exception class. for JAX-WS developers to fully utilize the use of a wsa:EndpointReference. JAXB 2.4. the setAttachmentMarshaller method of javax.xml.1 to Java Mapping JAXB provides support for the SOAP MTOM[26]/XOP[27] mechanism for optimizing transmission of binary data types.Chapter 2.xml. WSDL 1.WebFault required): A mapped exception MUST be annotated with a javax.wsaddressing.4.7.xml. henceforth called a fault bean.bind.ws.W3CEndpointReference class.W3CEndpointReference. JAX-WS provides the MIME processing required to enable JAXB to serialize and deserialize MIME based MTOM/XOP packages.WebFault annotation.AttachmentMarshaller and javax. 3 WS-I Basic Profile[18] R2205 requires parts to refer to elements rather than types. the name of a mapped exception MUST be the value of the name attribute of the wsdl:message referred to by the wsdl:fault element mapped according to the rules in sections 2.bind.1 provides a standard customization that can be used to force this mapping.8 and 2. ♦ Conformance (Exception naming): In the absence of customizations.4. ♦ Conformance (javax. JAX-WS implementations MUST map the wsa:EndpointReference to javax.W3CEndpointReference. However.xml.lang.xml. A JAX-WS implementation can plug into it by registering its own AttachmentMarshaller and AttachmentUnmarshaller at runtime using the setAttachmentUnmarshaller method of javax.ws.wsaddressing. An implementation generates a wrapper exception class that extends java.xml.1 W3CEndpointReference JAXB 2. 22 JAX-WS 2.

where FaultBean is replaced by the name of the generated fault bean. Two wsdl:fault child elements of the same wsdl:operation that indirectly refer to the same global element declaration are considered to be equivalent since there is no interoperable way of differentiating between their serialized forms. FaultBean faultInfo. ♦ Conformance (Fault equivalence): At runtime an implementation MAY map a serialized fault into any equivalent Java exception.6.1 to Java mapping that may result from use of certain SOAP binding extensions. FaultBean getFaultInfo() Getter to obtain the fault information.6.6.1 Example Figure 2.1 specified extension elements for the WSDL SOAP and MIME bindings.2. see section 6. 2.1 protocol bindings.5. The WrapperException class is annotated using the WebFault annotation (see section 7. ♦ Conformance (Unbound message parts): To preserve the protocol independence of mapped operations. ♦ Conformance (Required WSDL extensions): An implementation MUST support mapping of the WSDL 1.2) to capture the local and namespace name of the global element mapped to the fault bean. cause. Instead an implementation MUST generate binding code that ignores in and in/out parameters mapped from unbound parts and that presents out parameters mapped from unbound parts as null. may be used to convey protocol specific fault information.2 SOAP Binding This section describes changes to the WSDL 1.6 Binding The mapping from WSDL 1. However. an implementation MUST NOT ignore unbound message parts when mapping from WSDL 1. 2. May 7.1. Throwable cause) A constructor where WrapperException is replaced with the name of the generated wrapper exception and FaultBean is replaced by the name of the generated fault bean.1 to Java is based on the abstract description of a wsdl:portType and its associated operations. 2. the binding of a port type to a protocol can introduce changes in the mapping – this section describes those changes in the general case and specifically for the mandatory WSDL 1.4. The last argument. 2. 2007 JAX-WS 2.1[28] recommends that all parts of a message be bound but does not require it.1 to Java. Binding WrapperException(String message.4 shows an example of the WSDL fault mapping described above.1 General Considerations R2209 in WS-I Simple SOAP Binding Profile 1.1 23 .

} FaultDetail getFaultInfo() {..1 May 7.1 to Java Mapping 1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 <!-.} } Figure 2...Chapter 2.WSDL extract --> <types> <xsd:schema targetNamespace=". Throwable cause) {.") class OperationException extends Exception { OperationException(String message.. FaultDetail faultInfo. WSDL 1.."> <xsd:element name="faultDetail"> <xsd:complexType> <xsd:sequence> <xsd:element name="majorCode" type="xsd:int"/> <xsd:element name="minorCode" type="xsd:int"/> </xsd:sequence> </xsd:complexType> </xsd:element> </xsd:schema> </types> <message name="operationException"> <part name="faultDetail" element="tns:faultDetail"/> </message> <portType name="StockQuoteUpdater"> <operation name="setLastTradePrice"> <input .../> <output .../> <fault name="operationException" message="tns:operationException"/> </operation> </portType> // fault mapping @WebFault(name="faultDetail".... FaultDetail faultInfo) {. 2007 . targetNamespace="..} OperationException(String message..4: Fault mapping 24 JAX-WS 2.

When mapped to a parameter.1 Header Binding Extension A soap:header element may be used to bind a part from a message to a SOAP header. JAXB rules are used to determine the Java type of May 7. This additional part does not affect eligibility for wrapper style mapping of the message bound by the soap:body (see section 2.3. ♦ Conformance (Duplicate headers in binding): When mapping.1 mime:content Message parts are mapped to method parameters as described in section 2. during unmarshalling. JAXB[10] describes the mapping from the WS-I defined wsiap:swaref schema type to Java and.6. Binding 2.3. As clarified by R2208 in WS-I Basic Profile 1. the part may belong to either the message bound by the soap:body or to a different message: • If the part belongs to the message bound by the soap:body then it is mapped to a method parameter as described in section 2.1 to Java mapping that results from its use. mime:content A binding construct that may be used to bind a message part to an attachment.0[8].6.1). 2.2. the additional part is always mapped using the non-wrapper style. Note that the order of headers in a SOAP message is independent of the order of soap:header elements in the WSDL binding – see R2751 in WS-I Basic Profile 1. an implemention MUST report an error if the binding of an operation includes two or more soap:header elements that would result in SOAP headers with the same qualified name. 2.6. Such a part is always mapped using the non-wrapper style. Use of the mime:content construct is outside the scope of JAXB mapping and the following subsection describes changes to the WSDL 1.3 MIME Binding The presence of a mime:multipartRelated binding extension element as a child of a wsdl:input or wsdl:output element in a wsdl:binding indicates that the corresponding messages may be serialized as MIME packages. there is more than one instance of a header whose qualified name is mapped to a method parameter.3. 2007 JAX-WS 2.1[18]. both based on use of the WSDL 1.2. it is not discussed further here. The WS-I Attachments Profile[29] describes two separate attachment mechanisms. since JAX-WS inherits this capability. ♦ Conformance (Duplicate headers in message): An implementation MUST generate a runtime error if.6.3 regardless of whether the part is bound to the SOAP message or to an attachment.3.1 MIME binding[5]: wsiap:swaRef A schema type that may be used in the abstract message description to indicate a reference to an attachment. the part is treated as an additional unlisted part for the purposes of the mapping described in section 2. This causes problems when two or more headers with the same qualified name are present in a message and one or more of those headers are bound to a method parameter since it is not possible to determine which header maps to which parameter.1 25 . • If the part belongs to a different message than that bound by the soap:body then it may optionally be mapped to an additional method parameter.

Such a part is always mapped using the non-wrapper style. ♦ Conformance (MIME part identification): An implementation MUST use the algorithm defined in the WS-I Attachments Profile[29] when generating the MIME Content-ID header field value for a part bound using mime:content.xml.7. When a part is bound using one or more mime:content elements4 and use of the additional metadata is enabled then the JAXB mapping is customized to use the most specific type allowed by the set of MIME types described for the part in the binding.8 and 2.5 shows an example WSDL and two mapped interfaces: one without using the mime:content metadata. However. 26 JAX-WS 2.3. 2. An application MAY customize the name of the generated service class using the jaxws:class binding declaration defined in section 8.0 specification [10] for details of the type mapping. when a message part is bound to a MIME part (using the mime:content element of the WSDL MIME binding) additional information is available that provides the MIME type of the data and this can optionally be used to narrow the default JAXB mapping.1 to Java Mapping message parts based on the XML schema type referenced by the wsdl:part. Note that in the latter the type of the claimPhoto method parameter is Image rather than the default byte[].1 May 7.xml.ws. The case where the parameter mode is INOUT and is bound to different mime bindings in the input and output messages using the mime:content element MUST also be treated in the same way as described above.Service class.Service (see section 4. ♦ Conformance (Service class naming): In the absence of customization. JAXB defines a mapping between MIME types and Java types. These parts are mapped using the non-wrapper style. 2007 . WSDL 1. the other using the additional metadata to narrow the binding. The part belongs to the message bound by the soap:body then it is mapped to a method parameter as described in section 2. ♦ Conformance (Use of MIME type information): An implementation MUST support using the jaxws:enableMIMEContent binding declaration defined in section 8. On the client side. a wsdl:service element is mapped to a generated service class that extends javax.3. 4 Multiple mime:content elements for the same part indicate a set of permissible alternate types.5 to enable or disable the use of the additional metadata in mime:content elements when mapping from WSDL to Java.7. the name of a generated service class MUST be the value of the name attribute of the wsdl:service element mapped according to the rules described in sections 2. Please refer to appendix H in the JAXB 2. ♦ Conformance (Service superclass required): A generated service class MUST extend the javax. A wsdl:port element describes a port type bound to a particular protocol (a wsdl:binding) that is available at particular endpoint address. Figure 2.1.7 Service and Port A wsdl:service is a collection of related wsdl:port elements.ws.1 for more information on the Service class).8. Parts bound to MIME using the mime:content WSDL extension are mapped as described in section 2.Chapter 2.7. ♦ Conformance (MIME type mismatch): On receipt of a message where the MIME type of a part does not match that described in the WSDL an implementation SHOULD throw a WebServiceException.

2007 JAX-WS 2. } Figure 2. byte claimPhoto[])...1 27 ."/> <wsdl:input> <mime:multipartRelated> <mime:part> <soapbind:body parts="body" use="literal"/> </mime:part> <mime:part> <mime:content part="ClaimPhoto" type="image/jpeg"/> <mime:content part="ClaimPhoto" type="image/gif"/> </mime:part> </mime:multipartRelated> </wsdl:input> </wsdl:operation> </wsdl:binding> // Mapped Java interface without mime:content metadata @WebService public interface ClaimPortType { public String sendClaim(ClaimDetail detail. Image claimPhoto). Service and Port 1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 <!-..WSDL extract --> <wsdl:message name="ClaimIn"> <wsdl:part name="body" element="types:ClaimDetail"/> <wsdl:part name="ClaimPhoto" type="xsd:base64Binary"/> </wsdl:message> <wsdl:portType name="ClaimPortType"> <wsdl:operation name="SendClaim"> <wsdl:input message="tns:ClaimIn"/> </wsdl:operation> </wsdl:portType> <wsdl:binding name="ClaimBinding" type="tns:ClaimPortType"> <soapbind:binding style="document" transport="."/> <wsdl:operation name="SendClaim"> <soapbind:operation soapAction=".2. } // Mapped Java interface using mime:content metadata @WebService public interface ClaimPortType { public String sendClaim(ClaimDetail detail.5: Use of mime:content metadata May 7.7..

.WebEndpoint required): The getPortName methods of generated service interface MUST be annotated with a javax.ws.getPort(.WebServiceClient required): A generated service class MUST be annotated with a javax. Class<T> SEI.WebServiceFeature and returns a proxy that implements the mapped service endpoint interface.) method passing it the port name.xml.equals sense) to the values specified in the mandatory WebServiceClient annotation on the generated service class itself.WebServiceClient annotation.ws. the latter is required to be annotated with javax.URL) and the service name (a javax.Object.WebServiceException on failure. features) method passing it the port name. For each port in the service. this Java identifier is then treated as a JavaBean property for the purposes of deriving the getPortName method name. the latter is required to be annotated with a javax.ws.0 mandates that two constructors be present on every generated service class.xml.xml.7. The annotation contains all the information necessary to locate a WSDL document and uniquely identify a wsdl:service inside it. ♦ Conformance (Failed getPort Method): A generated getPortName method MUST throw javax.net.8.ws.Chapter 2. ♦ Conformance: A generated service class MUST have a default (i.QName).xml. ♦ Conformance (javax.1 to Java Mapping In order to allow an implementation to identify the Web service that a generated service class corresponds to. The value of the port name MUST be equal to the value specified in the mandatory WebEndpoint annotation on the method itself. In order to enable an implementation to determine the wsdl:port that a port getter method corresponds to.xml. The method generated delegates to the Service.e.Service.ws. the SEI and the features. WebServiceFeature. zero-argument) public constructor..8. This constructor MUST call the protected constructor declared in javax. the generated client side service class contains the following methods.xml.xml.WebEndpoint annotation.xml.ws.namespace.xml. The value of PortName in the above is derived as follows: the value of the name attribute of the wsdl:port element is first mapped to a Java identifier according to the rules described in section 2. ♦ Conformance (javax.1 May 7.xml.lang.getPort(QName portName. passing as arguments the WSDL location and the service name.ws. 28 JAX-WS 2. JAX-WS 2. The value of the port name MUST be equal to the value specified in the mandatory WebEndpoint annotation on the method itself.WebEndpoint annotation.ws. features) One required method that takes a variable-length array of javax. ♦ Conformance: The implementation class MUST have a public constructor that takes two arguments. WSDL 1.WebServiceClient annotation. This constructor MUST call the protected constructor in javax.Service passing as arguments the WSDL location and the service name values with which it was invoked. An application MAY customize the name of the generated methods for a port using the jaxws:method binding declaration defined in section 8. the wsdl location (a java.. 2007 . The method generated delegates to the Service..ws. getPortName(WebServiceFeature. The values of the actual arguments for this call MUST be equal (in the java.ws. two for each port defined by the WSDL service and whose binding is supported by the JAX-WS implementation: getPortName() One required method that takes no parameters and returns a proxy that implements the mapped service endpoint interface...xml.

"StockQuoteHTTPPort"). 1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 <!-."StockQuoteHTTPPort"). QName serviceName) { super(wsdlLocation.getPort( new QName("http://example. 2007 JAX-WS 2.com/stocks.getPort( new QName("http://example. features).com/stocks".com/stocks".class. Service and Port 2.getPort( new QName("http://example.com/stocks"."StockQuoteSMTPPort").1 29 . StockQuoteProvider..class). "StockQuoteService")).Service { public StockQuoteService() { super(new URL("http://example.class.1 Example The following shows a WSDL extract and the resulting generated service class.2. features). } @WebEndpoint(name="StockQuoteSMTPPort") public StockQuoteProvider getStockQuoteSMTPPort() { return (StockQuoteProvider)super. features) return (StockQuoteProvider)super. features) return (StockQuoteProvider)super.wsdl").com/stocks". } @WebEndpoint(name="StockQuoteSMTPPort") public StockQuoteProvider getStockQuoteSMTPPort( WebServiceFeature. } @WebEndpoint(name="StockQuoteHTTPPort") public StockQuoteProvider getStockQuoteHTTPPort( WebServiceFeature. } public StockQuoteService(URL wsdlLocation. targetNamespace="http://example.getPort( new QName("http://example.7.com/stocks".class). } } May 7. StockQuoteProvider. StockQuoteProvider.com/stocks". wsdlLocation="http://example.xml."StockQuoteSMTPPort")..ws. new QName("http://example.wsdl") public class StockQuoteService extends javax.. } @WebEndpoint(name="StockQuoteHTTPPort") public StockQuoteProvider getStockQuoteHTTPPort() { return (StockQuoteProvider)super.WSDL extract --> <wsdl:service name="StockQuoteService"> <wsdl:port name="StockQuoteHTTPPort" binding="StockQuoteHTTPBinding"/> <wsdl:port name="StockQuoteSMTPPort" binding="StockQuoteSMTPBinding"/> </wsdl:service> // Generated Service Class @WebServiceClient(name="StockQuoteService"..7. serviceName). StockQuoteProvider.com/stocks.

1. Service class If a name collision occurs between two identifiers with different precedences.8. Exception class 4.8 XML Names Appendix C of JAXB 1.1 Name Collisions WSDL name scoping rules may result in name collisions when mapping from WSDL 1..BindingProvider (an interface that proxies are required to implement. If a name collision occurs between a mapped Java method and a method in javax. StockQuoteProvider is the service endpoint interface mapped from the WSDL port type for both referenced bindings.0[9] defines a mapping from XML names to Java identifiers. Exception class The suffix “ Exception” is added to the class name. Service endpoint interface 2. JAX-WS uses this mapping to convert WSDL identifiers to Java identifiers with the following modifications and additions: Method identifiers When mapping wsdl:operation names to Java method identifiers. 2. E.1 to Java.Chapter 2. 30 JAX-WS 2. If a name collision occurs between two identifiers with the same precedence. Instead the first word in the word-list has its first character converted to lower case. WSDL 1. the first word in the word-list has its first character converted to lower case. the get or set prefix is not added. Clashes with Java language reserved words are reported as errors and require use of appropriate customizations to fix the clash. The order of precedence for name collision resolution is as follows (highest to lowest).g. 2007 . the prefix “ ” is added to the mapped method.1 May 7.ws.1 to Java Mapping In the above. Service class The suffix “ Service” is added to the class name.2). this is reported as an error and requires developer intervention to correct. The error may be corrected either by modifying the source WSDL or by specifying a customized name mapping. see section 4. the lower precedence item has its name changed as follows: Non-exception Java class The suffix “ Type” is added to the class name. Parameter identifiers When mapping wsdl:part names or wrapper child local names to Java method parameter identifiers. Non-exception Java class 3.xml. This section defines rules for resolving such name collisions. 2. a port type and a service are both mapped to Java classes but WSDL allows both to be given the same name.

jws.1 Name Collisions WS-I Basic Profile 1. The wsdl:definitions element acts as a container for other WSDL elements that together form the WSDL description of the constructs in the corresponding Java package. Java identifiers MUST be mapped to XML names using the algorithm defined in appendix B of SOAP 1.1 31 .WebMethod annotation to disambiguate overloaded Java method names when mapped to WSDL. This mapping is used when generating web service endpoints from existing Java interfaces.1. 3.1 Java Names ♦ Conformance (Java identifier mapping): In the absence of annotations described in this specification.1 artifact.2 Package A Java package is mapped to a wsdl:definitions element and an associated targetNamespace attribute. ♦ Conformance (Method name disambiguation): An implementation MUST support the use of the javax. An application MAY customize the mapping using the annotations defined in section 7.2 Part 2[4]. 3.0[8] (see R2304) requires operations within a wsdl:portType to be uniquely named – support for customization of the operation name allows this requirement to be met when a Java SEI contains overloaded methods.1 support): Implementations MUST support mapping Java to WSDL 1.1 mapping.Chapter 3 Java to WSDL 1. The following sections describe the default mapping from each Java construct to the equivalent WSDL 1.1 Mapping This chapter describes the mapping from Java to WSDL 1.1. A default value for the targetNamespace attribute is derived from the package name as follows: May 7.1. ♦ Conformance (Standard annotations): An implementation MUST support the use of annotations defined in section 7 to customize the Java to WSDL 1. ♦ Conformance (WSDL 1. 2007 JAX-WS 2. 3.

In pratice. For mapping purposes.example. 2007 .WebService annotation the Java package name MUST be mapped to the value of the wsdl:definitions element’s targetNamespace attribute using the algorithm defined above. The order of the tokens is reversed. Otherwise.WebService annotated classes to implicit service endpoint interfaces.WebMethod annotation but their declaring class has a javax. They are not annotated with the javax. ♦ Conformance (Class mapping): An implementation MUST support the mapping of javax.1) MAY be used to specify the target namespace to use for a Web service and MUST be used for classes or interfaces in no package.jws.3 Class A Java class (not an interface) annotated with a javax. 2. 3.jws. and R2003) on usage of WSDL and XML Schema import directives. ♦ Conformance (Package name mapping): The javax. then the interface referred by this element is for all purposes the SEI associated with the class. a class annotated with javax. In the absence of a javax.jws. The value of the targetNamespace attribute is obtained by concatenating “http://”to the list of tokens separated by “ . The package name is tokenized using the “. R2002. For mapping purposes. As defined by JSR 181.g.11.ws” would be mapped to the target namespace “http://ws. this implicit SEI and its methods are considered to be annotated with the same Web service-related annotations that the original class and its methods have. ♦ Conformance (WSDL and XML Schema import directives): Generated WSDL MUST comply with the WS-I Basic Profile 1. Java to WSDL 1. They are annotated with the javax.example. E.WebService annotation (see section 7. the Java package “com.jws. implementations are free to generate WSDL that uses the WSDL and XML Schema import directives. 2.” character as a delimiter. this class must be a top level class or a static inner class.0[8] restrictions (See R2001.com/ ”.1 May 7. No specific authoring style is required for the mapped WSDL document. 32 JAX-WS 2. 3.WebMethod annotation with the exclude element set to false or missing (since false is the default for this annotation element).jws. ”and “/”. In order to allow for a separation between Web service interface and implementation. if the WebService annotation on the class under consideration has a endpointInterface element..1 Mapping 1. in order to exclude a public method of a class annotated with WebService and not directly specifying a endpointInterface from the implicitly defined SEI.jws.WebService annotation.WebService must have a default public constructor.jws.jws. the class implicitly defines a service endpoint interface (SEI) which comprises all of the public methods that satisfy one of the following conditions: 1.Chapter 3.WebService annotation can be used to define a Web service. it is necessary to annotate the method with a WebMethod annotation with the exclude element set to true.

11. ♦ Conformance (Inherited interface mapping): An implementation MAY map inherited interfaces to additional wsdl:portType elements within the wsdl:definitions element. Interface 3.2. If the exclude element of the javax.1 and 3.4.WebMethod (see 7. MUST NOT have the exclude element set to true. 3.jws.5 Method Each public method in a Java SEI is mapped to a wsdl:operation element in the corresponding wsdl:portType plus one or more wsdl:message elements.1 shows an example of a Java SEI and the corresponding wsdl:portType. 2007 JAX-WS 2.WebMethod annotation (see 7. • Any of its methods MAY carry a javax.jws. 3.1) MAY be used to customize the name and targetNamespace attributes of the wsdl:portType element.4 Interface A Java service endpoint interface (SEI) is mapped to a wsdl:portType element.2.1). May 7.jws. the SEI is treated as if all methods of the inherited interface were defined within the SEI. • All method parameters and return types are compatible with the JAXB 2.jws. ♦ Conformance (Operation naming): In the absence of customizations.11.2). 7. See sections 7.7 of the specification.1 33 . The javax.jws. ♦ Conformance (Inheritance flattening): A mapped wsdl:portType element MUST contain WSDL definitions for all the methods of the corresponding Java SEI including all inherited methods.4 for more information on these customizations.1 does not define a standard representation for the inheritance of wsdl:portType elements.WebMethod if used. Customizations may be used to resolve these clashes.11.3.2. An SEI is a Java interface that meets all of the following criteria: • It MUST carry a javax. If not customized. • javax.jws. Figure 3. Multiple SEIs in the same package may result in name clashes as the result of sections 3.2) annotation MAY be used to customize the value of the name attribute of the wsdl:operation element and MUST be used to resolve naming conflicts.0[10] Java to XML Schema mapping definition ♦ Conformance (portType naming): The javax.11. When mapping an SEI that inherits from another interface. The wsdl:portType element acts as a container for other WSDL elements that together form the WSDL description of the methods in the corresponding Java SEI. the value of the name attribute of the wsdl:portType element MUST be the name of the SEI not including the package name and the target namespace is computed as defined above in section 3.3 and 7.4.WebService annotation (see section 7.WebMethod is set to true then the Java method MUST NOT be present in the wsdl as a wsdl:operation element. the value of the name attribute of the wsdl:operation element MUST be the name of the Java method.1 Inheritance WSDL 1.WebService annotation (see 7.6.

6 describes the mapping from Java methods and their parameters to corresponding global element declarations and named types in the wsdl:types section. The javax. two way methods have an input and produce an output.11.7.1 Mapping Methods are either one-way or two-way: one way methods have an input but produce no output.WebParam and javax.1 describes one way operations further.jws.Chapter 3.OneWay MUST NOT be mapped to one-way operations. 3. Not all Java methods that fulfill this requirement are amenable to become one-way operations and automatic choice between two-way and one-way mapping is not possible.7 for further details on exception mapping. Figure 3. Each wsdl:message element has one of the following1 : Document style A single wsdl:part child element that refers. Section 3. 1 34 JAX-WS 2. The value of a wsdl:message element’s name attribute is not significant but by convention it is normally equal to the corresponding operation name for input messages and the operation name concatenated with “Response” for output messages.5. ♦ Conformance (One-way mapping errors): Implementations MUST prevent mapping to one-way operations of methods that do not meet the necessary criteria. via a type attribute. RPC style Zero or more wsdl:part child elements (one per method parameter and one for a non-void return value) that refer.3) annotation to specify which methods to map to one-way operations.5. Naming of fault messages is described in section section 3. via an element attribute. that have no parameters that implement Holder and that do not throw any checked exceptions can be mapped to one-way operations.OneWay (see 7. • (Two-way methods only) zero or more wsdl:fault child elements. The wsdl:fault child elements refer to associated wsdl:message elements to describe each fault. • (Two-way methods only) an optional wsdl:output element that refers to a wsdl:message to describe the operation output.1 using document style.1 using RPC style.2 shows an example of mapping a Java interface containing a single method to WSDL 1. to a global element declaration in the wsdl:types section.jws.1 shows an example of mapping a Java interface containing a single method to WSDL 1.jws. ♦ Conformance (One-way mapping): Implementations MUST support use of the javax.1 One Way Operations Only Java methods whose return type is void. to named type declarations in the wsdl:types section. Figure 3.1 May 7. The wsdl:operation element corresponding to each method has one or more child elements as follows: • A wsdl:input element that refers to an associated wsdl:message element to describe the operation input.WebResult annotations can introduce additional parts into messages when the header element is true. See section 3. one for each exception thrown by the method. Section 3. Methods that are not annotated with javax.jws. Java to WSDL 1. 2007 .

..1: Java interface to WSDL portType mapping using document style May 7.WSDL extract --> <types> <xsd:schema targetNamespace=".5. 2007 JAX-WS 2.element declarations --> <xsd:element name="getPrice" type="tns:getPriceType"/> <xsd:element name="getPriceResponse" type="tns:getPriceResponseType"/> <xsd:element name="TickerException" type="tns:TickerExceptionType"/> <!-.type definitions --> . @WebService public interface StockQuoteProvider { float getPrice(String tickerSymbol) throws TickerException.1 35 . </xsd:schema> </types> <message name="getPrice"> <part name="getPrice" element="tns:getPrice"/> </message> <message name="getPriceResponse"> <part name="getPriceResponse" element="tns:getPriceResponse"/> </message> <message name="TickerException"> <part name="TickerException" element="tns:TickerException"/> </message> <portType name="StockQuoteProvider"> <operation name="getPrice"> <input message="tns:getPrice"/> <output message="tns:getPriceResponse"/> <fault message="tns:TickerException"/> </operation> </portType> Figure 3."> <!-.example.. } <!-.3.. Method 1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 // Java package com.

1 May 7. Java to WSDL 1. 2007 .example...element declarations --> <xsd:element name="TickerException" type="tns:TickerExceptionType"/> <!-.2: Java interface to WSDL portType mapping using RPC style 36 JAX-WS 2.WSDL extract --> <types> <xsd:schema targetNamespace=". } <!-. </xsd:schema> </types> <message name="getPrice"> <part name="tickerSymbol" type="xsd:string"/> </message> <message name="getPriceResponse"> <part name="return" type="xsd:float"/> </message> <message name="TickerException"> <part name="TickerException" element="tns:TickerException"/> </message> <portType name="StockQuoteProvider"> <operation name="getPrice"> <input message="tns:getPrice"/> <output message="tns:getPriceResponse"/> <fault message="tns:TickerException"/> </operation> </portType> Figure 3.type definitions --> ."> <!-.Chapter 3. @WebService public interface StockQuoteProvider { float getPrice(String tickerSymbol) throws TickerException...1 Mapping 1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 // Java package com.

xml.XmlAttachementRef. ♦ Conformance (Parameter classification): The javax. A methods return type is always out.bind.bind.jws. Thus. A JAXB annotation on the method is used to specify the binding of a methods return type while an annotation on the parameter specifies the binding of that parameter. ♦ Conformance (use of JAXB annotations): An implementation MUST honor any JAXB annotation that exists on an SEI method or parameter to assure that the proper XML infoset is used when marshalling/ unmarshalling the the return value or parameters of the method.XmlList. Since JAX-WS uses JAXB for it data binding. Parameters can be mapped to components of the message or global element declaration for either the operation input message.jws. the first argument of a method will have a default parameter name of “arg0”. May 7. the default MUST be in/out. javax. all other parameters are classified as in.adapters.4) MAY be used to specify whether a holder parameter is treated as in/out or out. The set of JAXB annotations that MUST be supported are: javax. the second one “arg1”and so on.annotation.annotation. for instance. For method parameters. Header results MUST be included as soap:header elements in the operation’s output message.Holder<T> class is classified as in/out or out. A parameter whose type is a parameterized javax.WebParam annotation (see 7.xml.6.XmlMimeType and javax.Holder.ws.1 Parameter and Return Type Classification Method parameters and return type are classified as follows: in The value is transmitted by copy from a service client to the SEI but is not returned from the service endpoint to the client.annotation.bind.ws.WebParam annotation (see 7. operation output message or both. If both the name and partName elements are used in the javax. out The value is returned by copy from an SEI to the client but is not transmitted from the client to the service endpoint implementation.xml.jws. javax.xml.6.bind.WebResult annotation’s header element MAY be used to map results to SOAP headers.4) MAY be used to specify the name of the wsdl:part or XML Schema element declaration corresponding to a Java parameter. ♦ Conformance (Parameter naming): The javax. If not specified.XmlJavaTypeAdapter 3.jws. javax.jws. The javax.1 37 .3. If not specified.WebParam annotation then the partName MUST be used for the wsdl:part name attribute and the name element from the annotation will be ignored. The mapping depends on the parameter classification. JAXB annotations on methods and method parameters MUST be honored. holder classes are used to determine the classification. in/out The value is transmitted by copy from a service client to the SEI and is returned by copy from the SEI to the client.xml. Method Parameters and Return Type 3. 2007 JAX-WS 2.6 Method Parameters and Return Type A Java method’s parameters and return type are mapped to components of either the messages or the global element declarations mapped from the method.11.The javax. the default is “argN”.11. where N is replaced with the zero-based argument index.WebParam annotation’s header element MAY be used to map parameters to SOAP headers. Header parameters MUST be included as soap:header elements in the operation’s input message.xml.

3 and 7.WebParam annotation’s header element MAY be used to map parameters to SOAP headers.jws.1 May 7. ♦ Conformance (Wrapper bean name clash): Generated bean classes must have unique names within a package and MUST NOT clash with other classes in that package. ♦ Conformance (Default wrapper bean names): In the absence of customizations. the wrapper request bean class MUST be named the same as the method and the wrapper response bean class MUST be named the same as the method with a “Response” suffix. a use of LITERAL and a parameterStyle of WRAPPED. The three styles are described in the following subsections.SOAPBinding annotation with the following properties: a style of DOCUMENT.2. Clashes during generation MUST be reported as an error and require user intervention via name customization to correct.xml. 2007 .2 Use of JAXB JAXB 2.11. document bare and RPC.jws.jws. The styles differ in what XML Schema constructs are generated for a method.ResponseWrapper annotations (see 7.xml. Three styles of Java to WSDL mapping are supported: document wrapped. The javax. the default name is return. Header parameters MUST be included as soap:header elements in the operation’s input message.SOAPBinding annotation MAY be used to specify at the type level which style to use for all methods it contains or on a per method basis if the style is document. each method is converted to two Java bean classes: one for the method input (henceforth called the request bean) and one for the method output (henceforth called the response bean). 3.WebResult annotations then the partName MUST be used for the wsdl:part name attribute and the name elment from the annotation will be ignored.jws.1 Document Wrapped This style is identified by a javax. JAX-WS uses this mapping to generate XML Schema named type and global element declarations that are referred to from within the WSDL message constructs generated for each operation.6.Chapter 3. 3. Note that some platforms do not distiguish filenames based on case so comparisons MUST ignore case.xml.jws. Java to WSDL 1.ws.1 defines a mapping from Java classes to XML Schema constructs.ws. For the purposes of utilizing the JAXB mapping.6. The javax. ♦ Conformance (Header mapping of parameters and results): The javax. 38 JAX-WS 2.xml. The javax.4) MAY be used to customize the name of the generated wrapper bean classes.RequestWrapper and javax.ws.WebResult annotation’s header element MAY be used to map results to SOAP headers. Header results MUST be included as soap:header elements in the operation’s output message.4) MAY be used to specify the name of the wsdl:part or XML Schema element declaration corresponding to the Java method return type.ws.WebResult annotation (see 7. If both the name and partName elements are used in the javax.RequestWrapper and javax.ResponseWrapper annotations (see 7. the wrapper beans package MUST be a generated jaxws subpackage of the SEI package. ♦ Conformance (Wrapper element names): The javax. In the absence of customizations.1 Mapping ♦ Conformance (Result naming): The javax. The first letter of each bean name is capitalized to follow Java class naming conventions. ♦ Conformance (Default wrapper bean package): In the absence of customizations.jws.3 and 7.4) MAY be used to specify the qualified name of the elements generated for the wrapper beans.

. and in/out non-header parameter. A response bean is generated containing properties for the method return value. Whereas the element name is derived from the RequestWrapper or ResponseWrapper annotations. The corresponding global element declarations MUST NOT have the nillable attribute set to a value of true. The global element declarations are used as the values of the wsdl:part elements element attribute. targetNamespace=".") @XmlAccessorType(AccessType. out The parameter or return value is mapped to a child element of the global element declaration for the response bean. Method Parameters and Return Type A request bean is generated containing properties for each in and in/out non-header parameter.. The request and response beans are generated with the appropriate JAXB customizations to result in a global element declaration for each bean class when mapped to XML Schema by JAXB.") @XmlAccessorType(AccessType.3. targetNamespace=". May 7.1) is used for the mapping rather than the holder class itself.. see figure 3.3: Wrapper mode bean representation of an operation When the JAXB mapping to XML Schema is utilized this results in global element declarations for the mapped request and response beans with child elements for each method parameter according to the parameter classification: in The parameter is mapped to a child element of the global element declaration for the request bean.1. @XmlRootElement(name="getPrice". its type is named according to the operation name (for the local part) and the target namespace for the portType that contains the operation (for the namespace name). In the case of a parameter. targetNamespace=". the class of the value of the holder class (see section 3.. Method return values are represented by an out property named “return”. The class of the value of the holder class (see section 3. 1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 float getPrice(@WebParam(name="tickerSymbol") String sym). 2007 JAX-WS 2.FIELD) public class GetPriceResponse { @XmlElement(name="return". Figure 3.FIELD) public class GetPrice { @XmlElement(name="tickerSymbol".") @XmlType(name="getPrice".") @XmlType(name="getPriceResponse".6. targetNamespace="") public float _return. in/out The parameter is mapped to a child element of the global element declarations for the request and response beans. targetNamespace="") public String tickerSymbol. The order of the properties in the request bean is the same as the order of parameters in the method signature.3 illustrates this conversion.. each out non-header parameter.1 39 ..6.6.1) is used for the mapping rather than the holder class itself.. targetNamespace=". } @XmlRootElement(name="getPriceResponse". The order of the properties in the response bean is the property corresponding to the return value (if present) followed by the properties for the parameters in the same order as the parameters in the method signature.. } Figure 3.

It must have at most one in or in/out non-header parameter. The namespace name of the input and output global elements is the value of the targetNamespace attribute of the WSDL definitions element.6.Chapter 3.jws.6. If an output parameter is used then the class of the value of the holder class is used. see figure 3. in the absence of a WebParam or WebResult annotation. out and in/out parameter and the return value are mapped to named XML Schema types using the mapping defined by JAXB. If it has a return type of void it must have at most one in/out or out non-header parameter. A global element declaration is generated for the method output and.2 Document Bare This style is identified by a javax. a use of LITERAL and a parameterStyle of WRAPPED2 . For out and in/out parameters the class of the value of the holder is used rather than the holder itself.3 RPC This style is identified by a javax. If present. its local name is equal to the operation name.SOAPBinding annotation with the following properties: a style of DOCUMENT. Java to WSDL 1. 3.1. a use of LITERAL and a parameterStyle of BARE. The global element declarations are used as the values of the wsdl:part elements element attribute. The nillable attribute of the generated global elements MUST have a value of true if and only if the corresponding Java types are reference types. Deviations from this is an error 40 JAX-WS 2. In order to qualify for use of bare mapping mode a Java method must fulfill all of the following criteria: 1.SOAPBinding annotation with the following properties: a style of RPC. A global element declaration is generated for the method input and. the type of the input parameter is mapped to a named XML Schema type using the mapping defined by JAXB. If present. If the input parameter is a holder class then the class of the value of the holder is used instead. 3. 2007 .1 Mapping 3. the local name is equal to the operation name suffixed with “Response”.jws. 2. in the absence of a WebParam annotation.1 May 7.2.2. If it has a return type other than void it must have no in/out or out non-header parameters. the type of the output parameter or return value is mapped to a named XML Schema type using the mapping defined by JAXB. Each method parameter and the return type is mapped to a message part according to the parameter classification: 2 Use of RPC style requires use of WRAPPED parameter style. The Java types of each in. The type of the two elements depends on whether a type was generated for the corresponding element or not: Named type generated The type of the global element is the named type. No type generated The type of the element is an anonymous empty type.

5 (i.rmi. The wsdl:fault element appears as a child of the wsdl:operation element that corresponds to the Java method that throws the exception and refers to the wsdl:message element. the package of the bean is a generated jaxws subpackage of the SEI package. The wsdl:part element refers to an XML Schema global element declaration that describes the fault. For exceptions that do not match the pattern described in section 2. exceptions that have a getFaultInfo method and WebFault annotation). the name of the global element declaration for a mapped exception MUST be the name of the Java exception. ♦ Conformance (Exception naming): In the absence of customizations. JAXB defines the mapping from a Java bean to XML Schema element declarations and type definitions and is used to generate the global element declaration that describes the fault.ws. or returned from a method.xml. then an implementation MUST throw a WebServiceException.2.3. Service Specific Exception in The parameter is mapped to a part of the input message. out The parameter or return value is mapped to a part of the output message. 2. null values cannot be used as method arguments or as the return value from a method which uses the rpc/literal binding. 2007 JAX-WS 2. in/out The parameter is mapped to a part of the input and output message. The following algorithm is used to map non-matching exception classes to the corresponding Java beans for use with JAXB: 1.lang. The named types are used as the values of the wsdl:part elements type attribute.7 Service Specific Exception A service specific Java exception is mapped to a wsdl:fault element. JAX-WS maps those exceptions to Java beans and then uses those Java beans as input to the JAXB mapping.1 of the WS-I Basic Profile specification (see [8]).rmi. In the absence of customizations. The javax. the name of the bean is the same as the name of the Exception suffixed with “Bean”. that uses the rpc/literal style. May 7. ♦ Conformance (java.stockquote. ♦ Conformance (Null Values in rpc/literal): If a null value is passed as an argument to a method.e.jaxws.1 41 . if the SEI package is com. a wsdl:message element with a single child wsdl:part element and an XML Schema global element declaration. In the absence of customizations.3. Due to the limitations described in section 5. For exceptions that match the pattern described in section 2. the FaultBean is used as input to JAXB when mapping the exception to XML Schema. see figure 3. Service specific exceptions are defined as all checked exceptions except java. E.RemoteExceptions): java.5.lang.example.RuntimeExceptions and java.RemoteException and its subclasses.RuntimeException and java.g.rmi.example.RemoteException and their subclasses MUST NOT be treated as service specific exceptions and MUST NOT be mapped to WSDL.stockquote then the package of the bean would be com.7. 3. The value of the name attribute of each wsdl:part element is the name of the corresponding method parameter or “return”for the method return value.WebFault annotation MAY be used to customize the local name and namespace name of the element.

} public void setTicker(String ticker) { . public UnknownTicker(Sting ticker) { .Throwable and the getClass getter from java. } } Figure 3. Java to WSDL 1.String.e. 1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 @WebFault(name="UnknownTickerFault". an abstract port type can be bound to multiple protocols. The getCause. 3. 42 JAX-WS 2.Chapter 3.. a property of the same type and name is added to the bean... namespace="... getLocalizedMessage and getStackTrace getters from java.... Throwable cause) { .FIELD) @XmlType(name="UnknownTicker".... For each getter in the exception and its superclasses.. } public UnknownTicker(Sting ticker.. in the absence of customizations..compareTo(String) method uses). 5.. the @XmlType annotation has a propOrder property whose value is an array containing the names of all the properties of the exception class that were mapped in the previous bullet point. to the name of the exception.1 May 7.Object are excluded from the list of getters to be mapped. 2007 .1.. 4. String message. Additionally... "ticker"}) public class UnknownTickerBean { . Figure 3. } public UnknownTicker(Sting ticker.") public class UnknownTicker extends Exception { .. sorted lexicographically according to the Unicode value of each of their characters (i.4: Mapping of an exception to a bean for use with JAXB.") @XmlAccessorType(AccessType.4 illustrates this mapping.. Note that some platforms do not distiguish filenames based on case so comparisons MUST ignore case. } public String getMessage() { . ♦ Conformance (Fault bean name clash): Generated bean classes must have unique names within a package and MUST NOT clash with other classes in that package. targetNamespace=". } } @XmlRootElement(name="UnknownTickerFault" targetNamespace=".. Clashes during generation MUST be reported as an error and require user intervention via name customization to correct.lang.1 Mapping 3. The bean is annotated with a JAXB @XmlRootElement annotation whose name property is set. } public String getTicker() { ..8 Bindings In WSDL 1... using the same algorithm that the int java. } public void setMessage(String message) { .. propOrder={"message".lang..lang. } public String getTicker() { . public UnknownTickerBean() { .". String message) { .. The bean is annotated with a JAXB @XmlType annotation whose name property is set to the name of the exception and whose namespace property is set to the namespace name mapped from the exception package name..

The value of the name attribute of the wsdl:binding is not significant.8. 3.1/HTTP binding (see 10).3.2 Method and Parameters Each method in a Java SEI is mapped to a wsdl:operation child element of the corresponding wsdl:binding.11.1 Interface A Java SEI is mapped to a wsdl:binding element and zero or more wsdl:port extensibility elements.binding specific extensions possible here --> </output> <fault message="tns:unknowntickerException"> <!-. if present. 1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 <portType name="StockQuoteProvider"> <operation name="getPrice" parameterOrder="tickerSymbol"> <input message="tns:getPrice"/> <output message="tns:getPriceResponse"/> <fault message="tns:unknowntickerException"/> </operation> </portType> <binding name="StockQuoteProviderBinding"> <!-.8. 3. The value of the name attribute of the wsdl:operation element is the same as the correMay 7.binding specific extensions possible here --> </input> <output message="tns:getPriceResponse"> <!-.8). Bindings ♦ Conformance (Binding selection): An implementation MUST generate a WSDL binding according to the rules of the binding denoted by the BindingType annotation (see 7. otherwise the default is the SOAP 1.8. The wsdl:binding element acts as a container for other WSDL elements that together form the WSDL description of the binding to a protocol of the corresponding wsdl:portType.5.binding specific extensions possible here --> <operation name="getPrice"> <!-. An example of a port type and associated binding skeleton structure is shown in figure 3. The wsdl:port extensibility elements define the binding specific endpoint address for a given port.binding specific extensions possible here --> <input message="tns:getPrice"> <!-.5: WSDL portType and associated binding The common skeleton structure is mapped from Java as described in the following subsections. 2007 JAX-WS 2.binding specific extensions possible here --> </fault> </operation> </binding> Figure 3.1 43 . see section 3. by convention it contains the qualified name of the corresponding wsdl:portType suffixed with “Binding”. Each protocol binding extends a common extensible skeleton structure and there is one instance of each such structure for each protocol binding.

erasure would be applied to the type of Collection i. 3. wsdl:output. The wsdl:operation element has wsdl:input. namespace = ". Color color) { shape.") public class SetColor { @XmlElement(name = "arg0". } The generated wrapper bean would be 1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 @XmlRootElement(name = "setColor". } public void setArg0(Shape arg0) { this.e it would be Collection<erasure(T)>. Type erasure is a mapping from parameterized types or type variables to types that are never parameterized types or type variables. 2007 .arg0 = arg0.") @XmlAccessorType(AccessType.FIELD) @XmlType(name = "setColor".arg1. @XmlElement(name = "arg1".setColor(color).arg1 = arg1. namespace = "") private Shape arg0.. Java to WSDL 1.. } } 44 JAX-WS 2. namespace = "") private Color arg0. return shape. The following code snippets shows the result of erasure on a wrapper bean that is generated when using generics: 1 2 3 4 public <T extends Shape> T setColor(T shape.arg0..1 May 7. In the case of Collection instead of applying erasure on the Collection itself. impelementations are required to use type erasure(see JLS section 4. } public Color getArg1() { return this.6 for definition of Type Erasure) when generating the request / response wrapper beans and exception beans except in the case of Collections. } public void setArg1(Color arg1) { this.. and wsdl:fault child elements if they are present in the corresponding wsdl:operation child element of the wsdl:portType being bound.9 Generics In JAX-WS when starting from Java and if generics are used in the document wrapped case. namespace = ". Erasure basically gets rid of all the generic type information from the runtime representation. public Shape getArg0() { return this.Chapter 3.1 Mapping sponding wsdl:operation element in the bound wsdl:portType.

3. namespace = "") private List<Object> arg0.FIELD) @XmlType(name = "echoTList". public List<Object> getArg0() { return this.") public class EchoTList { @XmlElement(name = "arg0".") @XmlAccessorType(AccessType. } public void setArg0(List<Shape> arg0) { this..arg0 = arg0. } } public <T> T echoTList(List<T> list) { if (list.. Generics The following code snippets shows the resulting wrapper bean when using Collections: 1 2 3 public List<Shape> echoShapeList(List<Shape> list) { return list. } } public List<? extends Shape> setArea(List<? extends Shape> list) { May 7. 2007 JAX-WS 2.FIELD) @XmlType(name = "echoShapeList"..arg0. namespace = "") private List<Shape> arg0.. namespace = ".1 45 ..") public class EchoShapeList { @XmlElement(name = "arg0". } The generated wrapper bean would be 1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 1 @XmlRootElement(name = "echoTList". namespace = "..9. public List<Shape> getArg0() { return this.. return list.size() == 0) return null. namespace = ".next().arg0.arg0 = arg0.") @XmlAccessorType(AccessType. } The generated wrapper bean would be 1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 1 2 3 4 5 @XmlRootElement(name = "echoShapeList". namespace = ".iterator().. } public void setArg0(List<Object> arg0) { this.

public List<Shape> getArg0() { return this... namespace = ".10 SOAP HTTP Binding This section describes the additional WSDL binding elements generated when mapping Java to WSDL 1.arg0. } public void setArg0(List<Shape> arg0) { this. 2007 .. Java to WSDL 1.10. The value of the style attribute of the soap:binding is either document or rpc.Chapter 3. } } 3.haNext()) { iterator. namespace = ". 3..") public class SetArea { @XmlElement(name = "arg0"...xmlsoap.iterator().setArea(. 3. If not 46 JAX-WS 2.11).next().1 Interface A Java SEI is mapped to a soap:binding child element of the corresponding wsdl:binding element plus a soap:address child element of any corresponding wsdl:port element (see section 3. namespace = "") private List<Shape> arg0.1 May 7. ♦ Conformance (SOAP binding style required): Implementations MUST include a style attribute on a generated soap:binding. } The generated wrapper bean would be 1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 @XmlRootElement(name = "setArea".FIELD) @XmlType(name = "setArea". while(iterator. Figure 3.2 Method and Parameters Each method in a Java SEI is mapped to a soap:operation child element of the corresponding wsdl:operation.10.arg0 = arg0.org/soap/http.1 Mapping 2 3 4 5 6 7 Iterator iterator = list. } return list.6 shows an example of a SOAP HTTP binding.") @XmlAccessorType(AccessType. The value of the transport attribute of the soap:binding is http://schemas.). ♦ Conformance (SOAP binding support): Implementations MUST be able to generate SOAP HTTP bindings when mapping Java to WSDL 1. The value of the style attribute of the soap:operation is document or rpc.1 using the SOAP HTTP binding.1.

3) to a wsdl:service.xmlsoap. A wsdl:port element describes a port type bound to a particular protocol (a wsdl:binding) that is available at particular endpoint address. A WSDL 1.11 Service and Ports A Java service implementation class is mapped to a single wsdl:service element that is a child of a wsdl:definitions element for the appropriate target namespace. the serviceName element of the WebService annotation are used to derive the service name. otherwise the name of the implementation class with the “Service”suffix appended to it.1 service is a collection of related wsdl:port elements. It is given by the serviceName element of the WebService annotation. Service and Ports 1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 <binding name="StockQuoteProviderBinding"> <soap:binding transport="http://schemas.7 shows an example using document style. if present with a non-default value. The parameters of a Java method are mapped to soap:body or soap:header child elements of the wsdl:input and wsdl:output elements for each wsdl:operation binding element.0 allows specifying one port of one binding type for each service defined by the application. May 7. otherwise from the package of the Java service implementation class according to the rules in section 3. In mapping a @WebService-annotated class (see 3. ♦ Conformance (Service creation): Implementations MUST be able to map classes annotated with the javax.11. figure 3.3. Implementations MAY support additional ports.2. JAX-WS 2.org/soap/http" style="document"/> <operation name="getPrice"> <soap:operation style="document|rpc"/> <input message="tns:getPrice"> <soap:body use="literal"/> </input> <output message="tns:getPriceResponse"> <soap:body use="literal"/> </output> <fault message="tns:unknowntickerException"> <soap:fault use="literal"/> </fault> </operation> </binding> Figure 3. WS-I Basic Profile[8] requires that all operations within a given SOAP HTTP binding instance have the same binding style. The value of the use attribute of the soap:body is literal. 2007 JAX-WS 2. if non-empty value.6: WSDL SOAP HTTP binding specified.1 47 . Figure 3. The value of the name attribute of the wsdl:service element is computed according to the JSR-181 [14] specification. 3. The latter is mapped from the value of the targetNamespace element of the WebService annotation. as long as their names do not conflict with the standard one.WebService annotation to WSDL wsdl:service elements. the value defaults to the value of the style attribute of the soap:binding.8 shows the same example using rpc style. Each desired port is represented by a wsdl:port child element of the single wsdl:service element mapped from the Java package.jws.

. Java to WSDL 1.xmlsoap.Chapter 3..7: WSDL definition using document style 48 JAX-WS 2.org/soap/http" style="document"/> <operation name="getPrice" parameterOrder="tickerSymbol"> <soap:operation/> <input message="tns:getPrice"> <soap:body use="literal"/> </input> <output message="tns:getPriceResponse"> <soap:body use="literal"/> </output> </operation> </binding> Figure 3.1 Mapping 1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 <types> <schema targetNamespace=". 2007 .1 May 7."> <xsd:element name="getPrice" type="tns:getPriceType"/> <xsd:complexType name="getPriceType"> <xsd:sequence> <xsd:element name="tickerSymbol" type="xsd:string"/> </xsd:sequence> </xsd:complexType> <xsd:element name="getPriceResponse" type="tns:getPriceResponseType"/> <xsd:complexType name="getPriceResponseType"> <xsd:sequence> <xsd:element name="return" type="xsd:float"/> </xsd:sequence> </xsd:complexType> </schema> </types> <message name="getPrice"> <part name="getPrice" element="tns:getPrice"/> </message> <message name="getPriceResponse"> <part name="getPriceResponse" element="tns:getPriceResponse"/> </message> <portType name="StockQuoteProvider"> <operation name="getPrice" parameterOrder="tickerSymbol"> <input message="tns:getPrice"/> <output message="tns:getPriceResponse"/> </operation> </portType> <binding name="StockQuoteProviderBinding"> <soap:binding transport="http://schemas.

3. Service and Ports 1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 <types> <schema targetNamespace=".1 49 . 2007 JAX-WS 2.8: WSDL definition using rpc style May 7.11."> <xsd:element name="getPrice" type="tns:getPriceType"/> <xsd:complexType name="getPriceType"> <xsd:sequence> <xsd:element form="unqualified" name="tickerSymbol" type="xsd:string"/> </xsd:sequence> </xsd:complexType> <xsd:element name="getPriceResponse" type="tns:getPriceResponseType"/> <xsd:complexType name="getPriceResponseType"> <xsd:sequence> <xsd:element form="unqualified" name="return" type="xsd:float"/> </xsd:sequence> </xsd:complexType> </schema> </types> <message name="getPrice"> <part name="tickerSymbol" type="xsd:string"/> </message> <message name="getPriceResponse"> <part name="result" type="xsd:float"/> </message> <portType name="StockQuoteProvider"> <operation name="getPrice"> <input message="tns:getPrice"/> <output message="tns:getPriceResponse"/> </operation> </portType> <binding name="StockQuoteProviderBinding"> <soap:binding transport="http://schemas..xmlsoap.org/soap/http" style="rpc"/> <operation name="getPrice"> <soap:operation/> <input message="tns:getPrice"> <soap:body use="literal"/> </input> <output message="tns:getPriceResponse"> <soap:body use="literal"/> </output> </operation> </binding> Figure 3..

suffixed with “Port”. if present. an implementation MUST use the simple name of the class annotated with WebService suffixed with “Port”. E.1 Mapping ♦ Conformance (Port selection): The portName element of the WebService annotation. MUST be used to derive the port name to use in WSDL. In the absence of a portName element.Chapter 3.1. Binding specific child extension elements of the wsdl:port element define the endpoint address for a port. Otherwise.8). Java to WSDL 1.10. 2007 .1 May 7. see the soap:address element described in section 3. an implementation MUST use the value of the name element of the WebService annotation. 50 JAX-WS 2. if present. ♦ Conformance (Port binding): The WSDL port defined for a service MUST refer to a binding of the type indicated by the BindingType annotation on the service implementation class (see 3.g.

4.Service Service is an abstraction that represents a WSDL service.1. A WSDL service is a collection of related ports.Executor to be used for asynchronous invocations (see section 4. per-port. • Create a new port via the addPort method. These APIs allow a client to create proxies for remote service endpoints and dynamically construct operation invocations. • Create a Dispatch instance via the createDispatch method. • Configure the java.ws.1 javax.ServiceDelegate. and new ports.xml.3.concurrent. Such ports only include binding and endpoint information and are thus only suitable for creating Dispatch instances since these do not require WSDL port type information.util.3 for information on proxies. and per-protocol message handlers using a handler resolver (see section 4. See section 4. Dispatch instances. • Configure per-service. See section 4.spi.1. ♦ Conformance (Service completeness): A Service implementation MUST be capable of creating proxies.3).xml. May 7.1.1 51 . Service instances provide facilities to: • Create an instance of a proxy via one of the getPort methods. each of which consists of a port type bound to a particular protocol and available at a particular endpoint address.1.3 for information on the Dispatch interface. 2007 JAX-WS 2. see section 6. All the service methods except the static create methods and the constructors delegate to javax.4).ws.2. Service instances are created as described in section 4.Chapter 4 Client APIs This chapter describes the standard APIs provided for client side use of JAX-WS. Conformance requirements in this chapter use the term ‘implementation’ to refer to a client side JAX-WS runtime system.

create(wsdlLocation. The following create methods may be used: create(URL wsdlLocation. No WSDL document is attached to the service. The generated implementation class will have two public constructors.URL) and the service name (a javax. "StockQuoteService")). When using the no-argument constructor.ws. the WSDL location and service name are implicitly taken from the WebServiceClient annotation that decorates the generated class.com/stocks".net.org/sample".1. Service s = Service. serviceName). one with no arguments and one with two arguments.org/my.namespace.create to create Service instances. } 52 JAX-WS 2.xml. "MyService"). 4.com/stocks. targetNamespace="http://example.com/stocks.1 May 7. } public StockQuoteService(String wsdlLocation.wsdl"). when nothing is generated.g.wsdl") public class StockQuoteService extends javax.Chapter 4. 1 2 3 URL wsdlLocation = new URL("http://example. a J2SE service client uses Service.1.. serviceName).xml.2 Static case When starting from a WSDL document.7. Client APIs 4.1 Service Usage 4. QName serviceName = new QName("http://example. ♦ Conformance (Service Creation Failure): If a create method fails to create a service object. wsdlLocation="http://example. representing the wsdl location (a java. the following code illustrates this process. it MUST throw WebServiceException..1. 2007 . create(QName serviceName) Returns a service object for a service with the given name.1.Service { public StockQuoteService() { super(new URL("http://example. QName serviceName) { super(wsdlLocation.QName) respectively. The cause of that exception SHOULD be set to an exception that provides more information on the cause of the error (e.1. an IOException). QName serviceName) Returns a service object for the specified WSDL document and service name. a concrete service implementation class MUST be generated as defined in section 2. new QName("http://example.com/stocks". } .1 Dynamic case In the dynamic case.wsdl"). The following code snippet shows the generated constructors: 1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 // Generated Service Class @WebServiceClient(name="StockQuoteService".

ws. the Service class delegates all of its functionality to a ServiceDelegate object.ws. serviceName)..2) and call its createServiceDelegate method.getPort(serviceEndpointInterface).net.4. The delegate is set when a new Service instance is created. javax. A Service instance provides access to a HandlerResolver via a pair of getHandlerResolver/setHandlerResolver methods that may be used to configure a set of handlers on a May 7. } // begin delegated methods public <T> T getPort(Class<T> serviceEndpointInterface) { return delegate. protected Service(java. that may be used to extend the capabilities of a JAX-WS runtime system.net.getClass()).Service 4.URL wsdlDocumentLocation.1.2. 2007 JAX-WS 2.xml.createServiceDelegate(wsdlDocumentLocation serviceName.xml.1. the static create method defined on the Service class MUST call the protected constructor to create a new service instance.spi. this.3 Handler Resolver JAX-WS provides a flexible plug-in framework for message processing modules.1. two-argument constructor defined on the Service class is called.getClass()). The constructor MUST obtain a Provider instance (see 6. For this to work. } 4.URL wsdlDocumentLocation. In order to ensure that the delegate is properly constructed.2 Provider and Service Delegate Internally.3) to which it delegates every non-static method call. The following code snippet shows an implementation of the Service API that satisfies the requirements above: 1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 public class Service { private ServiceDelegate delegate. known as handlers.1 53 . } . which must necessarily happen when the protected. passing the two arguments received from its caller and the class object for the instance being created (i. QName serviceName) { return new Service(wsdlDocumentLocation. The field used to hold the reference MUST be private. } public static Service create(java.provider() . passing the same arguments that it received from the application. which is part of the SPI used to allow pluggability of implementations. this.e. every Service object internally MUST hold a reference to a javax.ServiceDelegate object (see 6.. Chapter 9 describes the handler framework in detail. QName serviceName) { delegate = Provider.

getEndpointReference): An implementation MUST be able to return an javax. by ”borrowing” them when the application invokes a remote operation. If the BindingProvider instance has a binding that is either SOAP 1. Subsequent changes to the handler resolver configured for a Service instance do not affect the handlers on previously created proxies. Client APIs per-service.Executor.xml.xml.ws. The executor will then be used to invoke any asynchronous callbacks requested by the application. 2007 .concurrent.BindingProvider The BindingProvider interface represents a component that provides a protocol binding for use by clients. 4.xml. A BindingProvider instance maintains separate contexts for the request and response phases of a message exchange with a service: 54 JAX-WS 2. The setExecutor and getExecutor methods of Service can be used to modify and retrieve the executor configured for a service. 4.2 javax. Figure 4. ♦ Conformance (Default Executor): Lacking an application-specified executor.ws.2. an implementation MUST use its own executor.4 Executor Service instances can be configured with a java.1 illustrates the class relationships.concurrent.1 May 7. The BindingProvider interface provides methods to obtain the Binding and to manipulate the binding providers context.1.xml. or Dispatch instances. then subsequent asynchronous callbacks MUST be delivered using the specified executor. Calls that were outstanding at the time the setExecutor method was called MAY use the previously set executor. e.EndpointReference from a BindingProvider instance that will reference the target endpoint. per-port or per-protocol binding basis. An implementation MUST NOT use application-provided threads to deliver callbacks.ws.1.util.BindingProvider.Chapter 4.g. The following subsection describes the function and use of context with BindingProvider instances. it is implemented by proxies and is extended by the Dispatch interface.UnsupportedOperationException MUST be thrown.EndpointReference for the target endpoint if a SOAP binding is being used. this metadata forms the context of an exchange.2/HTTP.lang. then a W3CEndpointReference MUST be returned. 4. When a Service instance is used to create a proxy or a Dispatch instance then the handler resolver currently registered with the service is used to create the required handler chain. A web service client can get an javax.1 Configuration Additional metadata is often required to control information exchanges. ♦ Conformance (Use of Executor): If an executor object is successfully configured for use by a Service via the setExecutor method.util. If the binding is XML/HTTP an java. ♦ Conformance (javax. a java.1/HTTP or SOAP 1.ThreadPoolExecutor or analogous mechanism. if any. Further details on Binding can be found in section 6. to deliver callbacks.ws.

4.2. javax.xml.ws.BindingProvider

BindingProvider

getBinding():Binding          implements   Proxy

s d d d dextends d Dispatch 

    has-a           X $   has-a $$ $  $$$$ $ r rrhas-a rr rr r j r

Binding ... Map < String,Object > (Request Context) ... Map < String,Object > (Response Context) ...

...

...

Figure 4.1: Binding Provider Class Relationships

Request The contents of the request context are used to initialize the message context (see section 9.4.1) prior to invoking any handlers (see chapter 9) for the outbound message. Each property within the request context is copied to the message context with a scope of HANDLER. Response The contents of the message context are used to initialize the response context after invoking any handlers for an inbound message. The response context is first emptied and then each property in the message context that has a scope of APPLICATION is copied to the response context. ♦ Conformance (Message context decoupling): Modifications to the request context while previously invoked operations are in-progress MUST NOT affect the contents of the message context for the previously invoked operations.

The request and response contexts are of type java.util.Map<String,Object> and are obtained using the getRequestContext and getResponseContext methods of BindingProvider. In some cases, data from the context may need to accompany information exchanges. When this is required, protocol bindings or handlers (see chapter 9) are responsible for annotating outbound protocol data units and extracting metadata from inbound protocol data units. Note: An example of the latter usage: a handler in a SOAP binding might introduce a header into a SOAP request message to carry metadata from the request context and might add metadata to the response context from the contents of a header in a response SOAP message.

May 7, 2007

JAX-WS 2.1

55

Chapter 4. Client APIs

4.2.1.1 Standard Properties Table 4.1 lists a set of standard properties that may be set on a BindingProvider instance and shows which properties are optional for implementations to support. Table 4.1: Standard BindingProvider properties. Name Type Mandatory Y Description The address of the service endpoint as a protocol specific URI. The URI scheme must match the protocol binding in use. Username for HTTP basic authentication. Password for HTTP basic authentication. Used by a client to indicate whether it is prepared to participate in a service endpoint initiated session. The default value is false. Controls whether the SOAPAction HTTP header is used in SOAP/HTTP requests. Default value is false. The value of the SOAPAction HTTP header if the javax.xml.ws.soap.http.soapaction.use property is set to true. Default value is an empty string.

javax.xml.ws.service.endpoint .address String

javax.xml.ws.security.auth .username String .password

Y Y

String

javax.xml.ws.session .maintain Boolean

Y

javax.xml.ws.soap.http.soapaction .use Boolean

N

.uri

String

N

♦ Conformance (Required BindingProvider properties): An implementation MUST support all properties shown as mandatory in table 4.1. Note that properties shown as mandatory are not required to be present in any particular context; however, if present, they must be honored. ♦ Conformance (Optional BindingProvider properties): An implementation MAY support the properties shown as optional in table 4.1. 4.2.1.2 Additional Properties ♦ Conformance (Additional context properties): Implementations MAY define additional implementation specific properties not listed in table 4.1. The java.* and javax.* namespaces are reserved for use by Java specifications. 56 JAX-WS 2.1 May 7, 2007

4.2. javax.xml.ws.BindingProvider

Implementation specific properties are discouraged as they limit application portability. Applications and binding handlers can interact using application specific properties.

4.2.2 Asynchronous Operations
BindingProvider instances may provide asynchronous operation capabilities. When used, asynchronous operation invocations are decoupled from the BindingProvider instance at invocation time such that

the response context is not updated when the operation completes. Instead a separate response context is made available using the Response interface, see sections 2.3.4 and 4.3.3 for further details on the use of asynchronous methods. ♦ Conformance (Asynchronous response context): The local response context of a BindingProvider instance MUST NOT be updated on completion of an asynchronous operation, instead the response context MUST be made available via a Response instance. When using callback-based asynchronous operations, an implementation MUST use the Executor set on the service instance that was used to create the proxy or Dispatch instance being used. See 4.1.4 for more information on configuring the Executor to be used.

4.2.3 Proxies
Proxies provide access to service endpoint interfaces at runtime without requiring static generation of a stub class. See java.lang.reflect.Proxy for more information on dynamic proxies as supported by the JDK. ♦ Conformance (Proxy support): An implementation MUST support proxies. ♦ Conformance (Implementing BindingProvider): An instance of a proxy MUST implement javax.xml.ws.BindingProvider. A proxy is created using the getPort methods of a Service instance:
T getPort(Class<T> sei) Returns a proxy for the specified SEI, the Service instance is responsible

for selecting the port (protocol binding and endpoint address).
T getPort(QName port, Class<T> sei) Returns a proxy for the endpoint specified by port. Note that the namespace component of port is the target namespace of the WSDL definitions document. T getPort(Class<T> sei, WebServiceFeature... features) Returns a proxy for the specified SEI, the Service instance is responsible for selecting the port (protocol binding and and endpoint address). The specified features MUST be enabled/disabled and configured as specified. T getPort(QName port, Class<T> sei, WebServiceFeature... features) Returns a proxy for the endpoint specified by port. Note that the namespace component of port is the target namespace of the WSDL definition document. The specified features MUST be enabled/disabled and

configured as specified.
T getPort(EndpointReference epr, Class<T> sei, WebServiceFeature... features) Returns a proxy for the endpoint specified by epr. The address stored in the epr MUST be used

May 7, 2007

JAX-WS 2.1

57

StockQuoteProvider. Map<String. 2007 . an IOException).xml. ♦ Conformance (Service. 4.TRUE). If the error cannot be mapped to a service 58 JAX-WS 2.xml...ws.Object> context = bp.example. proxy. The epr MUST NOT be used as the value of any addressing header such as wsa:ReplyTo. Lines 4–6 perform some configuration of the proxy.BindingProvider bp = (javax.3. com. any WSDL in a JAX-WS suppported epr metadata MUST be ignored. its WSDL MUST be used to determine any binding information. An implementation is not required to fully validate the service endpoint interface provided by the client against the corresponding WSDL definitions and may choose to implement any validation it does require in an implementation specific manner (e.maintain". The serviceEndpointInterface parameter specifies the interface that will be implemented by the proxy. Any JAX-WS supported epr metadata MUST match the PortName for the sei.1 May 7. Creation of a proxy can fail if the interface doesn’t conform to the mapping or if any WSDL related metadata is missing from the Service instance.WebServiceException. an implemention MUST throw a service specific exception if possible. then a WebServiceException MUST be thrown.xml. If the Service instance does not have a WSDL. 4.xml.ws. Lines 7 invokes a method on the proxy. otherwise a WebServiceException MUST be thrown. The specified features MUST be enabled/disabled and configured as specified.session.Service service = .example. If the Service instance has an associated WSDL.g.StockQuoteProvider proxy = service. 1 2 3 4 5 6 7 javax.BindingProvider)proxy. lazy and eager validation are both acceptable). Any JAX-WS supported epr metadata MUST match the Service instance’s ServiceName.ws.2. an implementation MUST throw javax.StockQuoteProvider). com.2.WebServiceException and zero or more service specific exceptions.1 Example The following example shows the use of a proxy to invoke a method (getLastTradePrice) on a service endpoint interface (com.xml.4 Exceptions All methods of an SEI can throw javax.. Client APIs during invocations on the endpoint.ws.getPort(portName. If there is not enough metadata in the Service instance or in the epr metadata to determine a port.1). ♦ Conformance (Remote Exceptions): If an error occurs during a remote operation invocation.g.ws.getRequestContext(). The cause of that exception SHOULD be set to an exception that provides more information on the cause of the error (e. otherwise a WebServiceExeption MUST be thrown.getPort failure): If creation of a proxy fails. Lines 1–3 show how the proxy is created.ws. then any WSDL inlined in the JAX-WS supported metadata of the epr MUST be used to determine binding information. Note that no statically generated stub class is involved.xml.Chapter 4..example. The service endpoint interface provided by the client needs to conform to the WSDL to Java mapping rules specified in chapter 2 (WSDL 1.class) javax.setProperty("javax. Boolean.getLastTradePrice("ACME"). context.

an implementation MUST throw a ProtocolException or one of its subclasses.Mode.xml.g.g. Dispatch is a generic class that supports input and output of messages or message payloads of any type.MESSAGE and javax. an error in the configuration of a proxy instance may result in a WebServiceException whose cause is a java. May 7. The higher level JAX-WS APIs are designed to hide the details of converting between Java method invocations and the corresponding XML messages. i.xml.Mode.4. a client application would work directly with a SOAP message. E. but in some cases operating at the XML message level is desirable. all those that don’t occur as part of a remote invocation or handler processing. if the message is not an XML message a WebServiceException MUST be thrown. client applications work directly with protocol-specific message structures.1 59 .xml. A WebServiceException MUST be thrown when a Dispatch<Source> is invoked and the Service returns a MIME message.Source Use of Source objects allows clients to use XML generating and consuming APIs directly.ws. Message Payload In this mode.1 for more details. a client application would work with the contents of the SOAP Body rather than the SOAP message as a whole.IllegalArgumentException thrown by some implementation code. The Dispatch interface provides support for this mode of interaction. when used with a SOAP protocol binding. When used in message mode.ws. Dispatch supports two usage modes. When used with the HTTP binding (see chapter 11) in payload mode.Service.lang. if any.ws.. without any additional wrapping.xml. client applications work with the payload of messages rather than the messages themselves. Implementations are required to support the following types of object: javax. If the exception in question is a subclass of WebServiceException then an implementation MUST rethrow it as-is.Dispatch XML Web Services use XML messages for communication between services and service clients. as appropriate for the binding in use. 2007 JAX-WS 2.Service.e.xml.. identified by the constants javax.Dispatch specific exception.3. javax. A null value for Source is allowed to make it possible to invoke an HTTP GET method in the HTTP Binding case. when used with a SOAP protocol binding. See section 6. otherwise it MUST throw a WebServiceException whose cause is set to the exception that was thrown during handler processing.Dispatch interface. Dispatch is a low level API that requires clients to construct messages or message payloads as XML and requires an intimate knowledge of the desired message or payload structure.4. ♦ Conformance (Dispatch support): Implementations MUST support the javax. an implementation MUST throw a WebServiceException whose cause is the original local exception that was thrown. ♦ Conformance (Other Exceptions): For all other errors. the HTTP request and response entity bodies must contain XML directly or a MIME wrapper with an XML root part.transform. ♦ Conformance (Exceptions During Handler Processing): Exceptions thrown during handler processing on the client MUST be passed on to the application. 4.3 javax.ws. Source objects may be used with any protocol binding in either message or message payload mode.PAYLOAD respectively: Message In this mode.ws.xml. E. For instance.

Calling invoke on the different Dispatch types defined above with a null value means an empty message will be sent where allowed by the binding. The mode parameter of createDispatch controls whether the new Dispatch instance is message or message payload oriented. However.DataSource Use of DataSource objects allows clients to work with MIME-typed messages.soap package.activation. Client APIs JAXB Objects Use of JAXB allows clients to use JAXB objects generated from an XML Schema to create and manipulate XML representations and to use these objects with JAX-WS without requiring an intermediate XML serialization. 2007 . When used in mssage mode.SOAPMessage Use of SOAPMessage objects allows clients to work with SOAP messages using the convenience features provided by the java. A JAX-WS implementation MUST honor all WebServiceFeatures (section 6.1 May 7. the HTTP request and response entity bodies must contain XML directly or a MIME wrapper with an XML root part. message mode and the MEP. javax.1.3. DataSource objects may only be used with Dispatch instances that use the HTTP binding (see chapter 11) in message mode. the WSDL binding from which the Dispatch instance is generated contains static information including the protocol binding and service endpoint address. JAXB objects may be used with any protocol binding in either message or message payload mode.1 Configuration Dispatch instances are obtained using the createDispatch factory methods of a Service instance.5) for Dispatch based applications. SOAPMessage objects may only be used with Dispatch instances that use the SOAP binding (see chapter 10) in message mode.xml. a Dispatch instance may support configuration of certain aspects of its operation and provides methods (inherited from BindingProvider) to dynamically query and change the values of properties in its request and response contexts – see section 4. Asynchronous request response (invokeAsync methods) The method returns immediately. Dispatch instances are not required to be dynamically configurable for different protocol bindings. When used with the HTTP binding (see chapter 11) in payload mode.2. One-way (invokeOneWay methods) The method is logically non-blocking. 4. 4. The type parameter controls the type of object used for messages or message payloads.2 Operation Invocation A Dispatch instance supports three invocation modes: Synchronous request response (invoke methods) The method blocks until the remote operation completes and the results are returned. no results are returned.soap.1 for a list of standard properties. any results are provided either through a callback or via a polling object.Chapter 4. subject to the capabilities of the underlying protocol. Dispatch instances are not thread safe. javax.xml.3. if the message is not an XML message a WebServiceException MUST be thrown. So for example when using 60 JAX-WS 2.

an implementation MUST throw a java. Client code should not attempt to cast the object to any particular type as this will result in non-portable behavior. In both cases. an implementation MUST throw a WebServiceException if there is any error in the configuration of the Dispatch instance or a ProtocolException if an error occurs during the remote operation invocation.4. ♦ Conformance (Failed Dispatch. an implementation MUST throw a WebServiceException if there is any error in the configuration of the Dispatch instance.invoke): When an operation is invoked using an invoke method.3 Asynchronous Response Dispatch supports two forms of asynchronous invocation: Polling The invokeAsync method returns a Response (see below) that may be polled using the methods inherited from Future<T> to determine when the operation has completed and to retrieve the results. The following interfaces are used to obtain the results of an operation invocation: The invocation is logically non-blocking so detection of errors during operation invocation is dependent on the underlying protocol in use.xml.ws.1 for additional SOAP/HTTP requirements.1 / HTTP binding in message mode null being passed to invoke is an error condition and will result in a WebServiceException. • XML / HTTP binding both in payload and in message mode null being passed to invoke with the HTTP POST and PUT operations is an error condition and will result in a WebServiceException. ♦ Conformance (Reporting asynchronous errors): If the operation invocation fails. The invokeAsync method returns a wildcard Future (Future<?>) that may be polled to determine when the operation has completed.invokeOneWay): When an operation is invoked using an invokeOneWay method. • SOAP 1. ♦ Conformance (Failed Dispatch.1 / HTTP binding in payload mode using null will send a soap message with an empty body.get() has no standard type. See section 10.3. 2007 JAX-WS 2. Callback The client supplies an AsyncHandler (see below) and the runtime calls the handleResponse method when the results of the operation are available.1 61 .3. The cause of an ExecutionException is the original exception raised. For SOAP/HTTP it is possible that certain HTTP level errors may be detected.ExecutionException from the Response.invokeAsync): When an operation is invoked using an invokeAsync method.get method.4.util. Errors that occur during the invocation are reported when the client attempts to retrieve the results of the operation. ♦ Conformance (Failed Dispatch.Dispatch • SOAP 1. In the case of a Response instance this can only be a WebServiceException or one of its subclasses. The object returned from Future<?>. 4. javax.concurrent. an implementation MUST throw a WebServiceException if there is any error in the configuration of the Dispatch instance or if an error is detected1 during the remote operation invocation. errors that occur during the invocation are reported via an exception when the client attempts to retrieve the results of the operation. 1 May 7.

invoke(reqMsg). Service service = . Response extends java. error handling has been omitted. 4.util.invoke(soapReqMsg).5.concurrent.po"). PAYLOAD). 4..ws. 62 JAX-WS 2.xml. SOAPMessage soapResMsg = disp.1 Synchronous. Dispatch<Source> disp = service.ws. an implementation MUST throw a WebServiceException whose cause is set to the original JAXBException.2 Synchronous.Chapter 4. It defines a single handleResponse method that has a Response object as its argument..3.class.. 4. 2007 . Dispatch<SOAPMessage> disp = service.3..class. The context parameter contains the JAXBContext instance that the created Dispatch instance will use to marshall and unmarshall messages or message payloads..unmarshal( new FileInputStream( "po. PAYLOAD)..xml" ) ). jc. Service service = . Unmarshaller u = jc. Dispatch<Object> disp = service.createUnmarshaller(). and asynchronous callback modes.xml. Service service = .createDispatch(portName. 4.newInstance("primer.4 Using JAXB Service provides a createDispatch factory method for creating Dispatch instances that contain an embedded JAXBContext. Source resMsg = disp.. OrderConfirmation conf = (OrderConfirmation)disp. SOAPMessage.invoke(po). PurchaseOrder po = (PurchaseOrder)u. For ease of reading.3 Synchronous.1 May 7.. javax. Payload-Oriented With JAXB Objects 1 2 3 4 5 6 7 JAXBContext jc = JAXBContext...3. 4. Message-Oriented 1 2 3 4 5 SOAPMessage soapReqMsg = ..Future<T> to provide asyn- chronous result polling capabilities. Source.createDispatch(portName..createDispatch(portName.. MESSAGE).Response A generic interface that is used to group the results of an invocation with the response context. ♦ Conformance (Marshalling failure): If an error occurs when using the supplied JAXBContext to marshall a request or unmarshall a response. Client APIs javax.3.5.. Payload-Oriented 1 2 3 4 5 Source reqMsg = .5 Examples The following examples demonstrate use of Dispatch methods in the synchronous.5.AsyncHandler A generic interface that clients implement to receive results in an asynchronous callback. asynchronous polling..3.

xml. Response<SOAPMessage> res = disp.4. 4.get().5 Asynchronous. an application can package one or more description and/or schema documents in jar files.. Message-Oriented 1 2 3 4 5 6 7 8 9 SOAPMessage soapReqMsg = . Each resource MUST be a valid entity catalog according to the XML Catalogs 1. Service service = . while (!res.isDone()) { // do something while we wait } SOAPMessage soapResMsg = res. unbeknownst to the application code.. MESSAGE). 4.invokeAsync(reqMsg.4 Catalog Facility JAX-WS mandates support for a standard catalog facility to be used when resolving any Web service document that is part of the description of a Web service....invokeAsync(soapReqMsg). Using the entity catalog. Dispatch<SOAPMessage> disp = service. Payload-Oriented 1 2 3 4 5 6 7 8 9 10 11 12 13 14 class MyHandler implements AsyncHandler<Source> { . 4. SOAPMessage. handler).3.5. Catalog Facility In the above example PurchaseOrder and OrderConfirmation are interfaces pre-generated by JAXB from the schema document ‘primer. PAYLOAD).get().. The catalog is assembled by taking into account all accessible resources whose name is META-INF/jax-ws-catalog.. possibly local ones. public void handleResponse(Response<Source> res) { Source resMsg = res.1 specification [30]. a deployer can easily alter it to suit the local environment. The facility in question is the OASIS XML Catalogs 1. • Mapping the URI reference of a resource to another URI reference.createDispatch(portName.4.class. Dispatch<Source> disp = service. // do something with the results } } Source reqMsg = ..3. Since the catalog is an XML document. avoiding costly remote accesses.. It defines an entity catalog that handles the following two cases: • Mapping an external entity’s public identifier and/or system identifier to a URI reference.createDispatch(portName.. or remap remote URIs to other. Callback.. Polling.1 63 .4 Asynchronous.5..po’. MyHandler handler = new MyHandler()... disp. Service service = . 2007 JAX-WS 2. specifically WSDL and XML Schema documents. Source.1 May 7.class.

The EndpointReference instance MUST NOT be used directly as the value of an WSAddressing header such as wsa:ReplyTo.. When running on the Java SE platform..xml.5 javax.xml. The EndpointReference class delegates to the javax.spi. Client APIs specification. resulting in catalog-based URI resolutions.xml. ♦ Conformance (Use of the Catalog): In the process of resolving a URI that points to a WSDL document or any document reachable from it.ws. 4. getPort(Class<T> serviceEndpointInterface. Although defined in the client API chapter for reasons of ease of exposure.Provider to perform the getPort operation. resolutions of URIs to WSDL and schema documents that arise during the publishing of the contract for an endpoint (see 5. Relative URIs inside a catalog file are relative to the location of the catalog that contains them.EndpointReference is an abstraction that represents an invocable web service endpoint.Chapter 4. In particular. The returned proxy MUST use the EndpointReference instance to determine the endpoint address and any reference parameters to be sent on endpoint invocations. 64 JAX-WS 2.2.5) are subject to the requirements in this section. every JAX-WS API argument or annotation element whose semantics is that of a WSDL location URI MUST undergo URI resolution using the catalog facility described in this section.EndpointReference A javax. In particular.ws. features) Gets a proxy for the serviceEndpointInterface that can be used to invoke operations on the endpoint referred to by the EndpointReference instance. Client applications can use an EndpointReference to get a port for an SEI although doing so prevents them from getting/setting the Executor or HandlerResolver which would normally be done on a Service instance. the current context class loader MUST be used to retrieve all the resources with the specified name. 2007 . The specified features MUST be enabled/disabled and configured as specified.ws. a JAX-WS implementation MUST perform a URI resolution for it.1 specification.1 May 7. WebServiceFeature. as prescribed by the XML Catalogs 1. The following method can be used to get a proxy for a Port. use of the catalog is in no way restricted to client uses of WSDL location URIs. using the catalog defined above as its entity catalog. For this method to successfully return a proxy. WSDL metadata MUST be available and the EndpointReference instance MUST contain an implementation understood ServiceName in its metadata.

♦ Conformance (WebServiceProvider annotation): A Provider based service endpoint implementation MUST carry a WebServiceProvider annotation (see 7. 5. e. ♦ Conformance (Provider support required): An implementation MUST support Provider<Source> in payload mode with all the predefined bindings. 2007 JAX-WS 2. Section 2. ♦ Conformance (Provider default constructor): A Provider based service endpoint implementation MUST provide a public default constructor. Section 3. either directly or via the use of annotations.4 describes the requirements that a Java interface must meet to qualify as a JAX-WS SEI. May 7. ♦ Conformance (Provider implementation): A Provider based service endpoint implementation MUST implement a typed Provider interface.1 65 .Chapter 5 Service APIs This chapter describes requirements on JAX-WS service implementations and standard APIs provided for their use. The generic nature of Provider allows use with a variety of message object types. Provider<Source> or Provider<SOAPMessage>. perhaps mapped from a WSDL port type. However.Provider JAX-WS services typically implement a native Java service endpoint interface (SEI). in some cases it is desirable for services to be able to operate at the XML message level. Provider is a low level generic API that requires services to work with messages or message payloads and hence requires an intimate knowledge of the desired message or payload structure. A typed Provider interface is one in which the type parameter has been bound to a concrete class.DataSource> in message mode in conjunction with the predefined HTTP binding. The Provider interface offers an alternative to SEIs and may be implemented by services wishing to work at the XML message level.ws.1 javax. Java SEIs provide a high level Java-centric abstraction that hides the details of converting between Java objects and their XML representations for use in XML-based messages.g. It MUST also support Provider<SOAPMessage> in message mode in conjunction with the predefined SOAP bindings and Provider<javax.2 describes the mapping from a WSDL port type to an equivalent Java SEI.xml.7).activation. as in Provider<T>. as opposed to being left unbound.

1. reply message is the same as the input message 1 2 3 4 5 6 7 8 9 10 @WebServiceProvider @ServiceMode(value=Service.1.1.1. 5. a SOAP message when using the SOAP binding). Service APIs A JAX-WS implementation MUST honor all WebServiceFeatures (section 6.1.Mode.2 Configuration The ServiceMode annotation is used to configure the messaging mode of a Provider instance. } } 66 JAX-WS 2. Provider instances MAY use the WebServiceContext facility (see 5.MESSAGE) public class MyService implements Provider<SOAPMessage> { public MyService() { } public SOAPMessage invoke(SOAPMessage request) { return request.1. 2007 .1 Invocation A Provider based service instance’s invoke method is called for each message received for the service. Simple echo service. Use of @ServiceMode(value=MESSAGE) indicates that the provider instance wishes to receive and send entire protocol messages (e.3 Examples For brevity.g.5) for Provider based applications. the contents of a SOAP Body element when using the SOAP binding). 5.1 May 7.1 Exceptions The service runtime is required to catch exceptions thrown by a Provider instance.3) to access the message context and other information about the request currently being served. 5. The protocol binding is responsible for converting the exception into a protocol specific fault representation and then invoking the handler chain and dispatching the fault message as appropriate. absence of the annotation or use of @ServiceMode(value=PAYLOAD) indicates that the provider instance wishes to receive and send message payloads only (e.4. A Provider instance may make use of the protocol specific exception handling mechanism as described in section 6.Chapter 5. These properties are passed to the Provider instance each time it is invoked using the MessageContext instance accessible from the WebServiceContext. 5. The JAX-WS runtime makes certain properties available to a Provider instance that can be used to determine its configuration. error handling is omitted in the following examples.g.

xml. return reply. .).PAYLOAD) public class MyService implements Provider<Source> { public MyService() { } public Source invoke(Source request) { JAXBContent jc = JAXBContext.createUnmarshaller(). 5..2 javax. Their values can be retrieved using the getImplementor and getBinding methods respectively.xml. reply).xml.PAYLOAD) public class MyService implements Provider<Source> { public MyService() { } public Source invoke(Source request) { Source requestPayload = request.2..getPayload().Mode.unmarshall(request). StreamSource reply = new StreamSource(new StringReader(replyElement)).5.2.. If the implementor specifies a binding using the javax. Object requestObj = u. javax.Endpoint The Endpoint class can be used to create and publish Web service endpoints. Implementor and binding are set when the endpoint is created and cannot be modified later.’/>".1 Endpoint Usage Endpoints can be created using the following static methods on Endpoint: create(Object implementor) Creates and returns an Endpoint for the specified implementor. reply message contains a fixed acknowlegment element 1 2 3 4 5 6 7 8 9 10 11 12 13 14 @WebServiceProvider @ServiceMode(value=Service. e.BindingType annotation it MUST be May 7.).Endpoint Simple static reply. ..ws. String replyElement = "<n:ack xmlns:n=’.Mode.1 67 .ws.. } } 5...g. } } Using JAXB to read the input message and set the reply 1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 @WebServiceProvider @ServiceMode(value=Service. Acknowledgement reply = new Acknowledgement(.. a Binding. Other configuration information may be set at any time after the creation of an Endpoint but before its publication.newInstance(. 2007 JAX-WS 2. An endpoint consists of an object that acts as the Web service implementation (called here implementor) plus some configuration information. return new JAXBSource(jc.ws. Unmarshaller u = jc...

publish method is conditional to the presence of the appropriate permission as described in section 5.publish method is ”http” or ”https” then an implementation MUST use the SOAP 1. Endpoint e = Endpoint.spi.1/HTTP binding (see chapter 10) as the binding for the newly created endpoint.xml. ♦ Conformance (Other Bindings): An implementation MAY support using the Endpoint. Object implementor) Creates and publishes an Endpoint for the given implementor.1). create(String bindingID.1 May 7.publish method with addresses whose URL scheme is neither ”http” nor ”https”. ♦ Conformance (Default Endpoint Binding): In the absence of a specified binding. If the bindingID is null and no binding information is specified via the javax.BindingType annotation then a default SOAP 1. MUST be invoked. then invoking the publish(String address) method on the resulting endpoint. Published endpoints are active and capable of receiving incoming requests and dispatching them to their implementor. The created Endpoint is then returned as the value of the method.2. Object implementor) Creates and returns an Endpoint for the specified binding and implementor. After any injections have been performed and before any requests are dispatched to the implementor. Injection of the WebServiceContext.1 / HTTP binding MUST be used.ws. The publish(String. the implementor method which carries a javax. An implementor object MUST be either an instance of a class annotated with the @WebService annotation according to the rules in chapter 3 or an instance of a class annotated with the WebServiceProvider annotation and implementing the Provider interface (see 5. The binding is chosen by default based on the URL scheme of the provided address (which must be a URL). test). The success of the Endpoint. publish(String address. MUST happen the first time the endpoint is published. If a suitable binding if found.Object) method is provided as a shortcut for the common operation of creating and publishing an Endpoint. Service APIs used else a default binding of SOAP 1.annotation.2. if present.PostConstruct annotation. the endpoint is created then published as if the Endpoint.2) by calling the createEndpoint and createAndPublishEndpoint methods respectively. 2007 .Chapter 5.2 Publishing An Endpoint is in one of three states: not published (the default). Endpoint implementors MAY use the WebServiceContext facility (see 5.3) to access the message context and other information about the request currently being served. 68 JAX-WS 2.publish(String address) method had been called. 5. if the URL scheme for the address argument of the Endpoint.publish("http://localhost:8080/test". Object implementor) Method): The effect of invoking the publish method on an Endpoint MUST be the same as first invoking the create method with the binding ID appropriate to the URL scheme used by the address.ws. Such a method MUST satisfy the requirements for lifecycle methods in JSR-250 [31]. if requested. ♦ Conformance (Endpoint publish(String address.1 / HTTP binding MUST be used. These methods MUST delegate the creation of Endpoint to the javax.3. The following code provides an example of its use: 1 2 3 // assume Test is an endpoint implementation class annotated with @WebService Test test = new Test().Provider SPI class (see 6.xml. published or stopped.

the effects of configuration changes on a currently published endpoint are undefined.1 Example The following example shows the use of the publish(Object) method using a hypothetical HTTP server API that includes the HttpServer and HttpContext classes. as described in section 5. 2007 JAX-WS 2.4). then got stopped.ws. the changes they entail may not be reflected on the endpoint until the next time it is published. ♦ Conformance (WSDL Publishing): An Endpoint that uses the SOAP 1. the Binding in use and the set of metadata documents specified on the endpoint (see 5.2. so its implementor should be written so as to support multiple threads.5. An Endpoint that uses any other binding defined in this specification in conjunction with the HTTP transport SHOULD make its contract available using the same convention. In other words. Applications that wish to modify the configuration information (e.publish methods described above is conditional to the presence of the appropriate permission as described in section 5. publish(Object serverContext) Publishes the endpoint using the specified server context. A stopped endpoint may not be restarted.2. May 7. The WSDL contract for an endpoint is created dynamically based on the annotations on the implementor class. ♦ Conformance (Publishing over HTTP): If the Binding for an Endpoint is a SOAP (see 10) or HTTP (see 11) binding. Although the various setter methods on Endpoint must always store their arguments so that they can be retrieved by a later invocation of a getter. Publication of an Endpoint can be achieved by invoking one of the following methods: publish(String address) Publishes the endpoint at the specified address (a URL).1 document at the publishing address suffixed with ”?WSDL” or ”?wsdl”. javax. For finer control over the threads used to dispatch incoming requests. Stopped endpoint were in the published until some time ago. After the stop method returns. 1 2 // assume Test is an endpoint implementation class annotated with @WebService Test test = new Test().2. The synchronized keyword may be used as usual to control access to critical sections of code. an application can directly set the executor to be used.2. then an implementation MUST support publishing the Endpoint to a URL whose scheme is either ”http” or ”https”.xml.1/HTTP binding (see 10) MUST make its contract available as a WSDL 1. Stopped endpoints cannot be published again. It is RECOMMENDED that an implementation provide a way to access the contract for an endpoint even when the latter is published over a transport other than HTTP. The stop method can be used to stop publishing an endpoint. The address MUST use a URL scheme compatible with the endpoint’s binding. The server context MUST contain address information for the resulting endpoint and it MUST be compatible with the endpoint’s binding.g.2. The success of the two Endpoint.1 69 . the metadata) for an Endpoint must make sure the latter is in the not-published state.2. It is an error to invoke a publish method on a stopped endpoint. An Endpoint will be typically invoked to serve concurrent requests. 5. the runtime MUST NOT dispatch any further invocations to the endpoint’s implementor.3.Endpoint Non published endpoints are inactive.7.

If it is. an implementation MUST check whether a SecurityManager is installed with the application.createContext("/test"). HttpContext context = server. At runtime then. By setting the metadata of an Endpoint.start(). In order to do so.transform.3 Publishing Permission For security reasons.. If the permission is not granted.0 defines a new permission class. Endpoint endpoint = Endpoint.newFixedThreadPool(10)).1 May 7.xml. Service APIs 3 4 5 6 7 8 HttpServer server = HttpServer.ws.10).lang.create(SOAPBinding. then using the given URI in the appropriate construct (e.xml. to make sure that the WSDL or XML Schema document that is published contains information that cannot be represented using built-in Java annotations (see 7). and one named permission. 2007 . the application MUST use the systemId property of the javax. endpoint.4 Endpoint Metadata A set of metadata documents can be associated with an Endpoint by means of the setMetadata(List<Source>) method.Chapter 5. javax.2.2.Source class by setting its value to an absolute URI that uniquely identifies it among all supplied metadata documents. ♦ Conformance (Unknown Metadata): An implementation MUST ignore metadata documents whose type it does not recognize. test). implementations MUST NOT publish the endpoint and they MUST throw a java. 5.5 Determining the Contract for an Endpoint This section details how the annotations on the endpoint implementation class and the metadata for an endpoint instance are used at publishing time to create a contract for the endpoint. For instance. JAX-WS 2.1 and XML Schema 1. server. ♦ Conformance (Required Metadata Types): An implementation MUST support WSDL 1. wsdl:import or xsd:import).WebServicePermission.g. Note that the specified server context uses its own executor mechanism. When specifying a list of documents as metadata.g.2. any other executor set on the Endpoint instance would be ignored by the JAX-WS implementation.setExecutor(Executor.0 documents as metadata. This way it is possible. If such an annotation 70 JAX-WS 2. e.create(new InetSocketAddress(8080). 5. server. a WSDL document may import one or more XML Schema documents. publishEndpoint. 5.SecurityException. administrators may want to restrict the ability of applications to publish Web service endpoints. an application may need to establish references between them.publish(context). Both the WebService and WebServiceProvider annotations define a wsdlLocation annotation element which can be used to point to the desired WSDL document for the endpoint. implementations MUST verify that the application has the WebServicePermission identified by the target name publishEndpoint before proceeding. To this end.SOAP11HTTP_BINDING. an application can bypass the automatic generation of the endpoint’s contract and specify the desired contract directly. ♦ Conformance (Checking publishEndpoint Permission): When any of the publish methods defined by the Endpoint class are invoked.

5. we distinguish two cases: that of a SEI-based endpoint (i. it is not the empty string). 5. In the context of the Java EE Platform.ws. according to the rules in section 5.2/HTTP Binding A JAX-WS implementation MUST NOT generate a WSDL description for the endpoint.2. there may not be an equivalent for the notion of metadata as described in 5. the requirements in this section are also applicable to the publishing of an endpoint via declarative means. 2007 JAX-WS 2. Any Implementation-Specific Binding A JAX-WS implementation MAY generate a WSDL description for the endpoint. If the wsdlLocation annotation element is the empty string. JSR-109 [15] defines deployment descriptor elements that may be used to override the value of the wsdlLocation annotation element.5. a SEI-based endpoint MUST have an associated contract.Endpoint element is present on the endpoint implementation class and has a value other than the default one (i. 5. In addition to the case in which the Endpoint API is explicitly used. then a JAX-WS implementation MUST NOT generate a WSDL description for the endpoint.1 SEI-based Endpoints For publishing to succeed. HTTP Binding A JAX-WS implementation MUST NOT generate a WSDL description for the endpoint. A generated contract MUST follow the rules in chapter 3 and those in the JAXB specification [10].3.5. in a servlet container.2. SOAP 1.e.3 below. If the wsdlLocation annotation element is the empty string.1/HTTP Binding A JAX-WS implementation MUST generate a WSDL description for the endpoint based on the rules in section 5.2. javax. an endpoint that is annotated with a WebService annotation) and that of a Provider-based endpoint.5. In this case.g.xml. May 7. the rules in this section MUST be applied using an empty set of metadata documents as the metadata for the endpoint.2. e.2 Provider-based Endpoints Provider-based endpoints SHOULD have a non-empty wsdlLocation pointing to a valid WSDL description of the endpoint. Note: This requirements guarantee that future versions of this specification may mandate support for additional WSDL binding in conjunction with the predefined binding identifiers without negatively affecting existing applications. then a JAX-WS implementation MUST use the document referred to from the wsdlLocation annotation element to determine the contract. Please refer to that specification for more details. In such an occurrence.5. As we specify additional rules to be used in determining the contract for an endpoint.1 71 .2.4.2.e. then a JAX-WS implementation must obey the following rules. depending on the binding used by the endpoint: SOAP 1.

In the Java SE platform. a JAX-WS implementation MUST patch the endpoint address in the root description document to match the actual address the endpoint is deployed at.Chapter 5. MUST be a relative URL. since the extensibility of WSDL would make it a futile exercise. this specification does not attempt to capture all possible binding properties in its APIs.5. The document it points to MUST be packaged with the application. The value of the wsdlLocation annotation element on an endpoint implementation class.) At runtime. because it captures the signature-related aspects of the soap:binding binding extension in WSDL 1.1. An implementation MUST NOT patch any other location attributes. In order to state the requirements for patching the locations of any wsdl:import-ed or xsd:import-ed documents. There are some restrictions on the packaging of the description and any associated metadata documents. (The @SOAPBinding annotation is a bit of a hybrid.3 Use of @WebService(wsdlLocation) and Metadata A WSDL document contains two different kinds of information: abstract information (i.5. Please note that. is consulted to determine binding information. The goal of these restrictions is to make it possible to publish an endpoint without forcing a JAX-WS implementation to retrieve. when an endpoint is published. Rather. When running on the Java EE platform. bindings and ports) which affects the choice of protocol and transport as well as the on-the-wire format of the messages.e.2. Annotations (see 7) are provided to capture the former aspects but not the latter. to distinguish it from any WSDL documents it might import. it MUST follow the requirements in section 5. In terms of priority. although the catalog facility (see 4. 2007 .1 May 7. let’s call this document the ”root description document”. and the metadata documents are secondary. A JAX-WS implementation MUST patch the location attributes of all wsdl:import and xsd:import statement in local documents that point to local documents. Service APIs 5. and binding-related one (i. Moreover. the description specified using the wsdlLocation annotation element. a description for it.4) is used to resolve any absolute URLs encountered while processing the root description document or any documents transitively reachable from it via wsdl:import and xsd:import statements. store and patch multiple documents from potentially remote sites. if present. annotations must be followed for all the abstract aspects of an interaction.e.4 below (”Application-specified Service”). a Source object which is a member of the list of metadata documents and whose systemId property is equal to the URL in question). non-default wsdlLocation annotation element. the dispositions in the JSR-109 specification apply. portTypes and any schema-related information) which affects the format of the messages and the data being exchanged. In the absence of a non-empty. it is reachable from a local document via an import statement whose location is either a relative URL or an absolute URL for which there is a corresponding metadata document (i. it is the root description document. using the wsdl:service and wsdl:port qualified names as a key. Although the choice of binding is made at the time an endpoint is created. if present.e. those absolute URLs will not be rewritten when the importing 72 JAX-WS 2. but binding information has to come from somewhere else. relative URLs are treated as resources. comes first. or 2. At publishing time. if any.2. let’s define a document as being local if and only if 1. the metadata documents are consulted to identify as many description components as possible that can be reused when producing the contract for the endpoint. For ease of identification.

in that the ”imports” and ”includes” relationships existing between documents when the metadata was supplied to the endpoint MUST be respected at publishing time. but they MUST follow the general rule that any applicationprovided metadata element takes priority over an implementation-generated one.2. say D. but a metadata document. When publishing the main WSDL document for an endpoint.ws. including an appropriate WSDL binding element referencing portType P. say S.4 Application-specified Service One of the metadata documents. an implementation MUST ensure that all references between documents are correct and resolvable.5. When resolving URI references to other documents when processing metadata documents or any of the documents they may transitively reference.5. for better readability. For instance. metadata documents have priority over catalog-based mappings. Implementations MAY support other use cases. contains a definition for the WSDL portType whose qualified name. while keeping in mind the processing rules in the preceding paragraphs. No schema genMay 7. As a guideline.5. even if the catalog maps them to resources packaged with the application. In order to simplify an implementor’s task. a JAX-WS implementation MUST create a new description for S. this specification requires that only a small number of well-defined scenarios in which the application provides metadata documents be supported. The exception to using a metadata document as supplied by the application without any modifications is the address of the wsdl:port for the endpoint. matches that specified by the endpoint being published. the term ”metadata document” should be interpreted as also covering the description document pointed to by the wsdlLocation annotation element (if any).Endpoint document is published. The scenarios which are required to be supported are the following: 5. In what follows. The metadata document D MUST be imported/included so that the published contract uses the definition of P provided by D. It is an error if more than one metadata document contains a definition for the sought-after service S. with the exception of the overriding of a port address. contains a definition for a WSDL service whose qualified name . The renaming MUST be consistent. In this case. No further generation of contract-related artifacts may occur.xml. matches that specified by the endpoint being published. a JAX-WS implementation MUST use the catalog facility defined in section 4. Moreover. since documents resolved via the catalog are not considered local. say D. 5. except when there is a metadata document whose system id matches the URI in question. the generated contract must reuse as much as possible the set of metadata documents provided by the application. In this case.2. different URLs. a JAX-WS implementation MUST use D as the service description.4.1 73 .2. javax. the same metadata document SHOULD NOT be published at multiple. In other words. say P. The implementation MUST also override the port address in D and the location and schemaLocation attributes as detailed in the preceding paragraphs. 2007 JAX-WS 2.5 Application-specified PortType No metadata document contains a definition for the sought-after service S. This may require remapping the metadata documents to URLs different from those set as their systemId property. which MUST be overridden so as to match the address specified as an argument to the publish method or the one implicit in a server context. if the application-provided metadata contains a definition for portType foo that in no case should the JAX-WS implementation create its own foo portType to replace the one provided by the application in the final contract for the endpoint.

Executor. In this case. When present. leaving all the WSDL-specific aspects of the contract up to the runtime. The first one represents an application that has full control over all aspects of the contract. Like in the preceding case. the implementation MUST override any location and schemaLocation attributes. Table 5. 5.Chapter 5. The JAX-WS runtime just uses what the application provided.5.7). 74 JAX-WS 2. i.2.util.xml. Note: The three scenarios described above cover several applicative use cases. The second one corresponds to an application that defines all abstract aspects of the WSDL. with a minimum of adjustments to ensure consistency.6 Application-specified Schema or No Metadata No metadata document contains a definition for the sought-after service S and portType P. the third case represents an application that uses one or more well-known schema(s). Description Specifies the qualified name of the service. leaving up to the JAX-WS runtime to generate the concrete portions of the contract. Specifies the qualified name of the port. the implementation MUST reuse the schema for T among the available metadata documents. since the latter are naturally more suited to a more dynamic usage. if any.port QName eration occurs. The executor will then be used to dispatch any incoming requests to the application. For instance.ws. Like in the previous case. and wants to reuse it as-is. Finally. the WSDL-related properties override the values specified using the WebService and WebServiceProvider annotations.6 Endpoint Properties An Endpoint has an associated set of properties that may be read and written using the getProperties and setProperties methods respectively. an application that publishes a provider endpoint can decide at runtime which web service to impersonate by using a combination of metadata documents and the properties described in this section. It is an error if more than one metadata document contains a definition for the sought-after portType P. leaving WSDL and schema generation up to the JAX-WS (and JAXB) implementation.service QName . portType(s) and schema(s).2.2. The setExecutor and getExecutor methods of Endpoint can be used to modify and retrieve the executor configured for a service. 5. javax.wsdl . say T.as P is assumed to embed or import schema definitions for all the types/elements it requires.1 lists the set of standard Endpoint properties.7 Executor Endpoint instances can be configured with a java. 2007 . When it comes to generating a schema for a certain target namespace. 5. This functionality is most useful with provider objects (see section 7. possibly taking advantage of lots of facets/constraints that JAXB cannot capture. This use case also covers an application that does not specify any metadata. It is an error if more than one schema documents specified as metadata for the endpoint attempt to define components in a namespace T used by the endpoint. the implementation MUST override any schemaLocation attributes.1: Standard Endpoint properties. a JAX-WS implementation MUST generate a complete WSDL for S.concurrent.1 May 7. Service APIs Name Type Table 5.e.

5.ws. to dispatch incoming requests.WebServiceContext ♦ Conformance (Use of Executor): If an executor object is successfully set on an Endpoint via the setExecutor method. A returned W3CEndpointReference MUST also contain the specified referenceParameters.WebServiceException MUST be thrown. An implementation MUST throw java.WebServiceException if the Endpoint instance has not been published.WebServiceContext The javax.EndpointReference for the Endpoint instance.wsaddressing.ws. If the binding is SOAP 1.wsaddressing. May 7.xml.xml.ws.UnsupportedOperationException if the Endpoint instance uses the XML/HTTP binding. an implementation MUST use its own executor. getEndpointReference(Class<T> clazz.xml.1/HTTP or SOAP 1. The WebServiceContext is treated as an injectable resource that can be set at the time an endpoint is initialized.EndpointReference of type clazz for a published Endpoint instance.xml.ws.5.ws. An implementation SHOULD throw a java.ThreadPoolExecutor or analogous mechanism.xml.lang.WebServiceException if the Endpoint instance has not been published.WebServiceContext interface makes it possible for an endpoint implementation object and potentially any other objects that share its execution context to access information pertaining to the request being served. An implementation MUST throw java.W3CEndpointReference MUST be returned.2. ♦ Conformance (Default Executor): If an executor has not been set on an Endpoint. 5. List<Element> referenceParameters) Creates and returns and javax.IllegalStateException if it detects such a usage.xml.8 javax.lang.EndpointReference The following methods can be used on a published Endpoint to retrieve an javax. then an implementation MUST use it to dispatch incoming requests upon publication of the Endpoint by means of the publish(String address) method. An implementation MUST throw a javax.W3CEndpointReference. javax.1 75 . If clazz is of type javax.xml. The result of invoking any methods on the WebServiceContext of a component outside the invocation of one of its web service methods is undefined. An implementation MUST throw a javax.ws.ws.ws. then the returned W3CEndpointReference MUST contain the specified referenceParameters. In Java SE. an implementation MAY use the specified executor or another one specific to the server context being used.concurrent. getEndpointReference(List<Element> referenceParameters) Creates and returns and javax.UnsupportedOperationException if the Endpoint instance uses the XML/HTTP binding.lang. 2007 JAX-WS 2.2/HTTP. The WebServiceContext object will then use thread-local information to return the correct information regardless of how many threads are concurrently being used to serve requests addressed to the same endpoint object.ws.xml.EndpointReference for a published Endpoint. If the Class clazz is not a subclass of EndpointReference or the Endpoint implementation does not support EndpointReferences of type clazz a javax.xml.xml.3.xml.ws. If publishing is carried out using the publish(Object serverContext)) method. the resource injection denoted by the WebServiceContext annotation is REQUIRED to take place only when the annotated class is an endpoint implementation class.3 javax. then a javax.ws.util.xml. a java.ws.

then the resource MUST be injected into a field or a method. MUST have their respective default values. if they appear.1 MessageContext The message context made available to endpoint instances via the WebServiceContext acts as a restricted window on to the MessageContext of the inbound message following handler execution (see chapter 9). shareable elements. The restrictions are as follows: • Only properties whose scope is APPLICATION are visible using a MessageContext obtained from a WebServiceContext. • New properties set in the context are set in the underlying MessageContext with APPLICATION scope. the name and mappedName elements are ignored. As a consequence. the Set returned by keySet only includes properties with APPLICATION scope.Chapter 5. • The authenticationType.Object (the default) or javax. the type of the field or the type of the JavaBeans property defined by the method MUST be javax. it is recommended that the method be declared as non-public. The following constraints apply to the annotation elements of a Resource annotation used to inject a WebServiceContext: • The type element MUST be either java.3. Note: When using method-based injection.xml. on Java SE there is no point in declaring a resource of type WebServiceContext on the endpoint class itself (instead of one of its fields/methods). resources of type WebServiceContext are treated just like all other injectable resources there and are subject to the constraints prescribed by the platform specification [32]. Service APIs The following code shows a simple endpoint implementation class which requests the injection of its WebServiceContext: 1 2 3 4 5 6 7 @WebService public class Test { @Resource private WebServiceContext context.xml. 5. since it won’t be accessible at runtime via JNDI.. otherwise it will be exposed as a web service operation.WebServiceContext.. Moreover. public String reverse(String inputString) { . Alternatively.1 May 7. 76 JAX-WS 2.Resource annotation defined by JSR-250 [31] is used to request injection of the WebServiceContext.lang.annotation.ws. the get method returns null for properties with HANDLER scope. If the former. When running on the Java SE platform. When running on the Java EE 5 platform.ws. the field/method type must be assignable from the type described by the annotation’s type element. In this case. The above restriction on type guarantees that a resource type of WebServiceContext is either explicitly stated or can be inferred from the annotated field/method declaration. } } The javax. the method can be marked with the @WebMethod(exclude=true) annotation to ensure it will not be part of the generated portType for the service. 2007 .WebServiceContext.

wsaddressing. An attempt to remove a property whose scope is HANDLER in the underlying MessageContext results in an IllegalArgumentException being thrown. restricting access to context properties in this way ensures that endpoint implementations can only access properties intended for their use. May 7. javax.1 77 . each insert operation being carried out as if enclosed by a try/catch block that traps any IllegalArgumentException.ws.ws. • Only properties whose scope is APPLICATION can be removed using the context.wsaddressing. Consequently.5. • The Map.xml. 2007 JAX-WS 2.4.W3CEndpointReferenceBuilder Occasionally it is necessary for one application component to create an EndpointReference for another web service endpoint. 5. putAll is not atomic: it silently ignores properties whose scope is HANDLER and it never throws an IllegalArgumentException. The MessageContext is used to store handlers information between request and response phases of a message exchange pattern.W3CEndpointReferenceBuilder • An attempt to set the value of property whose scope is HANDLER in the underlying MessageContext results in an IllegalArgumentException being thrown.xml. Each property is inserted individually. The W3CEndpointReferenceBuilder class provides a standard API for creating W3CEndpointReference instances for web service endpoints.4 javax.putAll method can be used to insert multiple properties at once.

Service APIs 78 JAX-WS 2.Chapter 5. 2007 .1 May 7.

xml.1 javax. ♦ Conformance (Read-only handler chains): An implementation MAY prevent changes to handler chains configured by some other means (e. via a deployment descriptor) by throwing UnsupportedOperationException from the setHandlerChain method of Binding 6. The Provider SPI allows an application to use a different JAX-WS implementation from the one bundled with the platform without any code changes. i.Binding The javax. Binding provides methods to manipulate the handler chain configured on an instance (see section 9. e.spi.xml. A concrete binding is identified by a binding id.xml.1) and Endpoint (see 5. the ”http” URI scheme.2.1).Provider required): An implementation MUST provide May 7.Chapter 6 Core APIs This chapter describes the standard core APIs that may be used by both client and server side applications. Chapter 10 describes the JAX-WS SOAP binding.xml. a URI.2 javax. Applications obtain a Binding instance from a BindingProvider (a proxy or Dispatch instance) or from an Endpoint using the getBinding method (see sections 4.ws.Binding interface acts as a base interface for JAX-WS protocol bindings.ws. Such identifiers SHOULD include a domain name controlled by the implementation’s vendor.Provider Provider is an abstract service provider interface (SPI) factory class that provides various methods for the creation of Endpoint instances and ServiceDelegate instances.g. 5.spi. chapter 11 describes the JAX-WS XML/HTTP binding. ♦ Conformance (Concrete javax.g. Implementations MAY support additional bindings. the identifier for an implementation-specific binding SHOULD use a URI scheme that includes a domain name or equivalent. These methods are designed for use by other JAX-WS API classes. 6. This specification defines a number of standard bindings and their corresponding identifiers (see chapters 10 and 11).e. In order to minimize conflicts.1 79 .2. Bindings to specific protocols extend Binding and may add methods to configure specific aspects of that protocol binding’s operation.ws.2). 2007 JAX-WS 2. such as Service (see 4.ws.2) and are not intended to be called directly by applications.

The implementation will then attempt to load the class with the given class name using the current context class loader or. is used as the UTF-8 encoded name of the implementation class. Core APIs a concrete class that extends javax.Class. i.Provider.Chapter 6. 2.spi.2.BindingType annotation then a default SOAP1.spi.1 Configuration The Provider implementation class is determined using the following algorithm. if present. At each step.xml. a class annotated with the @WebService annotation according to the rules in chapter 3. missing one.xml.1 May 7. see 5.util. Object implementor) Creates and publishes an Endpoint for the given implementor. 6.lang.2 Creating Endpoint Objects Endpoints can be created using the following methods on Provider: createEndpoint(String bindingID.2.ws.1.ws.xml.e.Provider.Object) method is provided as a shortcut for the common operation of creating and publishing an Endpoint.Provider is defined.e. i. The created Endpoint is then returned as the value of the method.2.home}/lib/jaxws.spi. Such a class MUST have a public constructor which takes no arguments. It corresponds to the static publish method defined on the Endpoint class. 4. The steps listed below are performed in sequence. 6.ws. or • an instance of a provider class. If a resource with the name of META-INF/services/javax.Properties. If a suitable binding if found. Object implementor) Creates and returns an Endpoint for the specified binding and implementor. If the ${java.Provider exists. The binding is chosen by default based on the URL scheme of the provided address (which must be a URL).properties file exists and it is readable by the java. An implementor object MUST be either: • an instance of a SEI-based endpoint class. 1. 3.load(InputStream) method and it contains an entry whose key is javax. the endpoint is created then published as if the Endpoint. As soon as a step results in an implementation class being successfully loaded. then its first line.1.If the bindingId is null and no binding information is specified via the javax. at most one candidate implementation class name will be produced. then its value is used as the name of the implementation class. createAndPublishEndpoint(String address.ws.1/HTTP binding MUST be used. 80 JAX-WS 2. If a system property with the name javax. 2007 .publish(String address) method had been called. a class implementing the Provider interface and annotated with the WebServiceProvider annotation according to the rules in 5.ws. the algorithm terminates. then the value of that entry is used as the name of the implementation class. The createAndPublishEndpoint(String.xml. a default implementation class name is used. the java.spi. Finally.forName(String) method.xml.

readEndpointReference(javax.5 Getting Port Objects The following method can be used to get a proxy for a Port.xml.4 EndpointReferences The Provider class provides the following methods to create EndpointReference instances.xml.spi. This is the class that javax.ServiceDelegate 6..ws.7. 2007 JAX-WS 2. 6.ServiceDelegate required): An implementation MUST provide a concrete class that extends javax.xml.. 6. except the static create methods to.3 Creating ServiceDelegate Objects javax. The returned proxy MUST use the epr to determine the endpoint address and any reference parameters that MUST be sent on endpoint invocations.ws.3 javax. String wsdlDocumentLocation.ws. QName serviceName.2.3.xml.ws. In the dynamic case where there is no service class generated it will be javax. getPort(EndpointReference epr.ws.xml. createW3CEndpointReference Creates a W3CEndpointReference using the specified String address. WebServiceFeature. 6. ♦ Conformance (Concrete javax. then invoking the publish(String address) method on the resulting endpoint.EndpointReference from the infoset contained in source.xml. and List<Element> referenceParameters parameters.ws.2. List<Element> metadata. QName portName. The serviceClass is used by the ServiceDelegate to get access to the annotations. The epr MUST NOT be used directly as the value of an WS-Addressing header such as wsa:ReplyTo. The specified features MUST be enabled/disabled and configured as specified.ServiceDelegate ♦ Conformance (Provider createAndPublishEndpoint Method): The effect of invoking the createAndPublishEndpoint method on a Provider MUST be the same as first invoking the createEndpoint method with the binding ID appropriate to the URL scheme used by the address.spi.spi.spi. When starting from WSDL the serviceClass will be the generated service class as described in section 2.Source source) Unmarshalls and returns a javax.xml.ws.1 81 .ServiceDelegate class is an abstract class that implementations MUST provide. QName serviceName.spi.transform.xml. May 7.ServiceDelegate The javax.Service 4.1 class delegates all methods.Service. features) Gets a proxy for the sei that can be used to invoke operations on the endpoint referred to by the epr. 6.3 can be created using the following method on Provider: createServiceDelegate(URL wsdlDocumentLocation. Class<T> sei.xml. Class serviceClass) Creates and returns a ServiceDelegate for the specified service.6.ws.spi.ServiceDelegate.ws.xml. ServiceDelegate is defined as an abstract class for future extensibility purpose.2. javax.

for XML/HTTP is is HTTPException. both kinds of errors are mapped to WebServiceException. } catch (SOAPFaultException e) { QName soapFaultCode = e. } 6. if (someProblem) { 82 JAX-WS 2.ProtocolException A base class for exceptions related to a specific protocol binding.xml. a broken connection or an unresolvable server name). Core APIs 6.invoke(request). 6. Editors Note 6.HTTPException A subclass of ProtocolException.1 Client Side Example 1 2 3 4 5 6 7 try { response = dispatch.ws. an implementation MUST ensure that the exception is an instance of the appropriate ProtocolException subclass. 2007 . For SOAP the appropriate ProtocolException subclass is SOAPFaultException.xml.4.soap. much like ProtocolException is. ♦ Conformance (Protocol specific fault consumption): When an implementation catches an exception thrown by a service endpoint implementation and the cause of that exception is an instance of the appropriate ProtocolException subclass for the protocol in use.2 Server Side Example 1 2 3 public void endpointOperation() { .ws.ws.4 Exceptions The following standard exceptions are defined by JAX-WS.getFault().1 Protocol Specific Exception Handling ♦ Conformance (Protocol specific fault generation): When throwing an exception as the result of a protocol level fault.g. but the latter kind would be more usefully mapped to its own exception type. javax. Subclasses are used to communicate protocol level fault information to clients and may be used by a service implementation to control the protocol specific fault representation. javax. Currently.Chapter 6.getFaultCodeAsQName()... an implementation MUST reflect the information contained in the ProtocolException subclass within the generated protocol level fault.ws.4. may be used to carry HTTP specific information.SOAPFaultException A subclass of ProtocolException.1 A future version of this specification may introduce a new exception class to distinguish errors due to client misconfiguration or inappropriate parameters being passed to an API from errors that were generated locally on the sender node as part of the invocation process (e.4. may be used to carry SOAP specific information.xml..xml.WebServiceException A runtime exception that is thrown by methods in JAX-WS APIs when errors occur during local processing.1 May 7.1. javax..http. javax. 6.1. .

6.xml.ws.WebServiceFeature MUST provide a constructor argument and/or method to allow the web service developer to set the value of the enabled property.5 javax. Each derived type should provide either a constructor argument and/or a method that will allow the web service developer to set the enabled property. Each feature is derived from the javax.WebServiceFeatures): Each derived type of javax.xml. This allows the web service developer to pass different types of WebServiceFeatures to the various JAX-WS APIs that utilize them. The public default constructor MUST by default set the enabled property to true.. A JAX-WS 2.getSOAPFactory(). ♦ Conformance (javax. faultactor. } .AddressingFeature The AddressingFeature is used to control the use of WS-Addressing[24] by JAX-WS. Each WebServiceFeature MUST have a public static final String ID field that is used to uniquely identify the feature.ws..1 introduces three standard features.2 One-way Operations ♦ Conformance (One-way operations): When sending a one-way message. throw new SOAPFaultException(fault). each feature should be documented using JavaDocs on the derived classes.WebServiceFeature class. Using this feature with any May 7.1 javax.xml.ws. It is important that web services developers be able to enable/disable specific features when writing their web applications. Also.WebServiceFeature 4 5 6 7 8 9 SOAPFault fault = soapBinding.1/HTTP or SOAP 1. For example.1 implementations.xml. detail).soap.1 83 .WebServiceFeature JAX-WS 2. javax.createFault( faultcode.xml.ws. The WebServiceFeature class also has an enabled property that is used to store whether a particular feature should be enabled or disabled.ws.1 introduces the notion of features. The meaning of enabled or disabled is determined by each individual WebServiceFeature. faultstring.ws. This feature MUST be supported with the SOAP 1. A feature is associated with a particular functionality or behavior. 6. AddressingFeature.2/HTTP bindings. Since vendors can specify their own features. 6.1 implementation may define its own features but they will be non-portable across all JAX-WS 2. a developer may choose to implement WS-Addressing himself while using the Dispatch and Provider APIs and thus he MUST be able to tell JAX-WS to disable addressing.xml. Some features may only have meaning when used with certain bindings while other features may be generally useful.4. ♦ Conformance (enabled property): Each derived type of javax. An implementation MUST honor the value of the enabled property of any supported WebServiceFeature. care MUST be taken when creating a feature ID so as to not conflict with another vendor’s ID.ws.WebServiceFeature MUST contain a public static final String ID field that uniquely identifies the feature against all features of all implementations. JAX-WS 2.xml. implementations MUST throw a WebServiceException if any error is detected when sending the message. MTOMFeature and RespectBindingFeature as well as the base WebServiceFeature class.5. 2007 JAX-WS 2. } 6.5.

14.xml.5.xml.xml. Applications should instead use concrete implementations of EndpointReference such as javax.1 will bind the W3CEndpointReference class to the W3C EndpointReference XML Schema in the WSDL.Chapter 6.2 javax. Enabling this feature on the client will cause the JAX-WS runtime to include WS-Addressing headers in SOAP messages as specified by WS-Addressing[24]. This feature should be used instead of the javax.W3CEndpointReference The W3CEndpointReference class is a concrete implementation of the javax.2/HTTP bindings.xml.soap. The AddressingFeature has one property required.14.ws.1 javax.setMTOMEnabled().2 javax.ws.5. 6.SOAP12HTTP MTOM BINDING and the javax.1/HTTP or SOAP 1.ws.1. 6.ws. This feature MUST be supported with the SOAP 1.EndpointReference class and is used to reference endpoints that are compliant with the W3C Web Services Addressing 1.W3CEndpointReference which will provide better binding.5. 2007 .0 .xml. Enabling this feature on the server will result in the runtime being capable of consuming and responding to WS-Addressing headers. JAX-WS implementations are required to support the W3CEndpointReference class but they may also provide other EndpointReference subclasses that represent different versions of Addressing.0[24]. This may be necessary if a client or endpoint needs to implement Addressing themselves.soap.soap. Applications may also use the EndpointReference class in method signatures.ws..2.ws. 84 JAX-WS 2.1 May 7.SOAPBinding. javax. that can be configured to control whether all incoming messages MUST contain Addressing headers. JAXB 2.EndpointReference The abstract EndpointReference class is used by the JAX-WS APIs to reference a particular endpoint in accordance with the W3C Web Services Addressing 1.SOAPBinding.SOAPBinding.ws. 6. Developers may choose to prevent this from happening by explicitly disabling the AddressingFeature.1 will will bind the EndpointReference base class to xs:anyType.ws.soap. The AddressingFeature MAY be automatically enabled if the WSDL specifies its use in a manner supported by an implementation.Core[24] recommendation.SOAP11HTTP MTOM BINDING. Each concrete instance of an EndpointReference MUST contain a wsa:Address.1. Core APIs other binding is undefined. This feature corresponds to the Addressing annotation described in section 7.1. a client that desires to use nonanonymous ReplyTo can do so by disabling the AddressingFeature and by using Dispatch<Source> with Message mode. JAXB 2.xml.xml.MTOMFeature The MTOMFeature is used to specify if MTOM should be used with a web service. Disabling this feature will prevent a JAX-WS runtime from processing or adding WS-Addressing headers from/to SOAP messages even if the associated WSDL specifies otherwise. This feature corresponds to the MTOM annotation described in section 7. For example. Applications may use this class to pass EndpointReference instancess as method parameters or return types.xml. Using this feature with any other bindings is undefined.

The MTOMFeature has one property threshold.MTOMFeature): An implementation MUST support the javax. that can be configured to serve as a hint for which binary data SHOULD be sent as an attachment.1 85 . It has a corresponding RespectBinding annotation described in section 7.xml.RespectBindingFeature The RespectBindingFeature is used to control whether a JAX-WS implementation MUST respect/honor the contents of the wsdl:binding associated with an endpoint.14.0.xml.5.WebServiceFeature Enabling this feature on either the server or client will result the JAX-WS runtime using MTOM and for binary data being sent as an attachment. javax.3 javax. 6. All required wsdl:extensions MUST be supported and honored by a JAX-WS implementation unless a specific wsdl:extension has be explicitly disabled via a WebServiceFeature.5. May 7.soap. ♦ Conformance (javax.xml.ws. The threshold MUST not be negative.xml.3.ws.ws.RespectBindingFeature is enabled. In order to not break backward compatibility with JAX-WS 2. The default value is 0.ws.RespectBindingFeature): When the javax. a JAX-WS implementation MUST inspect the wsdl:binding at runtime to determine result and parameter bindings as well as any wsdl:extensions that have the required=true attribute.6. ♦ Conformance (javax.xml.MTOMFeature and its threshold property.soap. The threshold is the size in bytes that binary data SHOULD be in order to be sent as an attachment.xml. 2007 JAX-WS 2. the behavior with regards to respecting the wsdl:binding when this feature is disabled is undefined.ws.ws.

Core APIs 86 JAX-WS 2.1 May 7.Chapter 6. 2007 .

g. for this reason. for each property we list the default value. placed on a program element of the appropriate type. e. an implementation MUST NOT invoke the remote operation being invoked. an implementation may perform any correctness checks at deployment time.1 87 .g. an IllegalArgumentException or a ClassNotFoundException). it must obey a set of constraints detailed in this specification. at the time a method is invoked or a request is about to be dispatched to an endpoint. or more aggressively. either on the client or on the server. the annotation in question must also obey the constraints in the relevant specification (see [14]). it MUST generate a fault appropriate to the binding in use. ♦ Conformance (Correctness of annotations): An implementation MUST check at runtime that the annotations pertaining to a method being invoked. an implementation MUST NOT dispatch to an endpoint implementation object. • In a server setting.Chapter 7 Annotations This chapter describes the annotations used by JAX-WS. Rather. Rather. cannot be captured using the annotation element default facility built into the language. For annotations defined by JSR-181. it MUST throw a WebServiceException. the text describes what the logical default is and how it is computed. as well as any containing program elements (i. May 7. JAX-WS 2. it MUST throw a WebServiceException. In this case. An implementation may check for correctness in a lazy way.e. • In a server setting.0 uses annotations extensively. besides being syntactically correct. Often properties have logical defaults which are computed based on contextual information and. if any. classes. annotation. For simplicity. ♦ Conformance (Unsupported WebServiceFeatureAnnotation): If an unrecongnized or unsupported annotation annotated with the WebServiceFeatureAnnotation meta-annotation: • In a client setting. e. packages) is in conformance with the specification for that annotation ♦ Conformance (Handling incorrect annotations): If an incorrect or inconsistent annotation is detected: • In a client setting. Also. an implementation MUST NOT invoke the remote operation being invoked. when describing an annotation we use the term “property” in lieu of the more correct “annotation elements”. 2007 JAX-WS 2. Instead. setting its cause to an exception approximating the cause of the error (e. which is the default as it appears in the declaration of the annotation type. setting its cause to an exception approximating the cause of the error (e. In a container environment.g. an IllegalArgumentException or a ClassNotFoundException). annotation. an implementation MUST NOT dispatch to an endpoint implementation object. if any. For an annotation to be correct.g. it MUST generate a fault appropriate to the binding in use. Instead. when creating a proxy.

Mode. Table 7. a SOAP body) or the entire protocol messages (e. Only the className element is required in this case.xml. The default value of localName element is the operationName as defined in WebMethod annotation and the default value for the targetNamespace element is the target namespace of the SEI.1: ServiceMode properties. Table 7.PAYLOAD The ServiceMode annotation type is marked @Inherited.1 javax.RequestWrapper The RequestWrapper annotation is applied to the methods of an SEI.g.ws.xml.ServiceMode The ServiceMode annotation is used to specify the mode for a provider class. It is used to capture the JAXB generated request wrapper bean and the element name and namespace for marshalling / unmarshalling the bean.xml. MESSAGE or javax. see section 2. When starting from Java. this annotation is used to resolve overloading conflicts in document literal mode. Default javax.xml.2 javax.e. MESSAGE means that the whole protocol message will be handed to the provider instance.WebFault The WebFault annotation is used when mapping WSDL faults to Java exceptions.xml.5.Service.ws. Annotations 7. It can also be used to customize the mapping of service specific exceptions to WSDL faults.Mode.Service.3 javax.Chapter 7.1 May 7.ws. a SOAP envelope). so the annotation will be inherited from the superclass. It is used to capture the name of the fault element used when marshalling the JAXB type generated from the global element referenced by the WSDL fault message. whether a provider wants to have access to protocol message payloads (e. 88 JAX-WS 2.g. PAYLOAD that only the payload of the protocol message will be handed to the provider instance.ws.Service.Mode. one of javax. Property value Description The service mode. 7. Property name targetNamespace faultBean Description The local name of the element The namespace name of the element The fully qualified name of the fault bean class Default ”” ”” ”” 7.ws. 2007 . i.2: WebFault properties.PAYLOAD.ws.xml.

When starting from Java.WebEndpoint Table 7.5 javax.ws. 2007 JAX-WS 2.xml. this annotation is used to resolve overloading conflicts in document literal mode.4 javax. identified by its local name (a NCName).ws.ws. It is used to capture the JAXB generated response wrapper bean and the element name and namespace for marshalling / unmarshalling the bean.3: RequestWrapper properties.WebEndpoint The WebEndpoint annotation is specified on the getPortName() methods of a generated service class (see 2.4: ResponseWrapper properties.xml.ws.4.7. javax.WebServiceClient The WebServiceClient annotation is specified on a generated service class (see 2. identify by a URL to a WSDL document and the qualified name of a wsdl:service element. Property localName targetNamespace className Description The local name of the element The namespace name of the element The name of the wrapper class Default ”” ”” ”” 7. a JAX-WS implementation MUST use the catalog facility defined in section 4.6.ResponseWrapper The ResponseWrapper annotation is applied to the methods of an SEI.6 javax.7). Table 7. May 7. Table 7.7). The default value of the localName element is the operationName as defined in the WebMethod appended with ”Response” and the default value of the targetNamespace element is the target namespace of the SEI. Property localName targetNamespace className Description The local name of the element The namespace name of the element The name of the wrapper class Default ”” ”” ”” 7. It is used to associate a class with a specific Web service. It is used to associate a get method with a specific wsdl:port. 7.5: WebServiceClient properties.xml.xml. Property name targetNamespace wsdlLocation Description The local name of the service The namespace name of the service The URL for the WSDL description of the service Default ”” ”” ”” When resolving the URI specified as the wsdlLocation element or any document it may transitively reference.1 89 . Only the className element is required in this case.

getPort(portName. QName serviceName) { } @WebEndpoint(name="StockQuoteHTTPPort") public StockQuoteProvider getStockQuoteHTTPPort() { return (StockQuoteProvider)super.1 Example The following shows a WSDL extract and the resulting generated service class.6: WebEndpoint properties.class).xml.ws. } public StockQuoteService(String wsdlLocation. 2007 . } @WebEndpoint(name="StockQuoteSMTPPort") public StockQuoteProvider getStockQuoteSMTPPort() { return (StockQuoteProvider)super.1 May 7. StockQuoteProvider. ♦ Conformance (WebServiceProvider and WebService): A class annotated with the WebServiceProvider annotation MUST NOT carry a WebService annotation.WSDL extract --> <wsdl:service name="StockQuoteService"> <wsdl:port name="StockQuoteHTTPPort" binding="StockQuoteHTTPBinding"/> <wsdl:port name="StockQuoteSMTPPort" binding="StockQuoteSMTPBinding"/> </wsdl:service> // Generated Service Interface @WebServiceClient(name="StockQuoteService".Service { public StockQuoteService() { super(wsdlLocation_fromAnnotation.gePort(portName. serviceName_fromAnnotation). Annotations Table 7.. Property name Description The local name of the port Default ”” 7.ws.xml.Chapter 7.6.1) does indeed define a Web service endpoint.7 javax. wsdlLocation=".ws..". much like the WebService annotation does for SEI-based endpoints.WebServiceProvider The WebServiceProvider annotation is specified on classes that implement a strongly typed javax. 1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 <!-.xml.class). It is used to declare that a class that satisfies the requirements for a provider (see 5. The WebServiceProvider and WebService annotations are mutually exclusive. 90 JAX-WS 2.Provider. } } 7.. targetNamespace=".. StockQuoteProvider.") public class StockQuoteService extends javax.

annotation. It follows the resource pattern exemplified by the javax.8 javax.9 javax. The resource type as a Java class object The service type as a Java class object A product specific name that this resource should be mapped to.Resource annotation in JSR-250 [31].1/HTTP one (see chapter 10).BindingType The BindingType annotation is applied to an endpoint implementation class. Table 7. Default ”” ”” Object.ws.8: BindingType properties.class Object.class ”” The name of the resource.xml. as defined by the name element (or defaulted) is a name that is local to the application component using the resource. Property value Description The binding ID (a URI) Default ”” The default binding for an endpoint is the SOAP 1.ws. a JAX-WS implementation MUST use the catalog facility defined in section 4.9: WebServiceRef properties.1 91 .9. where it is subject to the common resource injection rules described by the platform specification [32].xml. A URL pointing to the location of the WSDL document for the service being referred to. (It’s a name in the JNDI java:comp/env namespace.7: WebServiceProvider properties. 7. The WebServiceRef annotation is required to be honored when running on the Java EE 5 platform. Property wsdlLocation serviceName portName targetNamespace Description The URL for the WSDL description The name of the service The name of the port The target namespace for the service Default ”” ”” ”” ”” When resolving the URL specified as the wsdlLocation element or any document it may transitively reference. 7. Table 7. It specifies the binding to use when publishing an endpoint of this type.7.WebServiceRef The WebServiceRef annotation is used to declare a reference to a Web service.WebServiceRef Table 7.xml. Property name wsdlLocation type value mappedName Description The name identifying the Web service reference.) Many May 7.4. javax. 2007 JAX-WS 2.ws.

@WebEndpoint(name="StockQuoteSMTPPort") StockQuoteProvider getStockQuoteSMTPPort(). In this case. 2.") public interface StockQuoteService extends javax.. If the type cannot be inferred. 1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 // Generated Service Interface @WebServiceClient(name="StockQuoteService". if the reference type can be inferred by the field/method declaration the annotation is applied to.xml.1 Example The following shows both uses of the WebServiceRef annotation. targetNamespace=". the type and value element will both refer to the generated service class type.ws. Application servers are not required to support any particular form or type of mapped name. targetNamespace=".1 May 7. 2007 . Moreover. if present. that is)..class. } // Sample client code 92 JAX-WS 2. then at least the type element MUST be present with a non-default value.ws.Service). In this case. To define a reference whose type is a generated service class. a JAX-WS implementation MUST use the catalog facility defined in section 4. To define a reference whose type is a SEI.Chapter 7. There are two uses to the WebServiceRef annotation: 1. } // Generated SEI @WebService(name="StockQuoteProvider". 7. No use of a mapped name is portable. overrides the WSDL location information specified in the WebService annotation of the referenced generated service class. wsdlLocation=". but the value element MUST always be present and refer to a generated service class type (a subtype of javax. but may be a name of any form.. When resolving the URI specified as the wsdlLocation element or any document it may transitively reference.9. A mapped name is product-dependent and often installation-dependent.".4. This mappedName is often a global JNDI name.. Annotations application servers provide a way to map these local names to names of resources known to the application server.Service { @WebEndpoint(name="StockQuoteHTTPPort") StockQuoteProvider getStockQuoteHTTPPort(). The wsdlLocation element. the type and value elements MAY have the default value (Object. nor the ability to use mapped names.") public interface StockQuoteProvider { Double getStockQuote(String ticker). the type element MAY be present with its default value if the type of the reference can be inferred from the annotated field/method declaration..xml..

class) private StockQuoteProvider stockQuoteProvider. The first one uses the SEI type. // WebServiceRef using the SEI type @WebServiceRef(StockQuoteService. type=PayrollService.. Property value Description An array of WebServiceRef annotations.. Since no name and type can be inferred in this case.1 93 .WebServiceRefs The WebServiceRefs annotation is used to declare multiple references to Web services on a single class.ws.WebServiceRefs 25 26 27 28 29 30 31 32 33 34 35 36 37 @Stateless public ClientComponent { // WebServiceRef using the generated service interface type @WebServiceRef public StockQuoteService stockQuoteService. This annotation follows the resource pattern exemplified by the javax.annotation.ws.. 1 2 3 4 5 6 7 8 9 10 11 @WebServiceRefs({@WebServiceRef(name="accounting" type=AccountingPortType.Resources annotation in JSR-250 [31].class). Table 7. value=AccountingService.class)}) @Stateless public MyComponent { // methods using the declared resources go here. 2007 JAX-WS 2. The WebServiceRef annotation is required to be honored when running on the Java EE 5 platform.10: WebServiceRefs properties.10.7. each WebServiceRef annotation inside a WebServiceRefs MUST contain name and type elements with non-default values. @WebServiceRef(name="payroll".xml. which prevents listing multiple javax.1 Example The following shows how to use the WebServiceRefs annotation to declare at the class level two web service references.10. javax. where it is subject to the common resource injection rules described by the platform specification [32]. It is necessary to work around the limition against specifying repeated annotations of the same type on any given class.10 javax.ws.class.. } 7. } May 7.WebServiceRef annotations one after the other. // other methods go here. while the second one uses a generated service class type. Default {} 7. each defining a web service reference.xml.

when resolving the URI specified as the wsdlLocation element or any document it may transitively reference.jws. 7. OUT. Consistently with the URI resolution process in JAX-WS. String wsdlLocation() default "". boolean exclude() default false.4 1 2 3 4 5 javax. 7.jws. JAX-WS 2. String endpointInterface() default "". a JAX-WS implementation MUST use the catalog facility defined in section 4.1 [14]. String name() default "".jws.WebParam @Target({PARAMETER}) public @interface WebParam { public enum Mode { IN.0 implementation MUST be conformant to the JAXWS profile of JSR-181 1.Chapter 7.11 Annotations Defined by JSR-181 In addition to the annotations defined in the preceding sections.11. String targetNamespace() default "".3 1 2 3 javax.WebMethod @Target({METHOD}) public @interface WebMethod { String operationName() default "".WebService @Target({TYPE}) public @interface WebService { String name() default "". Annotations 7. 7. String action() default "" . String portName() default "".4. 7.11. String serviceName() default "". ♦ Conformance (JSR-181 conformance): A JAX-WS 2. 94 JAX-WS 2.OneWay @Target({METHOD}) public @interface Oneway { }.11.11.jws. }.2 1 2 3 4 5 6 javax.0 uses several annotations defined by JSR-181. INOUT }. 2007 . As a convenience to the reader. }. the following sections reproduce the definition of the JSR-181 annotations applicable to JAX-WS.1 1 2 3 4 5 6 7 8 9 javax.1 May 7.

5 1 2 3 4 5 6 7 javax. WRAPPED } Style style() default Style.7 1 2 3 4 5 javax. May 7. 2007 JAX-WS 2. In this version of JAX-WS there is no standard way to specify Action values in a WSDL and there is no standard default value. 7.7.11.SOAPBinding @Target({TYPE.HandlerChain @Target({TYPE}) public @interface HandlerChain { String file(). String partName() default "".Action 6 7 8 9 10 String targetNamespace() default "". boolean header() default false. } 7. boolean header() default false. 7.1 95 .WRAPPED. after the W3C WG on WS-Addressing has defined these items in a recommendation.jws. String targetNamespace() default "". It used to specify the input. Use use() default Use.LITERAL.xml.DOCUMENT. } 7.12.WebResult @Target({METHOD}) public @interface WebResult { String name() default "return".12 javax. It is intended that.11. }. ParameterStyle parameterStyle() default ParameterStyle.IN. String name() default "". a future version of JAX-WS will require the new standards.Action The Action annotation is applied to the methods of a SEI.xml. javax.ws. output WSAddressing Action values associated with the annotated method. }.ws. String partName() default "".6 1 2 3 4 5 6 7 8 9 10 11 12 javax.jws. Mode mode() default Mode.11. RPC } public enum Use { LITERAL.jws. ENCODED } public enum ParameterStyle { BARE. METHOD}) public @interface SOAPBinding { public enum Style { DOCUMENT.

ws. Table 7.xml. and javax.ws.ws.xml. Property fault input output Description Array of FaultAction for the wsdl:faults of the operation Action for the wsdl:input of the operation Action for the wsdl:output of the operation Default ”” ”” ”” 7. javax. after the W3C WG on WS-Addressing has defined these items in a recommendation. It is intended that. If a JAX-WS implementation encounters an annotation annotated with the WebServiceFeatureAnnotation that it does not support or recognize an ERROR MUST be given.Chapter 7.xml. Annotations Table 7.14 javax.12: FaultAction properties.xml.WebServiceFeatureAnnotation The WebServiceFeatureAnnotation is a meta-annotation used by a JAX-WS implementation to identify other annotations as WebServiceFeatures.FaultAction The FaultAction annotation is used within the Action annotation to specify the WS-Addressing Action of a service specific exception as defined by section 3.7. Property id bean Description Unique identifier for the WebServiceFeature represented by the annotated annotation.1 May 7.MTOM. In this version of JAX-WS there is no standard way to specify Action values in a WSDL and there is no standard default value. 2007 .13: WebServiceFeatureAnnotation properties. Property value output Description Action for the wsdl:fault of the operation Name of the exception class Default ”” no defaults quired propert re- 7.soap.11: Action properties.spi. 96 JAX-WS 2. The class name of a derived WebServiceFeature class associated with the annotated annotation. Table 7.xml. a future version of JAX-WS will require the new standards.RespectBinding.ws.ws.soap. JAX-WS provides the following annotations as WebServiceFeatures: javax.Addressing.13 javax. Default No defaults required property No defaults required property The following shows how the Addressing annotation uses the WebServiceFeatureAnnotation metaannotation.

ws.MTOM The MTOM annotation is applied to an endpoint implementation class. the runtime behavior of this annotation is well-defined. Table 7. It is used to control the use of WS-Addressing[24][33].2.class) public @interface Addressing { /** * Specifies if this feature is enabled or disabled.1. a future version of JAX-WS will remove these requirements.ID. } 7. and what the default value must be for Action headers. It is used to control the use of MTOM. After the W3C WG on WS-Addressing has specified how the use of WS-Addressing is specified in the WSDL. It corresponds to the MTOMFeature described in section 6. and for each invocation. Specifies Adddressing headers MUST be present on incoming messages.soap.spi. Table 7. however.1 javax. an endpoint MUST explicitly specify what WS-Addressing Actions are to be used via the Action and FaultAction annotations.14: Addressing properties.15: MTOM properties.5.soap. To write a portable endpoint and its corresponding client with this version of JAX-WS. bean=AddressingFeature. It is intended that a future version of JAX-WS will require the use of the standard mechanism to convey the use of WS-Addressing via WSDL and default values for WS-Addressing Action headers as defined by the W3C WG on WS-Addressing.1 97 . Property enabled Description Specifies if MTOM is enabled or not.xml. the client MUST explicitly set the BindingProvider.SOAPACTION URI PROPERTY. /** * Property to determine whether WS-Addressing * headers MUST be present on incoming messages. javax.14.14. 2007 JAX-WS 2.xml. Default true May 7.ws. */ boolean enabled() default true. 7.14.Addressing The Addressing annotation is applied to an endpoint implementation class. Default true false The definition of this annotation is incomplete in this release of JAX-WS as there is no standard way to convey the use of WS-Addressing via a WSDL and there is no standard definition for the default value of WS-Addressing Action headers.xml.7. Property enabled required Description Specifies if WS-Addressing is enabled or not.2 javax. It corresponds with the AddressingFeature described in section 6.ws. The client MUST explicitly enable addresssing via the AddressingFeature. */ boolean required() default false.5.WebServiceFeatureAnnotation 1 2 3 4 5 6 7 8 9 10 11 12 13 14 @WebServiceFeatureAnnotation(id=AddressingFeature.

3 javax.1 May 7. Default true 98 JAX-WS 2. 0 7. Table 7.14. Annotations threshold Specifies the size in bytes that binary data SHOULD be before being sent as an attachment. It is used to control whether a JAX-WS implementation MUST respect/honor the contents of the wsdl:binding associated with an endpoint.RespectBinding The RespectBinding annotation is applied to an endpoint implementation class.16: RespectBinding properties.Chapter 7.ws.xml. 2007 . Property enabled Description Specifies whether the wsdl:binding must be respected or not. It has a corresponding RespectBindingFeature described in section 6.3.5.

com/xml/ns/jaxws namespace is reserved for standard JAX-WS binding declarations. Implementations MUST support all standard JAX-WS binding declarations.com/xml/ns/jaxws namespace name. Wherever it appears.sun. ♦ Conformance (Standard binding declarations): The http://java.4). customizations will hereafter be referred to as binding declarations. 8. The second approach consists in embeddeding binding declarations directly inside a WSDL document (see 8. called an external binding file (see 8. Extensions are expressed using elements and/or attributes whose namespace name is different from the one used by this specification.0 defines an XML-based language that can be used to specify customizations to the WSDL 1. the jaxws prefix is assumed to be bound to the http://java.1 to Java binding. In the first approach. ♦ Conformance (Binding language extensibility): Implementations MUST ignore unknown elements and attributes appearing inside a binding declaration whose namespace name is not the one specified in the standard.sun. In order to maintain consistency with JAXB. the rest of this section uses qualified element names exclusively. in any order. 2007 JAX-WS 2. In either case. the jaxws:bindings element is used as a container for JAX-WS binding declarations.1 Binding Language JAX-WS 2. http://java.com/xml/ns/jaxws.e. all binding declarations pertaining to a given WSDL document are grouped together in a standalone document. 8.sun. i. All XML elements defined in this section belong to the http://java.sun. For clarity. May 7.Chapter 8 Customizations This chapter describes a standard customization facility that can be used to customize the WSDL 1.com/xml/ns/jaxws namespace. It contains a (possibly empty) list of binding declarations.1 to Java binding defined in section 2.2 Binding Declaration Container There are two ways to specify binding declarations. The binding language is extensible. Implementation-specific binding declaration extensions MUST NOT use the http://java.com/xml/ns/jaxws namespace. Similarly. we call it a binding language.sun.3).1 99 .

2 shows a WSDL document containing binding declaration extensions. An external binding file specifies bindings for a given WSDL document.1 May 7.com/xml/ns/jaxb.0. When a jaxws:bindings element is used as a WSDL extension. 8. The WSDL document in question is identified via the mandatory wsdlLocation attribute on the root jaxws:bindings element in the document. it assumes that the prefix jaxb is bound to the namespace name http://java. @node An XPath expression pointing to the element in the WSDL file in scope that this binding declaration is attached to.3 Embedded Binding Declarations An embedded binding declaration is specified by using the jaxws:bindings element as a WSDL extension. It MUST NOT be present if the jaxws:bindings element is used as an extension inside a WSDL document or one of its ancestor jaxws:bindings elements already contains this attribute.. it will implicitly be assumed to be 2. 8.1: Syntax of the binding declaration container Semantics @wsdlLocation A URI pointing to a WSDL file establishing the scope of the contents of this binding declaration..1 Example Figure 8. For the JAX-WS 2. if present.1[18]. @version A version identifier. 8. Moreover. the version identifier. it MUST NOT have a node attribute.e. on non top-level binding declarations).0".binding declarations.3.1 namespace that accept extension elements.Chapter 8. It MUST NOT appear on jaxws:bindings elements which have any jaxws:bindings ancestors (i. For JAXB annotations. it MUST NOT have an element whose qualified name is jaxws:bindings amongs its children. It MUST NOT be present if the jaxws:bindings appears inside a WSDL document. 2007 .sun. A binding declaration embedded in a WSDL document can only affect the WSDL element it extends. Customizations 1 2 3 4 5 <jaxws:bindings wsdlLocation="xs:anyURI"? node="xs:string"? version="string"?> . Embedded binding declarations MAY appear on any of the elements in the WSDL 1. per the schema for the WSDL 1.. If the @version attribute is absent. Such a document is called an external binding file.1 namespace as amended by the WS-I Basic Profile 1. MUST be "2. </jaxws:bindings> Figure 8.4 External Binding File The jaxws:bindings element MAY appear as the root element of a XML document..0 specification. 100 JAX-WS 2.

8." xmlns:stns=". </jaxb:bindings> </xs:appinfo> </xs:annotation> <xs:element name="setLastTradePrice"> <xs:complexType> <xs:sequence> <xs:element name="tickerSymbol" type="xs:string"/> <xs:element name="lastTradePrice" type="xs:float"/> </xs:sequence> </xs:complexType> </xs:element> <xs:element name="setLastTradePriceResponse"> <xs:complexType> <xs:sequence/> </xs:complexType> </xs:element> </xs:schema> </wsdl:types> <wsdl:message name="setLastTradePrice"> <wsdl:part name="setPrice" element="stns:setLastTradePrice"/> </wsdl:message> <wsdl:message name="setLastTradePriceResponse"> <wsdl:part name="setPriceResponse" type="stns:setLastTradePriceResponse"/> </wsdl:message> <wsdl:portType name="StockQuoteUpdater"> <wsdl:operation name="setLastTradePrice"> <wsdl:input message="tns:setLastTradePrice"/> <wsdl:output message="tns:setLastTradePriceResponse"/> <jaxws:bindings> <jaxws:method name="updatePrice"/> </jaxws:bindings> </wsdl:operation> <jaxws:bindings> <jaxws:enableAsyncMapping>true</jaxws:enableAsyncMapping> </jaxws:bindings> </wsdl:portType> <jaxws:bindings> <jaxws:package name="com.. 2007 JAX-WS 2.1 101 ..acme....." xmlns:tns=. </jaxws:bindings> </wsdl:definitions> Figure 8..additional binding declarations...foo"/> ..2: Sample WSDL document with embedded binding declarations May 7."> <wsdl:types> <xs:schema targetNamespace="http://example.4....some JAXB binding declarations.. External Binding File 1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 <wsdl:definitions targetNamespace=".org/bar"> <xs:annotation> <xs:appinfo> <jaxb:bindings> .

additional binding declarations. </jaxb:bindings> </jaxws:bindings> <jaxws:bindings node="wsdl:portType[@name=’StockQuoteUpdater’]"> <jaxws:enableAsyncMapping>true</jaxws:enableAsyncMapping> <jaxws:bindings node="wsdl:operation[@name=’setLastTradePrice’]"> <jaxws:method name="updatePrice"/> </jaxws:bindings> </jaxws:bindings> .1. The root jaxws:bindings element implicitly contains a node attribute whose value is //. When a JAX-WS implementation processes a WSDL document for which there is an external binding file. Please refer to section 8. An XPath expression on a non-root jaxws:bindings element selects zero or more nodes from the set of nodes selected by its parent jaxws:bindings element. External binding files are semantically equivalent to embedded binding declarations (see 8.0 bindings element.5 Using JAXB Binding Declarations It is possible to use JAXB binding declarations in conjunction with JAX-WS. selecting the root element in the document. 8. as a child or descendant of the root jaxws:bindings element.e.org/foo.foo"/> <jaxws:bindings node="wsdl:types/xs:schema[targetNamespace=’http://example. It is an error if.3: Sample external binding file for WSDL in figure 8.4 8. It affects the data binding as specified by JAXB 2. i. MAY appear as an annotation inside a schema document embedded in a WSDL document. 2007 .. </jaxws:bindings> Figure 8.3). ♦ Conformance (Multiple binding files): Implementations MUST support specifying any number of external JAX-WS and JAXB binding files for processing in conjunction with at least one WSDL document... 1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 <jaxws:bindings wsdlLocation="http://example.. The JAXB 2. the resulting WSDL document contains conflicting binding declarations. henceforth referred to as jaxb:bindings..4.wsdl"> <jaxws:package name="com.. i.4 show an example external binding file and WSDL document respectively that express the same set of binding declarations as the WSDL document in 8. jaxws:bindings elements MAY appear as non-root elements.1 Example Figures 8.some JAXB binding declarations. it MUST operate as if all binding declarations specified in the external binding file were instead specified as embedded declarations on the nodes in the in the WSDL document they target.g.0..3.1 May 7..e.3 and 8. upon embedding the binding declarations defined in one or more external binding files. 102 JAX-WS 2.5 for more information on processing JAXB binding declarations.org/bar’]"> <jaxb:bindings> . as a descendant of a xs:schema element whose parent is the wsdl:types element.Chapter 8. e. they MUST carry a node attribute identifying the element in the WSDL document they annotate..acme. In this case. Customizations In an external binding file.

2007 JAX-WS 2." xmlns:tns=".org/bar"> <xs:element name="setLastTradePrice"> <xs:complexType> <xs:sequence> <xs:element name="tickerSymbol" type="xs:string"/> <xs:element name="lastTradePrice" type="xs:float"/> </xs:sequence> </xs:complexType> </xs:element> <xs:element name="setLastTradePriceResponse"> <xs:complexType> <xs:sequence/> </xs:complexType> </xs:element> </xs:schema> </wsdl:types> <wsdl:message name="setLastTradePrice"> <wsdl:part name="setPrice" element="stns:setLastTradePrice"/> </wsdl:message> <wsdl:message name="setLastTradePriceResponse"> <wsdl:part name="setPriceResponse" type="stns:setLastTradePriceResponse"/> </wsdl:message> <wsdl:portType name="StockQuoteUpdater"> <wsdl:operation name="setLastTradePrice"> <wsdl:input message="tns:setLastTradePrice"/> <wsdl:output message="tns:setLastTradePriceResponse"/> </wsdl:operation> </wsdl:portType> </wsdl:definitions> Figure 8.3 May 7."> <wsdl:types> <xs:schema targetNamespace="http://example. Using JAXB Binding Declarations 1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 <wsdl:definitions targetNamespace="...." xmlns:stns="...4: WSDL document referred to by external binding file in figure 8.5.1 103 ..8.

jaxb:bindings MAY appear inside a JAX-WS external binding file as a child of a jaxws:bindings element whose node attribute points to a xs:schema element inside a WSDL document. 8. method.7 Standard Binding Declarations The following sections detail the predefined binding declarations. (3) the definitions element. Editors Note 8.e. 2007 . 8. All these declarations reside in the http://java. when determining the value of the jaxws:enableWrapperStyle customization parameter for a portType operation. according to the element they pertain to: (1) the portType operation in question. without fixing up all its XPath expressions. In particular. classified according to the WSDL element they’re allowed on. It is an error if upon applying all the customizations in effect for a given WSDL document. 1 2 3 4 5 6 7 8 9 10 <jaxws:package name="xs:string">? <jaxws:javadoc>xs:string</jaxws:javadoc>? </jaxws:package> <jaxws:enableWrapperStyle>? xs:boolean </jaxws:enableWrapperStyle> <jaxws:enableAsyncMapping>? xs:boolean 104 JAX-WS 2. any of the generated Java source code artifacts does not contain legal Java syntax. either as an extension to the wsdl:definitions element or in an external binding file at a place where there is a WSDL document in scope. binding declarations MUST be processed in the following order. Customizations Additionally. even in the case that the XML Schema the JAXB binding file refers to was embedded in a WSDL.6 Scoping of Bindings Binding declarations are scoped according to the parent-child hierarchy in the WSDL document. While processing a JAXB binding declaration (i. a jaxb:bindings element) for a schema document embedded inside a WSDL document.1 Definitions The following binding declarations MAY appear in the context of a WSDL document. 8.1 May 7. For instance.com/xml/ns/jaxws namespace. Tools MUST NOT ignore binding declarations.7. it is an error to use any reserved keywords as the name of a Java field.1 This last requirement ensures that JAXB processors don’t have to be extended to incorporate knowledge of WSDL. When the schema is processed. (2) its parent portType. all XPath expressions that appear inside it MUST be interpreted as if the containing xs:schema element was the root of a standalone schema document.Chapter 8. it becomes possible to take a JAXB binding file and embed it in a JAX-WS binding file as-is. type or package.sun. the outcome MUST be as if the jaxb:bindings element was inlined inside the schema document as an annotation on the schema component. In particular.

8.7. 1 2 3 4 5 6 7 8 9 <jaxws:class name="xs:string">? <jaxws:javadoc>xs:string</jaxws:javadoc>? </jaxws:class> <jaxws:enableWrapperStyle>? xs:boolean </jaxws:enableWrapperStyle> <jaxws:enableAsyncMapping>xs:boolean</jaxws:enableAsyncMapping>? Semantics class/@name Fully qualified name of the generated service endpoint interface corresponding to the parent wsdl:portType. package/javadoc/text() Package-level javadoc string. disabled) by default for all operations in this wsdl:portType. disbled) by default for all operations.e. asynchronous mappings are enabled (resp. this declaration is true. false). use of the mime:content information is enabled (resp. either as an extension to the wsdl:portType element or with a node attribute pointing at one. enableWrapperStyle If present with a boolean value of true (resp. wrapper style processing is turned on by default for all qualified operations. By default.1 105 .2 PortType The following binding declarations MAY appear in the context of a WSDL portType. enableAsyncMapping If present with a boolean value of true (resp. false).7. false). wrapper style is enabled (resp. disabled) by default for all operations. wrapper style is enabled (resp. disabled) by default for all operations. May 7. i. class/javadoc/text() Class-level javadoc string. 2007 JAX-WS 2. false). enableMIMEContent If present with a boolean value of true (resp. and must be disabled by using a jaxws:enableWrapperStyle declaration with a value of false in the appropriate scope. enableWrapperStyle If present with a boolean value of true (resp. The enableWrapperStyle declaration only affects operations that qualify for the wrapper style per the JAX-WS specification. Standard Binding Declarations 11 12 13 14 15 </jaxws:enableAsyncMapping> <jaxws:enableMIMEContent>? xs:boolean </jaxws:enableMIMEContent> Semantics package/@name Name of the Java package for the targetNamespace of the parent wsdl:definitions element. 8.

either as an extension to the wsdl:portType/wsdl:operation element or with a node attribute pointing at one. method/javadoc/text() Method-level javadoc string. 8.3 PortType Operation The following binding declarations MAY appear in the context of a WSDL portType operation. false). disabled) by default for all operations in this wsdl:portType. or if a part/element that corresponds to the Java method return value is assigned a name. parameter/@childElementName The qualified name of a child element information item of the global type definition or global element declaration referred to by the wsdl:part identified by the previous attribute. parameter/@part A XPath expression identifying a wsdl:part child of a wsdl:message. 2007 . 106 JAX-WS 2. Customizations enableAsyncMapping If present with a boolean value of true (resp. It is an error if two parameters that do not correspond to the same Java formal parameter are assigned the same name. 1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 <jaxws:method name="xs:string">? <jaxws:javadoc>xs:string</jaxws:javadoc>? </jaxws:method> <jaxws:enableWrapperStyle>? xs:boolean </jaxws:enableWrapperStyle> <jaxws:enableAsyncMapping>? xs:boolean </jaxws:enableAsyncMapping> <jaxws:parameter part="xs:string" childElementName="xs:QName"? name="xs:string"/>* Semantics method/@name Name of the Java method corresponding to this wsdl:operation. enableAsyncMapping If present with a boolean value of true.7. parameter/@name The name of the Java formal parameter corresponding to the parameter identified by the previous two attributes. enableWrapperStyle If present with a boolean value of true (resp.1 May 7.Chapter 8. disabled) by default for this wsdl:operation. false). asynchronous mappings are enabled by default for this wsdl:operation. wrapper style is enabled (resp. asynchronous mappings are enabled (resp.

8.7. Standard Binding Declarations

8.7.4 PortType Fault Message
The following binding declarations MAY appear in the context of a WSDL portType operation’s fault message, either as an extension to the wsdl:portType/wsdl:operation/wsdl:fault element or with a node attribute pointing at one.
1 2 3 <jaxws:class name="xs:string">? <jaxws:javadoc>xs:string</jaxws:javadoc>? </jaxws:class>

Semantics
class/@name The name of the generated exception class for this fault. class/javadoc/text() Class-level javadoc string. It is an error if faults that refer to the same wsdl:message element are mapped to exception classes with different names.

8.7.5 Binding
The following binding declarations MAY appear in the context of a WSDL binding, either as an extension to the wsdl:binding element or with a node attribute pointing at one.
1 2 3 <jaxws:enableMIMEContent>? xs:boolean </jaxws:enableMIMEContent>

Semantics
enableMIMEContent If present with a boolean value of true (resp. false), use of the mime:content information is enabled (resp. disabled) for all operations in this binding.

8.7.6 Binding Operation
The following binding declarations MAY appear in the context of a WSDL binding operation, either as an extension to the wsdl:binding/wsdl:operation element or with a node attribute pointing at one.
1 2 3 4 5 6 7 8 9 10 <jaxws:enableMIMEContent>? xs:boolean </jaxws:enableMIMEContent> <jaxws:parameter part="xs:string" childElementName="xs:QName"? name="xs:string"/>* <jaxws:exception part="xs:string">* <jaxws:class name="xs:string">?

May 7, 2007

JAX-WS 2.1

107

Chapter 8. Customizations

11 12 13

<jaxws:javadoc>xs:string</jaxws:javadoc>? </jaxws:class> </jaxws:exception>

Semantics
enableMIMEContent If present with a boolean value of true (resp. false), use of the mime:content information is enabled (resp. disabled) for this operation. parameter/@part A XPath expression identifying a wsdl:part child of a wsdl:message. parameter/@childElementName The qualified name of a child element information item of the global type definition or global element declaration referred to by the wsdl:part identified by the previous attribute. parameter/@name The name of the Java formal parameter corresponding to the parameter identified by the previous two attributes. The parameter in question MUST correspond to a soap:header extension.

8.7.7 Service
The following binding declarations MAY appear in the context of a WSDL service, either as an extension to the wsdl:service element or with a node attribute pointing at one.
1 2 3 <jaxws:class name="xs:string">? <jaxws:javadoc>xs:string</jaxws:javadoc>? </jaxws:class>

Semantics
class/@name The name of the generated service interface. class/javadoc/text() Class-level javadoc string.

8.7.8 Port
The following binding declarations MAY appear in the context of a WSDL service, either as an extension to the wsdl:port element or with a node attribute pointing at one.
1 2 3 4 5 <jaxws:method name="xs:string">? <jaxws:javadoc>xs:string</jaxws:javadoc>? </jaxws:method> <jaxws:provider/>?

Semantics
method/@name The name of the generated port getter method. 108 JAX-WS 2.1 May 7, 2007

8.7. Standard Binding Declarations

method/javadoc/text() Method-level javadoc string. provider This binding declaration specifies that the annotated port will be used with the javax.xml.ws.Provider interface. A port annotated with a jaxws:provider binding declaration is treated specially. No service endpoint interface will be generated for it, since the application code will use in its lieu the javax.xml.ws.Provider interface. Additionally, the port getter method on the generated service interface will be omitted. Editors Note 8.2 Omitting a getXYZPort() method is necessary for consistency, because if it existed it would specify the non-existing SEI type as its return type.

May 7, 2007

JAX-WS 2.1

109

1 May 7. 2007 . Customizations 110 JAX-WS 2.Chapter 8.

9. The handlers within a handler chain are invoked each time a message is sent or received.LogicalHandler.1 111 . Logical handlers are protocol agnostic and are unable to affect protocol specific parts of a message. Logical handlers are handlers that implement javax. Message context properties may be used to facilitate communication between individual handlers and between handlers and client and service implementations.handler.xml. that may be used to extend the capabilities of a JAX-WS runtime system. Client and server-side handlers are organized into an ordered list known as a handler chain. This chapter describes the handler framework in detail. known as handlers.1 Types of Handler JAX-WS 2. and Dispatch instances. known collectively as binding providers.Chapter 9 Handler Framework JAX-WS provides a flexible plug-in framework for message processing modules. Inbound messages are processed by handlers prior to binding provider processing. Protocol Handlers that operate on message context properties and protocol specific messages. Protocol handlers are specific to a particular protocol and may access and change protocol specific aspects of a May 7.1). Protocol bindings can extend the handler framework to provide protocol specific functionality. chapter 10 describes the JAX-WS SOAP binding that extends the handler framework with SOAP specific functionality. Different types of handlers are invoked with different types of message context. Proxies. Handlers are invoked with a message context that provides methods to access and modify inbound and outbound messages and to manage a set of properties. ♦ Conformance (Handler framework support): An implementation MUST support the handler framework. Outbound messages are processed by handlers after any binding provider processing. 2007 JAX-WS 2.0 defines two types of handler: Logical Handlers that only operate on message context properties and message payloads.1.1 Architecture The handler framework is implemented by a JAX-WS protocol binding in both client and server side runtimes.ws. each use protocol bindings to bind their abstract functionality to specific protocols (see figure 9. 9.

1 Handler and Message Context Management The binding is responsible for instantiation..1: Handler architecture message.1. .2 shows the class hierarchy for handlers.handler.xml. 112 JAX-WS 2.1) being deployed in their handler chains. Protocol handlers are handlers that implement any interface derived from javax. 9. Figure 9..Handler.1 May 7.ws.. invocation.Handler except javax. Handlers for protocols other than SOAP are expected to implement a protocol-specific interface that extends javax.1...2.ws. 2007 .1.4 ♦ Conformance (Logical handler support): All binding implementations MUST support logical handlers (see section 9.handler. Figure 9.Chapter 9.handler..1.ws. 9.3.1) being deployed in their handler chains. Handler Framework Endpoint getBinding():Binding has-a €€ €€ €€ €€ q € Binding BindingProvider getHandlerChain():List I     setHandlerChain(List):void   has-a getBinding():Binding          implements   Proxy s d d d dextends d Dispatch one-to-many c Handler . and destruction of handlers according to the rules specified in section 9. ♦ Conformance (Other handler support): Binding implementations MAY support other handler types (see section 9. . The binding is responsible for instantiation and management of message contexts according to the rules specified in section 9.LogicalHandler.xml.2 Binding Responsibilities The following subsections describe the responsibilities of the protocol binding when hosting a handler chain.xml.

Architecture Handler<T> T extends MessageContext init(Map<String.2: Handler class hierarchy ♦ Conformance (Incompatible handlers): An implementation MUST throw WebServiceException when.1 113 .3.1. Outbound exceptions1 are converted to protocol fault messages and dispatched using whatever means the protocol binding uses for communication.setHandlerChain method.Object>):void destroy():void handleMessage(T):boolean handleFault(T):boolean close(MessageContext):void    s d   d   d   d   extends dextends   d LogicalHandler<T> SOAPHandler<T> T extends LogicalMessageContext T extends SOAPMessageContext getHeaders():Set<QName> Figure 9.2.9.1. Inbound messages are dispatched to the binding provider.2. 2007 JAX-WS 2. Specific protocol bindings describe the mechanism for their Outbound exceptions are exceptions thrown by a handler that result in the message direction being set to outbound according to the rules in section 9.2 Message Dispatch The binding is responsible for dispatch of both outbound and inbound messages after handler processing. 9. 1 May 7. ♦ Conformance (Incompatible handlers): Implementations MUST throw a WebServiceException when attempting to configure an incompatible handler using the Binding. the handler chain returned by the configured HandlerResolver contains an incompatible handler.2.2. JAX-WS defines no standard interface between binding providers and their binding. 9.3.3 Exception Handling The binding is responsible for catching runtime exceptions thrown by handlers and respecting any resulting message direction and message type change as described in section 9.1. Outbound messages are dispatched using whatever means the protocol binding uses for communication. at the time a binding provider is created.

handler. port and binding in use.xml.2 describes how the handler order relates to the order of handler execution for inbound and outbound messages. Section 9. 2007 .jws. The JAX-WS runtime uses the PortInfo argument to pass the HandlerResolver of the service.jws. via the Service. ♦ Conformance (Handler chain snapshot): Changing the handler resolver configured for a Service instance MUST NOT affect the handlers on previously created proxies.1 May 7. getHandlerChain.2.2 Configuration Handler chains may be configured either programmatically or using deployment metadata. 9. Handler Framework particular protocol. The following subsections describe each form of configuration.1. A Service instance provides access to a handlerResolver property.setHandlerResolver methods.1.2 describes the mechanism for the SOAP 1.3 javax. When a Service instance is used to create an instance of a binding provider then the created instance is configured with the handler chain created by the HandlerResolver instance registered on the Service instance at that point in time. During the creation of a binding provider.1. In performing this operation. 9. Figure 9.2 Handler Ordering The handler chain for a binding is constructed by starting with the handler chain as returned by the HandlerResolver for the service in use and sorting its elements so that all logical handlers precede all protocol handlers.3. which in turn is then used to configure the binding provider. known collectively as binding providers. 9.1 Programmatic Configuration JAX-WS only defines APIs for programmatic configuration of client side handler chains – server side handler chains are expected to be configured using deployment metadata. 9.ws. 9.1 binding.2.HandlerResolver A Service instance maintains a handler resolver that is used when creating proxies or Dispatch instances.1 javax.HandlerChain annotation The javax.2.HandlerChain annotation defined by JSR-181 [14] may be used to specify in a declarative way the handler chain to use for a service. section 10. A HandlerResolver implements a single method. which has one argument.2. or Dispatch instances. the order of handlers of any given type (logical or protocol) in the original chain is maintained. Inbound exceptions are passed to the binding provider.3 illustrates this. 114 JAX-WS 2. a PortInfo object.2. the handler resolver currently registered with a service is used to create a handler chain.Chapter 9. The HandlerResolver may use any of this information to decide which handlers to use in constructing the requested handler chain.getHandlerResolver and Service.

9.xml. 9. 2007 JAX-WS 2.3). including a provider.1.1. it affects all the proxies and Dispatch instances created using any of the ports on the service. ♦ Conformance (Handler resolver for a HandlerChain annotation): For a generated service class (see 2. the handler chain initially configured on an instance is a snapshot of the applicable handlers May 7.2. on an endpoint interface and on a generated service class. the name element of the HandlerChain annotation.4 javax. In addition to appearing on a endpoint implementation class or a SEI.3: Handler ordering. When used in conunction with JAX-WS. Configuration ' ' $ $ Service Handler Resolver L1 P1 P2 L2 P3 P4 P5 L3 P6 & ' & % % Proxy/Dispatch creation ' ? $ $ Binding Provider Binding L1 L2 L3 P1 P2 P3 P4 P5 P6 & & % % Figure 9.ws.7) which is annotated with a HandlerChain annotation.1 for more details). Ln and Pn represent logical and protocol handlers respectively.2.4 shows an endpoint implementation class annotated with a HandlerChain annotation. the handlerChain annotation MAY appear on a generated service class. ♦ Conformance (HandlerChain annotation): An implementation MUST support using the HandlerChain annotation on an endpoint implementation class. On the client. the HandlerChain annotation can be seen as a shorthand way of defining and installing a handler resolver (see 4. Figure 9.1 115 . the default handler resolver MUST return handler chains consistent with the contents of the handler chain descriptor referenced by the HandlerChain annotation. if present. As described above. In this case.Binding The Binding interface is an abstraction of a JAX-WS protocol binding (see section 6. as specified by JSR-181. MUST have the default value (the empty string).

Such a method MUST satisfy the requirements in JSR-250 [31] 116 JAX-WS 2. then the burden of calling any handler lifecycle methods falls on the application itself. ♦ Conformance (Binding handler manipulation): Changing the handler chain on a Binding instance MUST NOT cause any change to the handler chains configured on the Service instance used to create the Binding instance. e. This should not be seen as inconsistent. typically via the javax.3.annotation.1 May 7. so their contract will be known to the application developer.Resource annotation. 9.g.Chapter 9.2. Binding provides methods to manipulate the initially configured handler chain for a specific instance. 2007 . if present. an implementation must invoke the handler lifecycle methods as prescribed in this section.1 Handler Lifecycle In some cases.. using a handler resolver. because handlers are logically part of the application. a JAX-WS implementation must instantiate handler classes directly. 9. When doing so.. Such a model is provided by JSR 109[15] “Implementing Enterprise Web Services”.annotation.4: Use of the HandlerChain annotation configured on the Service instance at the time of creation. the runtime MUST invoke the method carrying a javax. The JAX-WS runtime system is responsible for loading the handler class and instantiating the corresponding handler object according to the instruction contained in the applicable handler configuration file or deployment descriptor.g. in a container environment or when using the HandlerChain annotation. The lifecycle of a handler instance begins when the JAX-WS runtime system creates a new instance of the handler class. If an application does its own instantiation of handlers. Handler Framework 1 2 3 4 5 @WebService @HandlerChain(file="sample_chain. After all the injections have been carried out. The runtime MUST then carry out any injections requested by the handler. including in the case where no injections were requested.xml") public class MyService { . e.3 Processing Model This section describes the processing model for handlers within the handler framework.2 Deployment Model JAX-WS defines no standard deployment model for handlers. The JAX-WS runtime system manages the lifecycle of handlers by invoking any methods of the handler class annotated as lifecycle methods before and after dispatching requests to the handler itself. 9. } Figure 9.PostConstruct annotation.

9. May 7. and handler instance cleanup must be left to finalizer methods and regular garbage collection. Once the handler instance is created and initialized it is placed into the Ready state.1 117 .g. . . .annotation. .4) whose contents may be manipulated by the handler. a Dispatch object. if present.2.2 Handler Execution As described in section 9.3. . 9.e. .g. H6 in that order: for outbound messages handler H1 would be invoked first followed by H2 . These terms are relative to the direction of the message.1 summarizes their meaning. H3 . e. The following subsections describe each handler method and the changes to handler chain processing they may cause. an endpoint or some other component. a EJB object. prior to releasing a handler instance.PreDestroy annotation. . in non-container environments. The handler instance is then ready for use. prior to invoking any other method on a handler instance. if present. an implementation MUST call the lifecycle method annotated with PostConstruct.1. consider a handler chain that consists of six handlers H1 . on any Handler instances which it instantiated. it has a void return type and takes zero arguments). and finally H1 . E. be it a proxy. 2007 JAX-WS 2. Consequently. . H4 . and finally handler H6 . ♦ Conformance (Handler initialization): After injection has been completed. Each handler is passed a message context (see section 9. Processing Model for lifecycle methods (i. an implementation MUST call the lifecycle method annotated with PreDestroy method. is released. ♦ Conformance (Handler destruction): In a managed environment.. for inbound messages H6 would be invoked first followed by H5 . Unless modified by the actions of a handler (see below) normal processing involves each handler in the chain being invoked in turn. The lifecycle of a handler instance ends when the JAX-WS runtime system stops using the handler for processing inbound or outbound messages. For outbound messages handler processing starts with the first handler in the chain and proceeds in the same order as the handler chain. Such a method MUST satisfy the requirements in JSR-250 [31] for lifecycle methods An implementation can only release handlers after the instance they are attached to. so as to permit the handler to clean up its resources. After taking the handler offline. it is impossible to call the PreDestroy method in a reliable way. In the following discussion the terms next handler and previous handler are used. While in the Ready state the JAX-WS runtime system may invoke other handler methods as required.3. . if present. a set of handlers is managed by a binding as an ordered list called a handler chain. a JAX-WS implementation SHOULD invoke the lifecycle method which carries a javax. After invocation of the PreDestroy method(s). For inbound messages the order of processing is reversed: processing starts with the last handler in the chain and proceeds in the reverse order of the handler chain. the handler instance will be made available for garbage collection. Handlers may change the direction of messages and the order of handler processing by throwing an exception or by returning false from handleMessage or handleFault. The handler instance must release its resources and perform cleanup in the implementation of the PreDestroy lifecycle method. . table 9.2.

Subsequent actions depend on whether the MEP in use requires a response to the message currently being processed or not: Response Normal message processing stops. Throw ProtocolException or a subclass This indicates that normal message processing should cease. the exception is dispatched (see section 9. and the exception is dispatched (see section 9. 2007 .2) if there are no further handlers. Subsequent handler processing takes this change into account.2.2).2. No response Normal message processing stops.1 handleMessage This method is called for normal message processing.1. Subsequent actions depend on whether the MEP in use includes a response to the message currently being processed or not: Response Normal message processing stops.1. 3 Next in this context means the next handler taking into account the message direction reversal 4 The handler may have already converted the message to a fault message. close is called on each previously invoked handler in the chain. For a request-response MEP.1.2) if there are no further handlers.3). fault message processing starts. Return false This indicates that normal message processing should cease.2.1 May 7. Following completion of its work the handleMessage implementation can do one of the following: Return true This indicates that normal message processing should continue. if the message direction is reversed during processing of a request message then the message becomes a response message. Handler Framework Message Direction Inbound Outbound Term Next Previous Next Previous Handler Hi−1 Hi+1 Hi+1 Hi−1 Table 9. close is called on each previously invoked handler in the chain. the exception is dispatched (see section 9. if the message is not already a fault message then it is replaced with a fault message4 . the runtime invokes handleMessage on the next3 handler or dispatches the message (see section 9.2.1. Subsequent actions depend on whether the message exchange pattern (MEP) in use requires a response to the message currently being processed2 or not: Response The message direction is reversed. The message direction is reversed.2. Throw any other runtime exception This indicates that normal message processing should cease.2.3). and the runtime invokes handleFault on the next4 handler or dispatches the message (see section 9. No response Normal message processing stops.1. 9.1. in which case no change is made. 2 118 JAX-WS 2. No response Normal message processing stops.Chapter 9. the message direction is reversed. the message is dispatched (see section 9.2.3.2) if there are no further handlers.1: Next and previous handlers for handler Hi . close is called on each previously invoked handler in the chain.1.2. The runtime invokes handleMessage on the next handler or dispatches the message (see section 9. close is called on each previously invoked handler in the chain.3).

1 119 . Fault message processing stops.3 close A handler’s close method is called at the conclusion of a message exchange pattern (MEP). Fault message processing stops.1.2). see section 9. May 7.2. for each message in an MEP or any combination of the two.9. an implementation MUST call the close method of each handler that was previously invoked during that MEP via either handleMessage or handleFault.2.3 Handler Implementation Considerations Handler instances may be pooled by a JAX-WS runtime system. Message Context 9. close is called on each previously invoked handler in the chain. Handlers should not rely on thread local state to share information.4. Return false This indicates that fault message processing should cease. following completion of its work the handleFault implementation can do one of the following: Return true This indicates that fault message processing should continue.2. ♦ Conformance (Order of close invocations): Handlers are invoked in the reverse order in which they were first invoked to handle a message according to the rules for normal message processing (see 9. Throw any other runtime exception This indicates that fault message processing should cease.3).3. close is called on each previously invoked handler in the chain. close is called on each previously invoked handler in the chain. Handlers should instead use the message context. 9. Throw ProtocolException or a subclass This indicates that fault message processing should cease. Fault message processing stops.3. the exception is dispatched (see section 9. the exception is dispatched (see section 9.1. The close method is only called on handlers that were previously invoked via either handleMessage or handleFault ♦ Conformance (Invoking close): At the conclusion of an MEP.1. 2007 JAX-WS 2.4 Message Context Handlers are invoked with a message context that provides methods to access and modify inbound and outbound messages and to manage a set of properties.3).2. All instances of a specific handler are considered equivalent by a JAX-WS runtime system and any instance may be chosen to handle a particular message. It is called just prior to the binding dispatching the final message.4. 9. fault or exception of the MEP and may be used to clean up per-MEP resources allocated by a handler.3.2) if there are no further handlers.1. The runtime invokes handleFault on the next handler or dispatches the fault message (see section 9. Different handler instances may be used to handle each message of an MEP.2 handleFault Called for fault message processing.3. Different threads may be used for each handler in a handler chain.2. the fault message is dispatched (see section 9.2.2). 9.

1.4. The property values may be manipulated by client applications.4. A case in which this might happen is when. These properties are only required to be present in the message context of an endpoint that is deployed inside a servlet container and uses an HTTP-based binding.2. All properties are available to all handlers for an instance of an MEP on a particular endpoint. E. Section 10. E.4. a handler may use the put method to insert a property in the message context that one or more other handlers in the handler chain may subsequently obtain via the get method.xml.ws. A JAX-WS runtime is expected to implement support for those properties shown as mandatory and may implement support for those properties shown as optional. The defaultscope for a property is HANDLER. The standard properties form a set of metadata that describes the context of a particular message. Properties are scoped as either APPLICATION or HANDLER.1.1) are passed a message context of type LogicalMessageContext when invoked. For example.1 javax..4 lists those properties that are specific to endpoints running inside a servlet container. It extends Map<String.handler. 2007 . Sections 9. if a logical handler puts a property in the message context.g. In addition. on the server.2 describe MessageContext and LogicalMessageContext respectively. the endpoint imple120 JAX-WS 2.2.1 and 9. that property will also be available to any protocol handlers in the chain during the execution of an MEP instance.. 9.Chapter 9.2 lists the set of standard MessageContext properties.1. APPLICATION scoped properties are also made available to client applications (see section 4. ♦ Conformance (Message context property scope): Properties in a message context MUST be shared across all handler invocations for a particular instance of an MEP on any particular endpoint.MessageContext MessageContext is the super interface for all JAX-WS message contexts.handler. the SOAP binding. the JAX-WS runtime or handlers deployed in a protocol binding.1) and service endpoint implementations. service endpoint implementations. JAX-WS bindings may define a message context subtype for their particular protocol binding that provides access to protocol specific features. These properties are only required to be present when using an HTTP-based binding.1.g.LogicalMessageContext Logical handlers (see section 9. it does not provide access to the protocol specific aspects of a message. see section 10. 9. defines that a logical handler deployed in a SOAP binding can access the contents of the SOAP body but not the SOAP headers whereas the XML/HTTP binding described in chapter 11 defines that a logical handler can access the entire XML payload of a message.3 describes the message context subtype for the JAX-WS SOAP binding. Table 9.Object> with additional methods and constants to manage a set of properties that enable handlers in a handler chain to share processing related state.3 lists the standard MessageContext properties specific to the HTTP protocol.1 May 7.1 Standard Message Context Properties Table 9. 9. Handler Framework Different types of handler are invoked with different types of message context.ws. LogicalMessageContext extends MessageContext with methods to obtain and modify the message payload.4. The getSource() method of LogicalMessageContext MUST return null whenever the message doesn’t contain an actual payload. Table 9. A protocol binding defines what component of a message are available via a logical message context.2 javax.xml.4.

9.4. Message Context

Name

Table 9.2: Standard MessageContext properties. Type Mandatory Description Y Specifies the message direction: true for outbound messages, false for inbound messages. A map of attachments to an inbound message. The key is a unique identifier for the attachment. The value is a DataHandler for the attachment data. Bindings describe how to carry attachments with messages. A map of attachments to an outbound message. The key is a unique identifier for the attachment. The value is a DataHandler for the attachment data. Bindings describe how to carry attachments with messages. A list of WS Addressing reference parameters. The list MUST include all SOAP headers marked with the
wsa:IsReferenceParameter= "true" attribute.

javax.xml.ws.handler.message .outbound Boolean

javax.xml.ws.binding.attachments .inbound Map<String,DataHandler>

Y

.outbound

Map<String,DataHandler>

Y

javax.xml.ws.reference .parameters List<Element>

Y

javax.xml.ws.wsdl .description URI

N

.service .port

QName

N N

QName

.interface .operation

QName QName

N N

A resolvable URI that may be used to obtain access to the WSDL for the endpoint. The name of the service being invoked in the WSDL. The name of the port over which the current message was received in the WSDL. The name of the port type to which the current message belongs. The name of the WSDL operation to which the current message belongs. The namespace is the target namespace of the WSDL definitions element.

May 7, 2007

JAX-WS 2.1

121

Chapter 9. Handler Framework

Name

Table 9.3: Standard HTTP MessageContext properties. Type Mandatory Description Y A map of the HTTP headers for the request message. The key is the header name. The value is a list of values for that header. The HTTP method for the request message. The HTTP query string for the request message, or null if the request does not have any. If the address specified using the javax.xml.ws.service.endpoint.address in the BindingProvider contains a query string and if the querystring property is set by the client it will override the existing query string in the javax.xml.ws.service.endpoint.address property. The value of the property does not include the leading ”?” of the query string in it. This property is only used with HTTP binding. Extra path information associated with the URL the client sent when it made this request. The extra path information follows the base url path but precedes the query string and will start with a ”/” character. A map of the HTTP headers for the response message. The key is the header name. The value is a list of values for that header. The HTTP response status code.

javax.xml.ws.http.request .headers Map<String,List<String>>

.method .querystring

String String

Y Y

.pathinfo

String

Y

javax.xml.ws.http.response .headers Map<String,List<String>>

Y

.code

Integer

Y

122

JAX-WS 2.1

May 7, 2007

9.4. Message Context

Name

Table 9.4: Standard Servlet Container-Specific MessageContext properties. Type Mandatory Description Y The ServletContext object belonging to the web application that contains the endpoint. The HttpServletRequest object associated with the request currently being served. The
HttpServletResponse

javax.xml.ws.servlet .context javax.servlet.ServletContext

.request

javax.servlet.http.HttpServletRequest

Y

.response

javax.servlet.http.HttpServletResponse

Y

object associated with the request currently being served. mentation has thrown an exception and the protocol in use does not define a notion of payload for faults (e.g. the HTTP binding defined in chapter 11).

9.4.3 Relationship to Application Contexts
Client side binding providers have methods to access contexts for outbound and inbound messages. As described in section 4.2.1 these contexts are used to initialize a message context at the start of a message exchange and to obtain application scoped properties from a message context at the end of a message exchange. As described in chapter 5, service endpoint implementations may require injection of a context from which they can access the message context for each inbound message and manipulate the corresponding applicationscoped properties. Handlers may manipulate the values and scope of properties within the message context as desired. E.g., a handler in a client-side SOAP binding might introduce a header into a SOAP request message to carry metadata from a property that originated in a BindingProvider request context; a handler in a server-side SOAP binding might add application scoped properties to the message context from the contents of a header in a request SOAP message that is then made available in the context available (via injection) to a service endpoint implementation.

May 7, 2007

JAX-WS 2.1

123

Handler Framework 124 JAX-WS 2.Chapter 9. 2007 .1 May 7.

1 Configuration A SOAP binding instance requires SOAP specific configuration in addition to that described in section 9.1[2] and SOAP 1.2. An ultimate SOAP receiver always plays the following roles: Next In SOAP 1.1 actor is equivalent to a SOAP 1.1.1.1. 4] use different terminology for the same concept: a SOAP 1.1.1 Programmatic Configuration JAX-WS defines APIs for programmatic configuration of client-side SOAP bindings. Server side bindings can be configured programmatically when using the Endpoint API (see 5. In SOAP 1. The additional information can be configured either programmatically or using deployment metadata. A SOAP 1.2). In SOAP 1.org/2003/05/soap-envelope/role/next.xmlsoap. Ultimate receiver In SOAP 1. the next role is identified by the URI http://schemas.org/soap/actor/next. but are otherwise expected to be configured using annotations or deployment metadata. The following subsections describe each form of configuration.2 the ultimate receiver role is identified by the URI http://www.w3. 10.1 the ultimate receiver role is identified by omission of the actor attribute from a SOAP header.w3.2 role.Chapter 10 SOAP Binding This chapter describes the JAX-WS SOAP binding and its extensions to the handler framework (described in chapter 9) for SOAP message processing. the next role is identified by the URI http://www.1 125 . 10.org/2003/05/soap-envelope/role/ultimateReceiver or by omission of the role attribute from a SOAP header. 10.2 terminology.2 endpoint never plays the following role: May 7.2. ♦ Conformance (SOAP required roles): An implementation of the SOAP binding MUST act in the following roles: next and ultimate receiver.1 SOAP Roles SOAP 1.2[3. This specification uses the SOAP 1. 2007 JAX-WS 2.

the javax. attachments specified using the javax.xml.setRoles.xml.attachments.1.ws. SOAP Binding None In SOAP 1. Mime attachments specified by the javax. 126 JAX-WS 2. SOAP SOAP handlers are handlers that implement javax.ws. ♦ Conformance (Incompatible handlers): Implementations MUST throw a WebServiceException when attempting to configure an incompatible handler using Binding.xml.ws. ♦ Conformance (None role error): An implementation MUST throw WebServiceException if a client attempts to configure the binding to play the none role via SOAPBinding. the none role is identified by the URI http://www. at the time a binding provider is created.handler. The handler chain may contain handlers of the following types: Logical Logical handlers are handlers that implement javax.org/2003/05/soap-envelope/role/none.binding.binding.2.2 SOAP Handlers The handler chain for a SOAP binding is configured as described in section 9.ws.SOAPBinding interface is an abstraction of the JAX-WS SOAP binding.xml.xml. • When using Dispatch in SOAP / HTTP binding in message mode. 2007 .SOAPHandler.1. the handler chain returned by the configured HandlerResolver contains an incompatible handler.setRoles.LogicalHandler either directly or indirectly.ws. ♦ Conformance (Default role persistence): An implementation MUST add the required next and ultimate receiver roles to the roles configured with SOAPBinding.ws.binding.soap.attachments.attachments.attachments.inbound and javax.xml. The javax.1.1 May 7.binding.xml. ♦ Conformance (SOAP required roles): An implementation of the SOAP binding MUST NOT act in the none role. ♦ Conformance (Logical handler access): An implementation MUST allow access to the contents of the SOAP body via a logical message context.ws.handler. Logical handlers have access to the content of the SOAP body via the logical message context. ♦ Conformance (Incompatible handlers): An implementation MUST throw WebServiceException when.getRoles. It extends javax.xml.outbound property will be included as mime attachments in the message.Chapter 10.ws.xml.outbound properties defined in the MessageContext 9. 10. The SOAPHandler however may change the properties in the MessageContext Use of javax.outbound property will be ignored as the message type already provides a way to specify attachments.2 can be modified in logical handlers.attachments.w3. Any changes to the two properites in consideration above in the MessageContext after invoking the first SOAPHandler are ignored.outbound property in Dispatch • When using Dispatch in SOAP / HTTP binding in payload mode.2.binding.Binding with methods to configure additional SOAP roles played by the endpoint.setHandlerChain. ♦ Conformance (Default role visibility): An implementation MUST include the required next and ultimate receiver roles in the Set returned from SOAPBinding. A SOAP message with the attachments specified using the properties is generated before invoking the first SOAPHandler.ws.

2. Obtain the set of SOAP roles for the current binding instance.getRoles. 7. This is obtained via Binding. the header is understood if its QName is in the set identified in step 3.3. then neither handlers nor the endpoint are invoked and instead the binding generates a SOAP must understand exception. This is the set of all headers with a mustUnderstand attribute whose value is 1 or true and an actor or role attribute whose value is in the set obtained in step 1.1 127 .getHandlerChain.10. This section is not intended to supercede any requirement stated within the SOAP specification. This is the set of all header QNames that satisfy at least one of the following conditions: (a) that are mapped to method parameters in the service endpoint interface. Refer to the SOAP specification[2. This is returned by SOAPBinding. 5. For each header in the set obtained in step 4. Subsequent actions depend on whether the message exchange pattern (MEP) in use requires a response to the message currently being processed or not: May 7.2. If the node does not understand how to process the message.1 SOAP mustUnderstand Processing The SOAP protocol binding performs the following additional processing on inbound SOAP messages prior to the start of normal handler invocation processing (see section 9. Such a model is provided by JSR 109[15] “Implementing Enterprise Web Services”.3 SOAP Headers The SOAP headers understood by a handler are obtained using the getHeaders method of SOAPHandler. 3.2).2 Processing Model The SOAP binding implements the general handler framework processing model described in section 9.getHeaders() for each SOAPHandler in the set obtained in step 2. 6. Otherwise the node does not understand how to process the message. then the node understands how to process the message. Identify the set of must understand headers in the inbound message that are targeted at this node. 10.2 Deployment Model JAX-WS defines no standard deployment model for handlers. If every header in the set obtained in step 4 is understood. (b) are members of SOAPHandler.1. 2. 3. 4. Obtain the set of Handlers deployed on the current binding instance.3 but extends it to include SOAP specific processing as described in the following subsections. (c) are directly supported by the binding instance. 4] for a normative description of the SOAP processing model.1. 10. Identify the set of header qualified names (QNames) that the binding instance understands. 10.1. Processing Model 10. but rather to outline how the configuration information described above is combined to satisfy the SOAP requirements: 1. 2007 JAX-WS 2.

Inbound The exception is passed to the binding provider.2. The current message is not already a fault message (the handler might have undertaken the work prior to throwing the exception).2.2).3.2.2.1 May 7. A server side implementation of the SOAP binding is responsible for catching exceptions thrown by a service endpoint implementation and.2. • Handler processing is resumed as described in section 9. • If the exception is of any other type then a new SOAP fault message is created to reflect a server class of error for SOAP 1.2 Service Endpoint Exceptions Service endpoints can throw service specific exceptions or runtime exceptions.2.2). The current message is replaced by the new SOAP fault message. if the message exchange pattern in use includes a response to the message that caused the exception. see section 6.2.1.2[3]. SOAP Binding Response The message direction is reversed and the binding dispatches the SOAP must understand exception (see section 10. If the criteria for converting the exception to a fault message subject to further handler processing are not met then the exception is handled as follows depending on the current message direction: Outbound A new SOAP fault message is created to reflect a server class of error for SOAP 1.2.3. converting such exceptions to SOAP fault messages and invoking the handleFault method on handlers for the fault message as described in section 9. see section 10. Section 10.2 Exception Handling The following subsections describe SOAP specific requirements for handling exceptions thrown by handlers and service endpoint implementations.3.1[2] or a receiver class of error for SOAP 1. 10.1[2] or a receiver class of error for SOAP 1. A binding is responsible for converting the exception to a fault message subject to further handler processing if the following criteria are met: 1. A handler throws a ProtocolException from handleMessage 2.3.1 Handler Exceptions A binding is responsible for catching runtime exceptions thrown by handlers and following the processing model described in section 9. If the above criteria are met then the exception is converted to a SOAP fault message as follows: • If the exception is an instance of SOAPFaultException then the fields of the contained SAAJ SOAPFault are serialized to a new SOAP fault message. The MEP in use includes a response to the message being processed 3.2.3 describes the rules for mapping an exception to a SOAP fault. 128 JAX-WS 2. In both cases they can provide protocol specific information using the cause mechanism.2. No response The binding dispatches the SOAP must understand exception (see section 10.2.2.Chapter 10. 2007 . 10.2[3] and the message is dispatched.4.2.2. 10.

which is also the value of the constant javax.10.2. 2007 JAX-WS 2.SOAPBinding. Empty • detail (Detail in SOAP 1.getFault().2.1 129 .3 Mapping Exceptions to SOAP Faults When mapping an exception to a SOAP fault.getFault().3. ♦ Conformance (SOAP 1. WS-I Simple SOAP Binding Profile[28] and WS-I Attachment Profile[29].xml. 1 If the exception is a SOAPFaultException or has a cause that is a SOAPFaultException.getFaultCodeAsQName()1 2.3 SOAP Message Context SOAP handlers are passed a SOAPMessageContext when invoked.getFault().2) 1.1[2] and SOAP With Attachments[34] as clarified by the WS-I Basic Profile[18].xmlsoap. Serialized service specific exception (see WrapperException.SOAP11HTTP BINDING. SOAPFaultException.toString() • faultactor (Role in SOAP 1.1 HTTP Binding Support): An implementation MUST support the HTTP binding of SOAP 1.ws.getFaultString()1 2. 4] can be bound to multiple transport or transfer protocols. Code set to env:Receiver) 1.soap.org/wsdl/soap/http. Exception.getMessage() 3. 10.2. May 7. SOAPFaultException.4 SOAP Transport and Transfer Bindings SOAP[2.5) 2. SOAPMessageContext extends MessageContext with methods to obtain and modify the SOAP message payload. • faultstring (Reason/Text 1.1 HTTP The SOAP 1. Exception. 10. the fields of the fault message are populated according to the following rules of precedence: • faultcode (Subcode in SOAP 1.2). SOAP Message Context 10. SOAPFaultException.2) 1.getFaultActor()1 2.getFaultInfo() in section 2. This section describes requirements pertaining to the supported protocols for use with SOAP. env:Server (Subcode omitted for SOAP 1.getFault().4.1 HTTP binding is identified by the URL http://schemas. SOAPFaultException.getDetail()1 10.

which is also the value of the constant javax.ws.soap.SOAPBinding. non-optimized messages being also acceptable.xml.1 May 7. SOAPBinding defines a property (in the JavaBeans sense) called MTOMEnabled that can be used to control the use of MTOM.1 and SOAP 1.SOAP12HTTP MTOM BINDING MUST have MTOM enabled by default. and a sender MAY send an optimized message.2 over HTTP with MTOM enabled.SOAPBinding. The setMTOMEnabled method is used to change the value of the property so as to enable or disable the use of MTOM.SOAP11HTTP MTOM BINDING javax.2[4].SOAPBinding. The getMTOMEnabled method is used to query the current value of the property.soap.ws.soap.2 HTTP Binding Support): An implementation MUST support the HTTP binding of SOAP 1.ws. 2007 . JAX-WS inherits the JAXB support for the SOAP MTOM[26]/XOP[27] mechanism for optimizing transmission of binary data types. ♦ Conformance (MTOM support): Predefined SOAPBinding instances MUST support enabling/disabling MTOM support using the setMTOMenabled method.soap. The URL of the latter is http://www.ws.org/2003/05/soap/bindings/HTTP/?mtom=true and its predefined constant javax. 10. The URL of the former is http://schemas. if an application attempts to change its value.SOAP12HTTP BINDING MUST have MTOM disabled by default.w3.SOAPBinding.SOAPBinding. In this case.w3.xmlsoap.SOAP11HTTP BINDING javax.1.1 MTOM ♦ Conformance (SOAP MTOM Support): An implementation MUST support MTOM[26]1 . a receiver MUST accept both non-optimized and optimized messages.soap.org/wsdl/soap/http?mtom=true and its predefined constant javax.SOAP12HTTP BINDING.xml. an implementation MUST throw a WebServiceException.soap. this specification defines two additional binding identifiers for SOAP 1. 1 130 JAX-WS 2.Chapter 10. ♦ Conformance (Semantics of MTOM enabled): When MTOM is enabled. ♦ Conformance (SOAP 1.xml. The heuristics used by a sender to determine whether to use optimization or not are implementation-specific.ws. ♦ Conformance (SOAP bindings with MTOM enabled): The bindings corresponding to the following IDs: javax.SOAPBinding.ws.2 HTTP binding is identified by the URL http://www. For convenience.4.xml.soap.xml.ws.SOAP12HTTP MTOM BINDING.xml.xml. ♦ Conformance (MTOM on Other SOAP Bindings): Other bindings that extend SOAPBinding MAY NOT support changing the value of the MTOMEnabled property.SOAP11HTTP MTOM BINDING. SOAP Binding The SOAP 1. see section 2.4.org/2003/05/soap/bindings/HTTP/.SOAPBinding. ♦ Conformance (SOAP bindings with MTOM disabled): The bindings corresponding to the following IDs: javax.

xml. implementations wait for the HTTP response even though there is no SOAP message in the HTTP response entity body.1.ws.xml.4. The client stores the cookie and returns it in subsequest messages to the service.1 defines two standard context properties (javax.auth. not that the request was accepted or processed. When using HTTP as the transfer protocol for a one-way SOAP message. ♦ Conformance (HTTP basic authentication support): An implementation of the SOAP/HTTP binding MUST support HTTP basic authentication.xml.auth.maintain) that may be used to control whether a client side runtime will join a session initiated by a service.username and javax.ws. SSL The SSL session ID is used to track a session.security.auth.ws.2 One-way Operations HTTP interactions are request-response in nature. ♦ Conformance (URL rewriting support): An implementation MUST support use of HTTP URL rewriting for state management.3 Security Section 4. ♦ Conformance (Cookie support): An implementation SHOULD support use of HTTP cookies for state management.username and javax.4.password) that may be used to configure authentication information. A SOAP/HTTP binding implementation can use three HTTP mechanisms for session management: Cookies To initiate a session a service includes a cookie in a message sent to a client.session.4. URL rewriting To initiate a session a service directs a client to a new URL for subsequent interactions. ♦ Conformance (One-way operations): When invoking one-way operations. However. ♦ Conformance (Authentication properties): A client side implementation MUST support use of the the standard properties javax.1.4 Session Management Section 4.xml. The new URL contains an encoded session identifier. 10.auth.1.1.10.1 defines a standard context property (javax. SOAP Transport and Transfer Bindings 10.1.password to configure HTTP basic authentication. an implementation of the SOAP/HTTP binding MUST block until the HTTP response is received or an error occurs.security.security.4.security.ws.2. 2007 JAX-WS 2. Note that completion of the HTTP request simply means that the transmission of the request is complete. R1120 in WS-I Basic Profile 1. ♦ Conformance (SSL session support): An implementation MAY support use of SSL session based state management. May 7.1[18] allows a service to use HTTP cookies. 10.ws.xml.1 131 .2. R1121 recommends that a service should not rely on use of cookies for state management.

Chapter 10.ws.1 May 7. SOAP Binding 10. 132 JAX-WS 2.1. ♦ Conformance (SOAP Addressing Support): An implementation MUST support WS-Addressing 1. implementations are required to follow WS-Addressing[24][33] protocols.xml.5 Addressing If the javax. 2007 .4.0 SOAP Binding[33].soap.AddressingFeature is enabled.

11.outbound property will be included as mime attachments to the message.outbound property in Dispatch • When using Dispatch in XML / HTTP binding in payload mode.ws.1.binding.ws. May 7.1 133 .http.w3.1 Programmatic Configuration JAX-WS only defines APIs for programmatic configuration of client side XML/HTTP bindings – server side bindings are expected to be configured using deployment metadata.binding. 11. An XML/HTTP binding instance allows HTTP-specific configuration in addition to that described in section 9. Use of javax.1 Configuration The XML/HTTP binding is identified by the URL http://www.ws.LogicalHandler either directly or indirectly.handler. 2007 JAX-WS 2.attachments.2.xml.1.HTTP BINDING.1. which is also the value of the constant javax.1 HTTP Handlers The handler chain for an XML/HTTP binding is configured as described in section 9.ws. The following subsections describe each form of configuration.xml. The handler chain may contain handlers of the following types: Logical Logical handlers are handlers that implement javax.org/2004/08/wsdl/http. attachments specified using the javax.xml.2. The JAX-WS XML/HTTP binding provides “raw” XML over HTTP messaging capabilities as used in many Web services today. ♦ Conformance (XML/HTTP Binding Support): An implementation MUST support the XML/HTTP binding.1.xml. 11.Chapter 11 HTTP Binding This chapter describes the JAX-WS XML/HTTP binding. The additional information can be configured either programmatically or using deployment metadata.HTTPBinding. Logical handlers have access to the entire XML message via the logical message context.attachments.

1 Handler Exceptions A binding is responsible for catching runtime exceptions thrown by handlers and following the processing model described in section 9. 2007 .1 May 7. the handler chain returned by the configured HandlerResolver contains an incompatible handler. The current message is not already a fault message (the handler might have undertaken the work prior to throwing the exception). The MEP in use includes a response to the message being processed 3.outbound property will be ignored. Such a model is provided by JSR 109[15] “Implementing Enterprise Web Services”. HTTP Binding • When using Dispatch in XML / HTTP binding in message mode. Dispatch of type DataSource should be used to send mime attachments for the XML / HTTP binding in message mode. A handler throws a ProtocolException from handleMessage 2. 11.1.2. Any current XML message content is removed.1 Exception Handling The following subsections describe HTTP specific requirements for handling exceptions thrown by handlers and service endpoint implementations.Chapter 11.2 Deployment Model JAX-WS defines no standard deployment model for handlers. 11. 134 JAX-WS 2.3.2. ♦ Conformance (Incompatible handlers): Implementations MUST throw a WebServiceException when attempting to configure an incompatible handler using Binding. If the above criteria are met then the exception is converted to a HTTP response message as follows: • If the exception is an instance of HTTPException then the HTTP response code is set according to the value of the statusCode property.xml.setHandlerChain. 11.2 Processing Model The XML/HTTP binding implements the general handler framework processing model described in section 9.attachments.1.2. ♦ Conformance (Incompatible handlers): An implementation MUST throw WebServiceException when. at the time a binding provider is created. the javax.3. A binding is responsible for converting the exception to a fault message subject to further handler processing if the following criteria are met: 1. ♦ Conformance (Logical handler access): An implementation MUST allow access to the entire XML message via a logical message context.binding. 11.ws.

1. any current XML message content is removed and the message is dispatched.1.11.3.1. In both cases they can provide protocol specific information using the cause mechanism.3. the status code of the HTTP fault message is populated according to the following rules of precedence: 1. if the message exchange pattern in use includes a response to the message that caused the exception.2. • Handler processing is resumed as described in section 9.2 Service Endpoint Exceptions Service endpoints can throw service specific exceptions or runtime exceptions.3 Mapping Exceptions to a HTTP Status Code When mapping an exception to a HTTP status code.1 HTTP Support One-way Operations HTTP interactions are request-response in nature. Section 11. converting such exceptions to HTTP response messages and invoking the handleFault method on handlers for the response message as described in section 9.2. 2007 JAX-WS 2.4.3 11. HTTP Support • If the exception is of any other type then the HTTP status code is set to 500 to reflect a server class of error and any current XML message content is removed. 1 If the exception is a HTTPException or has a cause that is a HTTPException.2. When used for one-way messages. not that the request was accepted or processed.2.1 135 . 11.3. A server side implementation of the XML/HTTP binding is responsible for catching exceptions thrown by a service endpoint implementation and. ♦ Conformance (One-way operations): When invoking one-way operations. Note that completion of the HTTP request simply means that the transmission of the request is complete.3.3 describes the rules for mapping an exception to a HTTP status code. implementations wait for the HTTP response even though there is no XML message in the HTTP response entity body. see section 6. If the criteria for converting the exception to a fault message subject to further handler processing are not met then the exception is handled as follows depending on the current message direction: Outbound The HTTP status code is set to 500 to reflect a server class of error. HTTPException.1. an implementation of the XML/HTTP binding MUST block until the HTTP response is received or an error occurs. May 7. 11. 11.getStatusCode()1 2. Inbound The exception is passed to the binding provider. 500.2.

xml. ♦ Conformance (Cookie support): An implementation SHOULD support use of HTTP cookies for state management. The client stores the cokkie and returns it in subsequest messages to the service. 2007 . ♦ Conformance (Authentication properties): A client side implementation MUST support use of the the standard properties javax.2 Security Section 4.Chapter 11.security.session. The new URL contains an encoded session identifier. 136 JAX-WS 2. HTTP Binding 11.xml.password) that may be used to configure authentication information.username and javax.xml. ♦ Conformance (SSL session support): An implementation MAY support use of SSL session based state management.password to configure HTTP basic authentication. URL rewriting To initiate a session a service directs a client to a new URL for subsequent interactions. ♦ Conformance (URL rewriting support): An implementation MUST support use of HTTP URL rewriting for state management.1.maintain) that may be used to control whether a client side runtime will join a session initiated by a service.1 defines two standard context properties (javax.1 defines a standard context property (javax.ws. ♦ Conformance (HTTP basic authentication support): An implementation of the XML/HTTP binding MUST support HTTP basic authentication.1.security.username and javax.auth.3.xml.3.auth. A XML/HTTP binding implementation can use three HTTP mechanisms for session management: Cookies To initiate a session a service includes a cookie in a message sent to a client.ws.auth.2.ws.security.security. 11.ws.xml.2.1 May 7.ws.auth. SSL The SSL session ID is used to track a session.3 Session Management Section 4.

. .9 WSDL 1. . . . . . .Appendix A Conformance Requirements 2. . . . . . . . . . . . .2 2. . . . . . . . . . . . . . . . . . . . .SOAPBinding . . . . . .xml. . 11 2. . . . . . . . . .jws. . . . . 10 Optional WSDL extensions . . . . . . . . . .ws. . . . . . . . . . . . . . . . Annotations on generated classes . . . . .18 Non-wrapped parameter naming . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .14 Using javax. . . . . . . . . . . . . . . . . . . . . . . . 10 2. . . . . .12 Transmission primitive support . . . . . . . . . . . . . . . . . . . . . . . . . .22 Parameter name clash . . . . . . 11 2. . . . . . . . . . . Definitions mapping . . . . . . . . . . .WebParam . . . . . . . . . . . . . . . . . . . . . .WebService required . . . . . . . . . . .13 Using javax. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 12 2.24 Using javax. . . .10 Method naming . . . .15 Using javax. . . . . . . . . . . . . . .4 2. .20 Disabling wrapper style . . . 10 SEI naming . .WebResult . . . . . . . . . . . . . . . . . . . . . . 12 2. . . . . . . . . .OneWay . . 10 javax. . . . . . . . . . . . . . . . . . .21 Wrapped parameter naming . . .jws. . . . . . . . . .bind. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .23 Using javax. . . . . . . . . . . . . .1 support . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Customization required . . . . . . . . .19 Default mapping mode . . 14 2. . . . . . . . . . . . . . . . 14 2. . . . . . . . . . . . . . . . . . 12 2. . . . . . . . . .1 137 . . . .3 2. . . . . . . . . . . . . . . . . . . . . . 13 2.11 javax. . . . . . . . 12 2. . . . . . . . . . . . . . . . . . . . . . . . . . .16 Using javax. . . . . . . . . . . . . . . . . . . . . 12 2. . . . . . . . . . . . . . . . . . . . . . . . . . . . .XmlSeeAlso required . . . . . . . . . . . . 12 2.8 2. . . . . . . . . . . . . . . . . 14 2. . . . . . . . . . .jws. .xml. . . . . . . . .ws. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .WebMethod required . . . . . . . . . . . . . . . . . . . . . . . . . . . .jws. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .1 2. . . . . . . . . . . . . . . . . . . . . . . . 14 May 7. . . . . . .ResponseWrapper . . . .6 2. . . . . . . 2007 JAX-WS 2. . . .17 use of JAXB annotations . . . . . 9 9 9 9 WSDL and XML Schema import directives .7 2.jws. . . . . . . . . 14 2. . . . . . . . . . . . . . . . . . . . . . . . . . .5 2. . .xml. . . . . . . . . . 10 javax. . . . . . . . . . .RequestWrapper . 14 2. . . . . . . .jws. . . . . .

. . . . . . . . . . . . . . . . . .ws. . . . . . .1 May 7. . . . . . . . . . . . . . . . . . . . . . . 28 . . . . . . . . . . .xml. . . . 18 2. . . . . . . . . . . .WebEndpoint required . . . . . . . . . . . . . . . .26 Asynchronous mapping required . . . . . . . . . . . . 31 JAX-WS 2. 28 2. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .43 Unbound message parts . . . . . . . . . . . . . .ws. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Conformance Requirements 2. . . . . . . . . . 22 2. . . . . . . . . . . . . . . . . . . . . . . . . . .37 javax. . . . . . . 26 2. . . . . . . . . . . .32 Asynchronous fault reporting . . . . . . . . . . 21 2. . . 19 2. . . . . . . . . . . . . . . . .33 Asychronous fault cause . . . . . . . . . . . . . . . . . .52 2. . . . 19 2. . . . . .42 Required WSDL extensions . . . . . 25 2.ws. 28 . . .46 Use of MIME type information . . . . . . . . 31 Java identifier mapping . . . . . . . . . . . . . . . . . . . . . .28 Asynchronous method naming . .50 Service class naming . . . . . . . . . . . .41 Fault equivalence . . . . . . . . . . .39 Exception naming . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .1 3. . . . . . . . . . . .3 138 WSDL 1. . . . . . . . . . . . . . . . . . . . . . . . .49 Service superclass required . . . 18 2. . . . . . . . . . . . .51 javax. . . . . . . . . . . . . . . . . . . . . . . . . 22 2. . . . . . . . .34 JAXB class mapping . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 28 2. . . . . . 26 2. . . . . . . . . . . . . . . . . . . . . . . . . . .29 Asynchronous parameter naming . . . . . . . . . . . . . . . . . .WebFault required . 21 2. . .xml.Appendix A. . .48 MIME part identification . .2 3. . . . . . . . . . 26 2. . . .ws. . .xml. . . . . . . . . . . . . . . . . .54 Failed getPort Method . . . . . . . . . . . . . . . . . . .W3CEndpointReference . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 23 2. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .25 Use of Holder . . . . . . . . . . . .40 Fault equivalence . . . 22 2. . . . . . . .53 . . . . . . . . . 31 Standard annotations . . . . . . . . . . . . . .1 support . . . . . . . . . . . .WebServiceClient required 2. . . . . . . . . . .36 JAXB customization clash . . .27 Asynchronous mapping option . . . . . . . . . . .wsaddressing. . . . . . . . . . 17 2. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 18 2. . . . . . . . . . . . 22 2. . . . . . . . . . 26 2. . . . . . . . . . . . . . . . . . . . . . . . . . . 25 2. . . . . . . . . . 26 2. . . 23 2. . . . . . . . . . . . . 21 2. . . . .47 MIME type mismatch . . . . 2007 . . . . . . . . . . . . . . . . . . . . . . . . . . .35 JAXB customization use . . . . . . . . . .45 Duplicate headers in message . . . 17 2. . . . . . . . . . . . . .44 Duplicate headers in binding . . . . . . . . . . . . . . . . . . . . . . .30 Failed method invocation . . . . . . . . . . . . . . . . . . . . . . . . . .31 Response bean naming . . . . . . . . . . . . . . 17 2. . . . . . . . . . . . . . . . . . . . . . 18 2. . . .38 javax. 23 2. . . . . . . . . . . . . . . . . . . . . .55 javax. . . . . . . . . . . . . . . . . . .xml. . . . . . . . . . . . . . . . . . . . . . . . . . . . 28 3. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

. . . . . . . . . . . . . . . . . . . . . .28 SOAP binding support . . . . . . . . 32 portType naming . . . . . . . .29 SOAP binding style required . . . . . . . . . . . . . . . . . . 42 3. .31 Port selection . . . . 41 3. . . . . . . . . . . . . . . . . . . . 46 3. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 51 Service Creation Failure . . . . . 34 3. . . . 41 3. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .16 Parameter naming . . . . . .RemoteExceptions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .11 Operation naming . . . . . . . . . . . . 2007 JAX-WS 2. . . . . . . . . . . 47 3. . . . . . . .lang. . . . . . . . . . . . . . . . . . . . . . . .10 Inherited interface mapping . . . . . . . . . . . . . . . . . 54 May 7. . . . . . . . . . . . . . . . . . .32 Port binding . . . . . . . . . .14 use of JAXB annotations . . . . . . . . . . .27 Binding selection . . . . . .1 139 . . . . . . . .22 Wrapper bean name clash . . . . . . . . . . . . . . . . . . . . . . . . . . . .9 Method name disambiguation . . . .21 Wrapper element names . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .1 4. . . . . 37 3. . . . . . . . . . . . . . . . .6 3. . . 41 3. . . . . .30 Service creation . . . . . . . . . . . . . . . . . . . .RuntimeExceptions and java. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 50 3. . .26 Fault bean name clash . . . .13 One-way mapping errors . . . . 43 3. . . . . . . . . . . . . . . . . . . . . . . . . .getEndpointReference . . . . . . . . . . 31 Package name mapping .15 Parameter classification . . . . . . . . . . . . . . . . . . . . . . 38 3. .8 3. . . . . .18 Header mapping of parameters and results . . . . . . . . . . . . . . . . . . . . . . . . . . . . .25 java. . .23 Null Values in rpc/literal . . . .xml. . . . . . . . . . . . . . . . .19 Default wrapper bean names . . . . . . . . . . . . . . . . . . . 32 Class mapping .3. . . . .20 Default wrapper bean package . . . . . . . . . . . . . . . . . . . . . .5 3. .2 4. . . . . . . . . . . . . . . . . . .24 Exception naming . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 38 3. . . 34 3. . 33 3. . . . . . . . . . . .rmi. . . . . . . . . . . . . . . . . 37 3. . . . . . . . . . . . . . . . . . . . . . . . . . . . . .BindingProvider. . . . . . . . . . . . . . . . . . . . . . . . . . . . . .3 4. . . . . . . . . . . .ws. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 50 4. . . . . 54 javax. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 38 3. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 33 3. . . . . . . . . . . . . . . . . . . 46 3.5 Service completeness . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 32 WSDL and XML Schema import directives . . . . . . . . 38 3. . . . . . . . . . . . . . . . . . . . . . . . . . . 52 Use of Executor . . . . . . . . . . . . . . . . . .4 3. . . . .4 4. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 33 Inheritance flattening . . . . . . . . . . . . 37 3. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .12 One-way mapping . . . . . . . . . . . . . . . . . . . . 33 3. . . . . . . . . . . . . . . . . . . . . . . . . . . . . 54 Default Executor . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 38 3. .7 3. . . . . . . . . 38 3. . . . . . . .17 Result naming . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

. . . . . . . . . . . .10 Asynchronous response context 4. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 56 . . . . . . . . . . . . . .9 Provider support required . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .invoke . 75 5. . . . . . . . . . . . . . 65 Endpoint publish(String address. . . . . . . . . . . . . . . . . 70 5. . . . . . . . . . . .12 Implementing BindingProvider . . . . . . . . . . .xml. . . . . . . . . . . . . . .ws. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .spi. . . Conformance Requirements 4. .9 Message context decoupling . .14 Default Executor . 61 4. . . . . . . . . . 57 4.7 5. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .6 5. . . . . . . . . . . . 56 Optional BindingProvider properties . . . .5 5.16 Other Exceptions . . . . . . . . . . . . . . . . . . . . 55 Required BindingProvider properties . . . . . .2 140 Read-only handler chains . . .3 5. . . . . . . . . . . . 59 4. . . . . . . . . . . . . 2007 . .1 6. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 65 Provider default constructor . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .8 4. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 57 4. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .getPort failure . . . . . . . . . . . . . . . . . . . . . 68 Publishing over HTTP . . . . . . . . . . 70 5. . . . . . . . . . . . . . . . . . . . . . . . . . . . 65 WebServiceProvider annotation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .23 Use of the Catalog . .4 5. . . . . . . . . . . . . . . . . . . . . . . . 56 Additional context properties . . . . . . . . . . 79 Concrete javax. . . . . . . . .1 May 7. . . . . . . . . . . . 69 WSDL Publishing . . . . . . . . . . . . . . . . .20 Failed Dispatch. . 64 5. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .12 Unknown Metadata . . . . . . . . . . . 57 4. . . . . . . . . . . . . . . . . 68 Other Bindings . . . . . . .8 5. . . . . . . . . . . . 61 4. . . . .22 Marshalling failure . . . . .18 Failed Dispatch. . . . . . . . . . . . . . 58 4. . . . . . . . . . . Object implementor) Method . . . . . . . . . . . . . 68 Default Endpoint Binding . . . . 79 JAX-WS 2. . . .11 Required Metadata Types . . . . . . . . . . . . . . . . . . 61 4. . . .13 Use of Executor . . . . . . . . . . . . . . 61 4. . . . . . . . . 75 6. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 62 4. . . . . . . 70 5. . . . . . . . . . . . . . . . . . . . . . . . . . . .7 4. . . . . . . . . . . . . . . . . . . . . . . . .invokeAsync . . . . . . . . . . . . .6 4.15 Exceptions During Handler Processing . . . . . . . . 69 5. . .21 Reporting asynchronous errors . .Provider required . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .2 5. . . . . . . . . . . . . . .11 Proxy support . . . . . . . . .10 Checking publishEndpoint Permission . . . . . . . . . . . . . . . . .17 Dispatch support . .14 Remote Exceptions . . .invokeOneWay . . . .19 Failed Dispatch. . . . . . . . . . . . . . . 59 4. . 65 Provider implementation . . . . . . . . . . . . . 59 4. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .13 Service. . . . . . . . . . .Appendix A. . . .1 5. . 58 4. . . . . . . . . .

. . . 120 10. . . . . . . . . . . . . . . . 83 enabled property . . . .xml. . . . . . . . . . . . . .10 javax. . . . . . . . . . . . . .MTOMFeature . . . . . . . . . . . .ws. . . . . . . . . . . . . . . . 117 9. . .3 7. . . . . . .12 Invoking close . . .xml. . . . . .2 7. . . . . . . . . . 81 Concrete javax. . . . . .3 6. . . . .3 Default role visibility . . . .1 7. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .5 6. . . . . . . . . . . . . . . . . 85 6. . . . . . . . . . . . . . . . . . . . . . .ws. . . . . . . . . . . . . .4 6. . . . . . . . . . . . . . . . . .13 Order of close invocations . . . . . . . . . . . . . . . . .6. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .1 SOAP required roles . . . . . . .6 9. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .2 8. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 114 HandlerChain annotation . . . . . . . . . . . . . .6 6. . . . . . . . . . . . 126 May 7. . . . . . . . . . .ws. . . . . . . . . . . . . . . . . . . 112 Other handler support . . . . . . . . . .RespectBindingFeature . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 119 9. . . . . . . . . . . .4 7. . . . . . . . . . . . . . . . . 125 10. . . . . . . . . . . . . . . . . . . . . . . .3 9. . 83 javax. . . . . . . . . . .8 6. . . . . . . . . . . . . . . .7 9. . . . . .11 javax. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 115 Binding handler manipulation . . . . . . . . . . . . . . . . . . . . . . . . . .2 9. . . . . 115 Handler resolver for a HandlerChain annotation . . . . . . . . . . . . . 81 Protocol specific fault generation . . . . . . . . . . . . . . . . . .xml. .5 8. . . . . . . . 112 Incompatible handlers . . . . . . . . . . . . . . . . . . 126 10. .1 9. . . . . . . . . . . . . . . . . . . . . . . . 102 Handler framework support . . . . . . . . . . . . . 113 Incompatible handlers . . . . . . . . . 87 Unsupported WebServiceFeatureAnnotation . . . . . . . . .WebServiceFeatures . . . . . . . . . . . . . . . . . . . . . . . . . 87 Handling incorrect annotations . . . . . . . . .1 8. . 82 Protocol specific fault consumption . . . . . . . . . . . 116 9. . . . . . . . . . . . . . . . . . . . . . 113 Handler chain snapshot . . . . . . . . . . . . . . . . . . . . .9 Provider createAndPublishEndpoint Method . . . . 85 7. . . . 82 One-way operations . . . . . . . . . . . 117 9. . . . . . . . 111 Logical handler support . . . . . . . . . . .xml. . . .2 SOAP required roles . . . . 119 9. . . . . . . . . . . . . . . . . . . . . . . . . .3 9. . . . . . . . . . . . . . . . . . . . . . . . .8 9. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2007 JAX-WS 2.10 Handler initialization . . . . . . . . 99 Binding language extensibility . . .11 Handler destruction .1 141 . . . . . . . .ws. . . . . . . . .soap. . . . . . . . . . . . . . . . . . . . . . . . . . . . . .9 Correctness of annotations . . . . . . . . . 90 JSR-181 conformance . . .7 6. . . . . . . . . . . . . . 83 6. .4 9.14 Message context property scope . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 94 Standard binding declarations . . . . . . . . . . . . . . . . . . . . . . .spi. . . . . . . . . . . . . . .5 9. . . . 87 WebServiceProvider and WebService . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .ServiceDelegate required . . . . . 99 Multiple binding files . . . . . . . . . . . . . . . . . . . . . . .

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .10SSL session support . . . . . . . . . .1 XML/HTTP Binding Support . . . . . . . 126 10. . . . . . . . . . . . . . . . . . . . . .8 Logical handler access . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .17One-way operations . . . .8 URL rewriting support . . . . . . . . . . . . . . . . . . .7 Incompatible handlers . . . . . . . . . . 2007 . . . 136 11. . . 126 10. . . . . . . . . . . . . . . . . . . . 136 11. . . . . . . . . . 126 10. . . . . . 131 10. . . . . . . . . . . . . . . . . . . . . . . . . 132 11. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 135 11. 130 10. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .4 Logical handler access . . . . . . . 131 10. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 130 10. . . . .19Authentication properties . . . .6 HTTP basic authentication support . . . .18HTTP basic authentication support . . . . . . . . . . 126 10. . . . . . . . . . . . . . . . Conformance Requirements 10. . . . . . . . . . . . . . . . . . . . . 131 10. . . . . . .1 May 7. . . . . . . . 126 10. . . . . . . . . . .5 One-way operations . . . . . . . . . . . . . . . . . . . . . . . . . .2 Incompatible handlers .7 Authentication properties . . . . . . . . . . . . . . .20URL rewriting support . . . .4 Default role persistence . . . . . . . . . . . 134 11. . . . . . . . . . . . . . .12Semantics of MTOM enabled . . . . . . . . . . . . . . . . .10SOAP 1. . . . . . . .15SOAP bindings with MTOM enabled . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 136 11. . . . . . . . . . . . . . . . . . . . . .3 Incompatible handlers . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 130 10. . . . . . . . . . . . . . . . . . . . . . . . . . . 130 10.5 None role error . . . 131 10. . . . . . . . . . . . . . . . . . . . . . .6 Incompatible handlers . . . . . . . . . . . . . . . 130 10. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .23SOAP Addressing Support . . . . . . . . . . . . . .9 Cookie support . .21Cookie support . . . . .1 HTTP Binding Support . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .2 HTTP Binding Support . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 133 11. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 134 11. . . . . . . 136 11. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .22SSL session support . . . . .16MTOM on Other SOAP Bindings . . . . . . . . . . . . . . . . . . . 129 10. . . . . . . . . . . . . . . . . . . 136 142 JAX-WS 2. . . . . . . . . . . . 131 10. . . . . . . . . . . . . . . . . . 134 11. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .14SOAP bindings with MTOM disabled . . . . . . . . . . .9 SOAP 1. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .Appendix A. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .11SOAP MTOM Support . . . . . . . . . . .13MTOM support . 131 10. . . . . . . . . . . . . 130 10. . . 130 10. .

• Modified description of createEndpoint method to state to cover case when no binding is specified (section 6.2).2).6).5.2. • Added wsa namespace definition (section 1.ws.5).1.6. 3.1). • Added text stating that Dispatch and Provider based applications MUST honor WebServiceFeatures (section 4.1 requirement (sections 1.3 and 5.xml.2).3..7). • Added conformance requirement for Exceptions that are NOT service specific exceptions (section 3.2).8 and 6. • Added getPortName(WebServiceFeature. • Added section 6.getEndpointReference (section 4.2.7). • Added sections 4.EndpointReference.. • Added new getPort methods on Service that take WebServiceFeatures and EndpointReference (section 4.4.5.4 on javax.W3CEndpointReferenceBuilder. 2. • Added conformance requirement for @XmlSeeAlso annotation (section 2.3). May 7. • Added text describing the need to use customizations to resolve some conflicts (section 3.1 Changes since Final Draft • Added JAXB 2.1 W3CEndpointReference.Appendix B Change Log B.ws. 5. 2007 JAX-WS 2. • Added conformance requirement for BindingProvider.4 EndpointReferences.1).2). • Added conformance requirement for use of JAXB annotations (section 2.2. • Added clarification that not both input and output messages must be present for wrapper style (section 2. • Added conformance requirement to honor JAXB annotations (section 3.4.1. • Added section 2.1.1 javax.3.wsaddressing.xml.1 143 .4).2.) method to generated Service (section 2. • Added section 5.

13 and 7.3).2.outbound in Dispatch • Added clarification for usage of null in Dispatch (section 4.reference.7).3).1). 7. • Added inner class mapping requirements.0 support will be added a future revision of the specification.xml. Change Log • Added section 6. • Added conformance requirements for RequestWrapper and ResponseWrapper annotations (section 2.7 (section 7.2.2. • Added Action.xml.2.Appendix B.4 and added requirement on XmlType annotation on a generated fault bean (section 3.14). • Added conformance rquirement for unsupported WebServiceFeatureAnnotations (section 7).1. 144 JAX-WS 2. • Clarified usage of generics in document wrapped case.5).3). • Added section 10.parameters standard message context property (table 9. • Renamed section 5.2.4.xml. • Removed references to WSDL 2.2).close methods (section 9.5 Getting Port Objects.attachments.2).ws.2. • Added new binding identifiers for SOAP/HTTP bindings with MTOM enabled (section 10.3. • Rephrased rules on using WebServiceContext so that the limitations that apply in the Java SE environment are marked as such (section 5. this included adding a new conformance requirement (section 3.2. • Clarified order of invocation of Handler.3).2).WebServiceFeature.1 May 7.5 Addressing.2). since this conflicts with 3.* namespaces for Java specifications (section 4.1. B.3.ws.6.12.binding.1. • Added a requirement that a class annotated with WebServiceProvider must not be annotated with WebService (section 7. • Added section 6. 3. FaultAction and WebServiceFeatureAnnotation annotations (sections 7. • Clarified requirement on additional context properties and reserved the java.7).1.* and javax.ws.4. • Clarified the nillability status of various elements in the Java to WSDL binding (sections 3.4. • Added javax.2 Changes since Proposed Final Draft • Added clarification for usage of javax.5 and added new requirements around generation of the contract for an endpoint (section 5.1).6. 2007 .1.6.2. • Fixed example in figure 3.0 and updated goals to reflect WSDL 2.1. • Added requirement detailing the semantics of ”MTOM enabled” (section 10.5 javax. • Removed requirement that the ”name” element of the WebFault annotation be always present.2).

2).header usage (section 3.3 Changes since Public Draft • Changed endpoint publishing so that endpoints cannot be stopped and published again multiple times (section 5. • Clarified that criteria for bare style take only parts bound to the body into account (section 3. • Removed requirements to support additional SOAP headers mapping. • Use of WebParam and WebResult partName.1). • Clarified that parts bound to mime:content are treated as unlisted from the point of view of applying the wrapper style rules (section 2.2). • Added clarifications for XML / HTTP binding.4). Changes since Public Draft • Added a conformance requirement for support of the XML/HTTP binding. • Adding a requirement on dealing with exceptions thrown during handler processing (section 4.header WebResult.6.1 and 11. • Fixed erroneous reference to a ”generated service interface” in section 7. • Added requirements around binding identifiers for implementation-specific bindings (section 6. Same thing for Dispatch (section 4.1 145 .2. • Added javax.1.xml.session message context property (section 9. May 7.2.9 (the correct terminology is ”generated service class”).3).1). • Added support for DataSource as a message format for Provider and clarified the requirement for the other supported types (section 5. • Clarified that LogicalMessageContext.B.servlet. • Add a create(Object implementor) to Endpoint to create an Endpoint.1).3).2. • Clarified that request and response beans do not contain properties corresponding to header parameters (section 3.getSource() may return null when there is no payload associated with the message (section 9.xml.2. • Replaced the init/destroy methods of handlers with the PostConstruct and PreDestroy annotations from JSR-250 (section 9.6) and updated WSDL SOAP HTTP Binding section (3.1). • Added WebParam. 2007 JAX-WS 2.WebServiceRefs annotation (section 7.3.3. • Removed the javax.1). • Added explicit mention of the predefined binding identifiers (sections 10.1).2). • Clarified the use of INOUT param with two different MIME bindings in the input and output messages.6.1). • Corrected signature for Endpoint.1).9.2. in analogy with the existing requirements for SOAP (section 11.2).10).create to use String for bindingId.4.4.ws. B.4.6.ws. • Replaced the BeginService/EndService annotations with PostConstruct and PreDestroy from JSR-250 in endpoint implementors (section 5.

1).6).2) .10).2.4.3). • Added requirement for conformance to the JAX-WS profile in JSR-181 (section 7. • Added condition that the wrapper elements be non-nillable to wrapper style (section 2.2.1).8).2.1). • Added effect of the BindingType annotation on the generated WSDL service (sections 3. • Updated the usage of WebMethod exclude element from Java to WSDL mapping.1.3.2).Appendix B.2). • Added use of HandlerChain annotation (section 9. • Added portName element to @WebServiceProvider annotation.1 May 7.6. 2007 . 11.3.2.2.5) and clarified that it is required to be used when processing endpoint metadata at publishing time (section 5.2. in section 4.4).2.1.11). • Updated 181 annotations (section 7. • Added WebServiceRef annotation (section 7. • Added catalog facility (section 4.1. • Added restrictions on metadata at the time an endpoint is published (section 5. Fixed handler ordering section accordingly (section 9.3. • Added requirement on correctness of annotation to the beginning of chapter 7.7.2.8 and 3. 146 JAX-WS 2. • Clarified naming rules for generated wrapper elements and their type (section 3.1. Change Log • Removed the ParameterIndex annotation (chapters 3 and 7).2).2. • Added zero-argument public constructor requirement to the implementation-specific Provider SPI class (section 6. • Added service delegate requirements to chapter 4.1. • Clarified that holders should never be used for the return type of a method (section 2. • Clarified that endpoint properties override the values defined using the WebServiceProvider annotation (section 5. • Replaced HandlerRegistry with HandlerResolver (sections 4. • Removed mapping of headerfaults (sections 2. • Added requirement that a provider’s constructor be public (section 5.5) and annotations (chapter 7).1.2.2).2 and 8.10).1 and 3. • Updated use of SOAPBinding on a per method basis in the document style case and removed editor’s note about SOAPBinding not being allowed on methods (section 2.7).destroy (section 9. 10.6.6.1.3).1. • Clarified invocation of Handler.1.2. • Split standard message context properties into multiple tables and added servlet-specific properties (section 9.3.1).1).2.1. • Fixed some inconsistencies caused by the removal of RemoteException (e.11).g. • Changed the algorithm for the default target namespace from java to WSDL (section 3. 9. • Clarified use of targetNamespace from WebService in an implementation class and an SEI based on 181 changes.1.

4 Changes Since Early Draft 3 • Added requirements on mapping @WebService-annotated Java classes to WSDL. since their role is now taken by annotations: java. B.2. Changes Since Early Draft 3 • Added WebServiceContext (section 5. • Fixed package name for javax.2.xml.request. • Removed definition of message-level security annotations (section 7.ws. • In section 10. • Added BindingType annotation (section 7.EndpointFactory (section 5.ws. • Added WebServiceProvider annotation in javax.Provider and updated section with WebServiceProvider annotation (section 5.http.createPort method to Service. • Added requirement the provider endpoint implementation class carry a WebServiceProvider annotation (section 5. • Removed WSDL 2.2 and 6.5).xml.1). • Fixed RequestWrapper and ResponseWrapper description to use that they can be applied to the methods of an SEI (sections 7.2).0 mapping (appendices A and B).1).Provider • Removed javax.8).4).1) and the corresponding message context property (in section 9. their use (sections 4. • Removed javax.1). May 7.ws.ws.addPort.2.2 on the new Endpoint API.spi. • Added the following new annotation types: @RequestWrapper. • Renamed the Service.1).5). refactored message context section in chapter 5 so that it applies to all kinds of endpoints.Servicefactory (section 4.xml.2). 2007 JAX-WS 2.3).method.B.xml. • Added the createService(Class serviceInterface) method to ServiceFactory. • Removed the HTTP method getter/setter from HTTPBinding and replaced them with a new message context property called javax.2.ws.ws package (section 7.1.4 and 7.RemoteException.xml.rmi. • Added 5. • Changed Factory pattern to use javax.1 147 . • Added WebServicePermission (section 5. • Added conformance requirement for one-way operations (section 6. @WebEndpoint.Remote and java. @ResponseWrapper. • Added MTOMEnabled property to SOAPBinding. @WebServiceClient.4. • Removed references to the RMI classes that JAX-RPC 1.rmi.9).1 clarified that SOAP headers directly supported by a binding must be treated as understood when processing mustUnderstand attributes.xml.1 used to denote remoteness.

see section 8.xxx to javax.Throwable with must not be mapped to fault bean properties.ServiceMode annotation type. see section 3.2.6. see sections 8. • Fixed example of external binding file to use a schema annotation. 148 JAX-WS 2. see section 4.xxx.2. see section 3.rpc.1. • Changed the client API chapter to reflect the annotation-based runtime. see section 4. • Changed JAX-RPC to JAX-WS.xml.2. see section 5.ws. removed the requirement that an exception be thrown if the application attempts to set an unknown or unsupported property on a binding provider. • Modified Dispatch so it can be used with multiple message types and either message payloads or entire messages.5 Changes Since Early Draft 2 • Renamed ”element” attribute of the jaxws:parameter annotation to ”childParameterName” for clarity.2.6.ws.xml.3.1.6. Reflected resulting changes made to APIs.4. In particular. B. javax.1.xml.lang. and the spec now simply talks about proxies. • Clarified that SEI method should throw JAX-RPC exception with a cause of any runtime exception thrown during local processing. • Added new context properties to provide access to HTTP headers and status code. see section 3. • Updated document bare mapping to clarify that @WebParam and @WebResult can be used to customize the generated global element names.4. • Removed requirement that SEIs MUST NOT have constants.1 May 7.Appendix B. • Added chapter ?? WSDL 2. • In section 4. 2007 . since there are no stub-specific properties any more.0 to Java Mapping. • Added new XML/HTTP Binding. see section 3.2. see section 7. Change Log • Added getStackTrace to the list of getters defined on java. • Added javax.1. the distinction between generated stubs and dynamic proxies disappeared. • Added ordering to properties in request and response beans for doc/lit/wrapped.7. • Added new annotation for generated exceptions. see section 7.3 and 8. B.2.1. • Added default Java package name to WSDL targetNamespace mapping algorithm. • Modified Provider so it can be used with multiple message types and either message payloads or entire messages.2.4.6 Changes Since Early Draft 1 • Added chapter 5 Service APIs. only those in the request context.7. see chapter 11.

• Fixed section 2. see section 2. • Emphasized control nature of context properties. • Added section for SOAP proocol bindings 10.3. see section 2.11.B.4.8.2. added lifecycle subsection. • Added support for WSDL MIME binding. • Clarified meaning of other in the handler processing section.2.2. see section 2. see section 3.2. • Added use of JAXB package name to ns URI mapping. see 9.5. • Added property for message attachments.4. 2007 JAX-WS 2.6. see section 2.3. May 7.3.6.4 to allow use of JAXB interface based mapping. Client and Server API chapters. • Added support for document/literal/bare mapping in Java to WSDL mapping. • Clarified that additional parts mapped using soapbind:header cannot be mapped to a method return type.1.6. see section 2. • Clarified that fault mapping should only generate a single exception for each equivalent set of faults. • Removed implementation specific methods from generated service interfaces. • Introduced new typographic convention to clearly mark non-normative notes. • Removed element references to anonymous type as valid for wrapper style mapping (this doesn’t prevent substitution as orignally thought).3. • Clarified fixed binding requirement for proxies.1. • Added mapping from Java to wsdl:service and wsdl:port. see section ??. • Added new section to clarify mapping from exception to SOAP fault. see section 2.1 149 .5.3. • Removed references to J2EE and JNDI usage from ServiceFactory description. see 4. see section 2. see 10. see section 2.10. 3.4.1 and 3.1 ‘Runtime Services’ chapter. • Added resolution to issue regarding binding of duplicate headers.2. see section 2. see sections 3. see section 2.7.0 Mapping. • Added a section to clarify Stub use of RemoteException and JAXRPCException. Changes Since Early Draft 1 • Added chapter ?? Java to WSDL 2.6. • Clarified relationship between TypeMappingRegistry and JAXB.4. • Added new Core API chapter and rearranged sections into Core.2. see section 3.2.3.5. • Added use of JAXB ns URI to Java package name mapping.1. • Clarified that async methods are added to the regular sync SEI when async mapping is enabled rather than to a separate async-only SEI.3. The HTTP subsection of this now contains much of the mterial from the JAX-RPC 1. • Clarified behaviour under fault condition for asynchronous operation mapping.1.2. • Added conformance requirement to describe the expected behaviour when two or more faults refer to the same global element.

7.1 May 7. • Added security API information. see section 10. 150 JAX-WS 2.get to throw JAXRPCException. now throws standard java. Change Log • Changes for context refactoring. • Clarrified SOAP mustUnderstand processing. • Updated exception mapping for Java to WSDL since JAXB does not envision mapping exception classes directly. Made it clear that the handler rather than the HandlerInfo is authoritative wrt which protocol elements (e. SOAP headers) it processes.1.Appendix B.2.concurrent.g. added description of rules for moving between jaxws context and message context boundaries. 2007 .ExecutionException instead. • Removed requirement for Response. removed message context properties that previously held request/response contexts on client side.util. see sections ?? and ??. see section 3.

Jeffrey Schlimmer. Note. Sperberg-McQueen. C. Jean Paoli. JSR. Working Draft. October 2000.w3. Greg Meredith. The Java Architecture for XML Binding (JAXB). [11] Kohsuke Kawaguchi.org/en/jsr/detail?id=101. [7] Roberto Chinnici. See http://www. [2] Don Box. M.w3.0 (Second Edition). Noah Mendelsohn. Noah Mendelsohn. May 7.ws-i.w3. [4] Martin Gudgin. Final Material. Recommendation. Marc Hadley. See http://www.0-2004-04-16.0. Jean-Jacques Moreau.1. Marc Hadley. Recommendation. W3C. and Sanjiva Weerawarana. The Java API for XML Based RPC (JAX-RPC) 1. See http://www. Basic Profile Version 1. Mark Nottingham. and Eve Maler. and Prasad Yendluri. [10] Joseph Fialli and Sekhar Vajjhala. August 2003.html. See http://jcp. Web Services Description Language (WSDL) 1.org/en/jsr/detail?id=222.org/TR/2004/WD-wsdl20-20040803. Note.org/TR/2003/REC-soap12-part2-20030624. WS-I.org/TR/2001/NOTE-wsdl-20010315. June 2003. David Ehnebuske. 2007 JAX-WS 2. Jean-Jacques Moreau. [12] Roberto Chinnici. Maintenance JSR. W3C. August 2003. See http://jcp.org/en/jsr/detail?id=101. See http://www.w3. See http://www. March 2001. See http://www. Andrew Layman.0 Part 1: Core Language. and Dave Winer. Extensible Markup Language (XML) 1. The Java Architecture for XML Binding (JAXB) 2. JCP. See http://www.2 Part 1: Messaging Framework.0. August 2003.2 Part 2: Adjuncts. [6] Rahul Sharma. Noah Mendelsohn. and Sanjiva Weerawarana. The Java Architecture for XML Binding (JAXB) 2.1. JCP. W3C.1 151 . and Henrik Frystyk Nielsen. W3C.org/TR/2003/REC-soap12-part1-20030624. JSR. JCP. See http://jcp.org/en/jsr/detail?id=31. August 2004. SOAP Version 1. June 2002. Francisco Curbera.1. Web Services Description Language (WSDL) Version 2. [9] Joseph Fialli and Sekhar Vajjhala. W3C. Martin Gudgin. June 2003. and Henrik Frystyk Nielsen. JCP.w3.w3.1. JCP. JSR. See http://jcp. April 2004. Henrik Nielsen. SOAP Version 1. Recommendation. Martin Gudgin.0. May 2000. Jean-Jacques Moreau. See http://jcp. [5] Erik Christensen. Simple Object Access Protocol (SOAP) 1. Gopal Kakivaya. David Ehnebuske. [8] Keith Ballinger. The Java API for XML Based RPC (JAX-RPC) 1. Satish Thatte.org/TR/2000/REC-xml-20001006.org/TR/SOAP/.org/Profiles/BasicProfile-1. JSR. W3C. January 2003.Bibliography [1] Tim Bray.org/en/jsr/detail?id=222. [3] Martin Gudgin.

[22] Henry S. JSR. 2000. Attachments Profile Version 1. [23] Paul V. JSR. RFC 2119: Keywords for use in RFCs to Indicate Requirement Levels.second edition. and Noah Mendelsohn. See http://www. Bill Joy.html.org/Profiles/AttachmentsProfile-1. XML Schema Part 2: Datatypes.org/TR/2001/REC-xml-infoset-20011024/. August 2004.title. Java API for XML Registries 1. August 2003.w3. JSR. [15] Jim Knutson and Heather Kreger. JCP. Anish Karmarkar.html. Bradner. January 2005. 152 JAX-WS 2. Working Group Draft. Murray Maloney. August 2004. June 2002.ietf. RFC.0 (JAXR). [16] Nataraj Nagaratnam. Basic Profile Version 1. Web Services Metadata for the Java Platform. XML-binary Optimized Packaging. W3C.w3. Final Material.core. Recommendation. Inc. Fielding. Noah Mendelsohn. JSR.ws-i. WS-I.0-2004-08-24. and Herve Ruellan. Mark Nottingham. http://www. May 2001. March 1997. Chris Ferris. See http://jcp.1. See http://www. 2007 .ws-i. [14] Jim Trezzo.w3. Berners-Lee. See http://jcp.org/en/jsr/detail?id=109. Web Services for J2EE. WS-I. RFC 2396: Uniform Resource Identifiers (URI): Generic Syntax.org/TR/2001/REC-xmlschema-2-20010502/. http://www. [29] Chris Ferris. W3C.org/en/jsr/detail?id=175.org/Profiles/SimpleSoapBindingProfile-1.doc. W3C. XML Information Set. Masinter. January 2005. WS-I. [25] James Gosling. Martin Gudgin.org/TR/soap12-mtom/.org/TR/2001/REC-xmlschema-1-20010502/. Thompson. [24] Tony Rogers Marting Gudgin.w3. R. and Prasad Yendluri. and Canyang Kevin Liu. Recommendation. SOAP Message Transmission Optimization Mechanism. August 2003. See http://jcp. XML Schema Part 1: Structures. May 2006. JCP. JCP. JCP. W3C. See http://jcp.html. See http://www.0.com/docs/books/jls/second edition/html/j. RFC. Recommendation.ietf. and Gilad Bracha. Marc Hadley. David Ehnebuske. JCP.sun. [19] T. March 1997.1 May 7.0-2004-08-24. Mark Nottingham. Web Services Message Security APIs. Recommendation. April 2002.org/en/jsr/detail?id=183. Final Material. See http://www.w3. Canyang Kevin Liu.txt. and L. May 2001. A Metadata Facility for the Java Programming Language. September 2002.0 .html. [17] Farrukh Najmi. Mark Nottingham. and Herve Ruellan. Recommendation.txt. http://java. See http://www.BIBLIOGRAPHY [13] Joshua Bloch.org/Profiles/BasicProfile-1.jcp. Noah Mendelsohn. Simple SOAP Binding Profile Version 1.org/rfc/rfc2396. The Java Language Specification . Guy Steele. [20] S. See http://www.org/TR/2006/REC-ws-addr-core-20060509/.org/rfc/rfc2119. [27] Martin Gudgin. [21] John Cowan and Richard Tobin.w3. [28] Mark Nottingham.org/en/jsr/detail?id=181. Book. See http://www. IETF. Sun Microsystems. Biron and Ashok Malhotra. October 2001.org/TR/xop10/. W3C. Recommendation. August 2004. Jorgen Thelin. See http://www. See http://www. [18] Keith Ballinger. [26] Martin Gudgin.1-2004-08-24.ws-i. JSR.0. See http://www.org/en/jsr/detail?id=93. W3C. IETF. Web services addressing 1. David Beech.

May 2006. December 2000. [31] Rajiv Mordani. [33] Tony Rogers Marting Gudgin.org/en/jsr/detail?id=244. July 2005.html. SOAP Messages With Attachments. [32] Bill Shannon.1. 2007 JAX-WS 2. Marc Hadley. OASIS Committee Specification. See http://jcp.php/14041/xml-catalogs.w3. August 2005.org/TR/2006/REC-ws-addr-soap-20060509/. Satish Thatte. July 2005. May 7. OASIS. Web services addressing 1. Note. http://www. and Henrik Frystyk Nielsen.1 153 . W3C.BIBLIOGRAPHY [30] Norm Walsh. See http://www. [34] John Barton. XML Catalogs 1. Java Platform Enterprise Edition 5 Specification.w3. See http://jcp.org/committees/download.org/TR/SOAP-attachments.oasis-open. W3C. See http://www. Recommendation.org/en/jsr/detail?id=250.0 . Common Annotations for the Java Platform. JCP.soap binding. JSR. JSR. JCP.

Sign up to vote on this title
UsefulNot useful