Specification: Jakarta XML Web Services

Version: 4.0

Status: Final Release

Release: February 23, 2022

Copyright (c) 2019, 2022 Eclipse Foundation.

Eclipse Foundation Specification License

By using and/or copying this document, or the Eclipse Foundation document from which this statement is linked, you (the licensee) agree that you have read, understood, and will comply with the following terms and conditions:

Permission to copy, and distribute the contents of this document, or the Eclipse Foundation document from which this statement is linked, in any medium for any purpose and without fee or royalty is hereby granted, provided that you include the following on ALL copies of the document, or portions thereof, that you use:

  • link or URL to the original Eclipse Foundation document.

  • All existing copyright notices, or if one does not exist, a notice (hypertext is preferred, but a textual representation is permitted) of the form: "Copyright (c) [$date-of-document] Eclipse Foundation, Inc. [url to this license]"

Inclusion of the full text of this NOTICE must be provided. We request that authorship attribution be provided in any software, documents, or other items or products that you create pursuant to the implementation of the contents of this document, or any portion thereof.

No right to create modifications or derivatives of Eclipse Foundation documents is granted pursuant to this license, except anyone may prepare and distribute derivative works and portions of this document in software that implements the specification, in supporting materials accompanying such software, and in documentation of such software, PROVIDED that all such works include the notice below. HOWEVER, the publication of derivative works of this document for use as a technical specification is expressly prohibited.

The notice is:

"Copyright (c) 2018 Eclipse Foundation. This software or document includes material copied from or derived from [title and URI of the Eclipse Foundation specification document]."

Disclaimers

THIS DOCUMENT IS PROVIDED "AS IS," AND THE COPYRIGHT HOLDERS AND THE ECLIPSE FOUNDATION MAKE NO REPRESENTATIONS OR WARRANTIES, EXPRESS OR IMPLIED, INCLUDING, BUT NOT LIMITED TO, WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE, NON-INFRINGEMENT, OR TITLE; THAT THE CONTENTS OF THE DOCUMENT ARE SUITABLE FOR ANY PURPOSE; NOR THAT THE IMPLEMENTATION OF SUCH CONTENTS WILL NOT INFRINGE ANY THIRD PARTY PATENTS, COPYRIGHTS, TRADEMARKS OR OTHER RIGHTS.

THE COPYRIGHT HOLDERS AND THE ECLIPSE FOUNDATION WILL NOT BE LIABLE FOR ANY DIRECT, INDIRECT, SPECIAL OR CONSEQUENTIAL DAMAGES ARISING OUT OF ANY USE OF THE DOCUMENT OR THE PERFORMANCE OR IMPLEMENTATION OF THE CONTENTS THEREOF.

The name and trademarks of the copyright holders or the Eclipse Foundation may NOT be used in advertising or publicity pertaining to this document or its contents without specific, written prior permission. Title to copyright in this document will at all times remain with copyright holders.

Scope

Jakarta XML Web Services defines a means for implementing XML-Based Web Services based on Jakarta SOAP with Attachments and Jakarta Web Services Metadata.

Jakarta Web Services Metadata defines a programming model for Web Services in Java, use of metadata, a non-normative processing model for metadata annotated web service source files, runtime requirements for a container, and annotations used for WSDL, binding, and configuration.

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 de-facto 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. Jakarta XML RPC[7] added support for the WS-I Basic Profile 1.0[8] to improve interoperability between Jakarta XML RPC implementations and with services implemented using other technologies.

Jakarta Web Services Metadata defines the syntax and semantics of Java Web Service (JWS) metadata and default values and implementers are expected to provide tools that map the annotated Java classes onto a specific runtime environment.

Jakarta XML Web Services (this specification) is a follow-on to Jakarta XML RPC, extending it as described in the following sections.

Throughout the document, references to JAXB refer to the Jakarta XML Binding unless otherwise noted and references to JAX-WS refer to the Jakarta XML Web Services unless otherwise noted.

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. Jakarta XML Web Services relates to these specifications and standards as follows:

Jakarta Web Services Metadata
  • Define an annotated Java syntax for programming Web Service applications.

  • Provide a simplified model for Web Service development that facilitates and accelerates development.

  • Provide a syntax that is amenable to manipulation by tools.

  • Define a standard for to building and deploying Web Services without requiring knowledge and implementation of generalized APIs and deployment descriptors.

This specification addresses the need to simplify:

  • Development of server applications that conform both to basic SOAP and WSDL standards.

  • Building Web Services that can be deployed with the core Web Services APIs and existing Jakarta EE standards.

  • Separate control of public Web Service message contracts and private implementation signatures, because in practice public and private formats evolve on different schedules.

    Jakarta XML Binding

    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. Jakarta XML Web Services will delegate data binding-related tasks to the Jakarta XML Binding[39] specification that is being developed in parallel with Jakarta XML Web Services.
    Jakarta XML Binding[39] 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. Jakarta XML Web Services will allow full use of JAXB provided facilities including binding customization and optional schema validation.

  • JAX-WS 2.1 requires JAXB 2.1[11].

  • JAX-WS 2.2 requires JAXB 2.2[12].

  • JAX-WS 2.3 requires JAXB 2.3[13].

  • Jakarta XML Web Services 3.0 requires Jakarta XML Binding 3.0[39].

  • Jakarta XML Web Services 4.0 requires Jakarta XML Binding 4.0[39].

    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. Jakarta XML Web Services will add support for SOAP 1.2 whilst requiring continued support for SOAP 1.1.

    WSDL 2.0

    The W3C is expected to progress WSDL 2.0[14] to Recommendation during the lifetime of this JSR. Jakarta XML Web Services will add support for WSDL 2.0 whilst requiring continued support for WSDL 1.1.

The expert group decided against this goal for this release. We will look at adding support in a future revision of the Jakarta XML Web Services specification.

WS-I Basic Profile 1.1

Jakarta XML RPC 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 specificatoin and Jakarta XML Web Services will add support for the additional clarifications it provides.

A Metadata Facility for the Java Programming Language (JSR 175)

Jakarta XML Web Services will define the use of Java annotations[15] to simplify the most common development scenarios for both clients and servers.

Jakarta XML Web Services Metadata

Jakarta XML Web Services will align with and complement the annotations defined by Jakarta XML Web Services Metadata[16].

Jakarta Enterprise Web Services

The Jakarta Enterprise Web Services specification[17] defined jaxrpc-mapping-info deployment descriptor provides deployment time Java ⇔ WSDL mapping functionality. In conjunction with Jakarta Enterprise Web Services Metadata[16], Jakarta Enterprise Web Services will complement this mapping functionality with development time Java annotations that control Java ⇔ WSDL mapping.

Web Services Security (JSR 183)

Jakarta XML Web Services will align with and complement the security APIs defined by JSR 183[18].

Jakarta XML Web Services will improve support for document/message centric usage:

Asynchrony

Jakarta XML Web Services will add support for client side asynchronous operations.

Non-HTTP Transports

Jakarta XML Web Services will improve the separation between the XML message format and the underlying transport mechanism to simplify use of Jakarta XML Web Services with non-HTTP transports.

Message Access

Jakarta XML Web Services will simplify client and service access to the messages underlying an exchange.

Session Management

Jakarta XML RPC session management capabilities are tied to HTTP. Jakarta XML Web Services will add support for message based session management.

Jakarta XML Web Services will also address issues that have arisen with experience of implementing and using JAX-RPC 1.0:

Handlers

Jakarta XML Web Services 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

Jakarta XML Web Services will describe techniques and mechanisms to ease the burden on developers when creating new versions of existing services.

1.2. Non-Goals

The following are non-goals:

Backwards Compatibility of Binary Artifacts

Binary compatibility between Jakarta XML RPC and Jakarta XML Web Services implementation runtimes.

Pluggable data binding

Jakarta XML Web Services will defer data binding to Jakarta XML Binding[39]; 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 Jakarta XML Binding. However, Jakarta XML Web Services 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.

SOAP Encoding Support

Use of the SOAP encoding is essentially deprecated in the web services community, e.g., the WS-I Basic Profile[8] excludes SOAP encoding. Instead, literal usage is preferred, either in the RPC or document style.

SOAP 1.1 encoding is supported in JAX-RPC 1.0 and Jakarta XML RPC but its support in Jakarta XML Web Services runs counter to the goal of delegation of data binding to Jakarta XML Binding. Therefore Jakarta XML Web Services will make support for SOAP 1.1 encoding optional and defer description of it to Jakarta XML RPC.

Support for the SOAP 1.2 Encoding[4] is optional in SOAP 1.2 and Jakarta XML Web Services will not add support for SOAP 1.2 encoding.

Backwards Compatibility of Generated Artifacts

JAX-RPC 1.0 and JAXB 1.0 bind XML to Java in different ways. Generating source code that works with unmodified Jakarta XML RPC client source code is not a goal.

Support for Java versions prior to Java SE 5.0

Jakarta XML Web Services relies on many of the Java language features added in Java SE 5.0. It is not a goal to support Jakarta XML Web Services on Java versions prior to Java SE 5.0.

Service Registration and Discovery

It is not a goal of Jakarta XML Web Services to describe registration and discovery of services via UDDI or ebXML RR. This capability is provided independently by Jakarta XML Registries[19].

1.3. Requirements

1.3.1. Relationship To Jakarta XML Binding

Jakarta XML Web Services specification describes the WSDL ⇔ Java mapping, but data binding is delegated to Jakarta XML Binding[39]. The specification must clearly designate where Jakarta XML Binding rules apply to the WSDL ⇔ Java mapping without reproducing those rules and must describe how Jakarta XML Binding capabilities (e.g., the Jakarta XML Binding binding language) are incorporated into Jakarta XML Web Services. Jakarta XML Web Services is required to be able to influence the Jakarta XML Binding binding, e.g., to avoid name collisions and to be able to control schema validation on serialization and deserialization.

1.3.2. Standardized WSDL Mapping

WSDL is the de-facto service description language for XML Web Services. The specification must specify a standard WSDL ⇔ Java mapping. The following versions of WSDL must be supported:

  • WSDL 1.1[5] as clarified by the WS-I Basic Profile(Ballinger, Ehnebuske, Gudgin, et al. 2004; Ballinger, Ehnebuske, Ferris, et al. 2004)

The standardized WSDL mapping will describe the default WSDL ⇔ Java mapping. The default mapping may be overridden using customizations as described below.

1.3.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 Jakarta XML Binding[39] and Jakarta XML Web Services Metadata[16] specifications, 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. The annotations will support mapping to WSDL 1.1.

WSDL Annotations

In conjunction with Jakarta XML Binding[39] and Jakarta XML Web Services Metadata[16] specifications, 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 annotations will support mapping from WSDL 1.1.

The specification must describe the precedence rules governing combinations of the customization methods.

1.3.4. Standardized Protocol Bindings

The specification must describe standard bindings to the following protocols:

The specification must not prevent non-standard bindings to other protocols.

1.3.5. Standardized Transport Bindings

The specification must describe standard bindings to the following protocols:

The specification must not prevent non-standard bindings to other transports.

1.3.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 Jakarta SOAP with Attachments API.

Handler Context

The framework will describe a mechanism for communicating properties between handlers and the associated service clients and service endpoint implementations.

Unified Response and Fault Handling

The handleResponse and handleFault methods will be unified and the the declarative model for handlers will be improved.

1.3.7. Versioning and Evolution

The specification must describe techniques and mechanisms to support versioning of service endpoint interfaces. The facilities must allow new versions of an interface to be deployed whilst maintaining compatibility for existing clients.

1.3.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 Jakarta XML Web Services. Both forms of invocation will support a user configurable timeout period.

1.3.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.

HTTP based sessions

The session management mechanism must support HTTP cookies and URL rewriting.

SOAP based sessions

The session management mechanism must support SOAP based session information.

1.4. Use Cases

1.4.1. Handler Framework

1.4.1.1. Reliable Messaging Support

A developer wishes to add support for a reliable messaging SOAP feature to an existing service endpoint. The support takes the form of a Jakarta XML Web Services handler.

1.4.1.2. Message Logging

A developer wishes to log incoming and outgoing messages for later analysis, e.g., checking messages using the WS-I testing tools.

1.4.1.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.

1.5. Conventions

The keywords 'MUST', 'MUST NOT', 'REQUIRED', 'SHALL', 'SHALL NOT', 'SHOULD', 'SHOULD NOT', 'RECOMMENDED', 'MAY', and 'OPTIONAL' in this document are to be interpreted as described in RFC 2119[22].

For convenience, conformance requirements are called out from the main text as follows:

Conformance (Example): Implementations MUST do something.

A list of all such conformance requirements can be found in appendix [confreqs].

Java code and XML fragments are formatted as shown in figure 1, “Example Java Code”:

1. Example Java Code
1
2
3
4
5
6
7
package com.example.hello;

public class Hello {
    public static void main(String args[]) {
        System.out.println("Hello World");
    }
}

Non-normative notes are formatted as shown below.

Note

This is a note.

This specification uses a number of namespace prefixes throughout; they are listed in Table 1, “Prefixes and Namespaces used in this specification.”. Note that the choice of any namespace prefix is arbitrary and not semantically significant (see XML Infoset[23]).

Table 1. Prefixes and Namespaces used in this specification.
Prefix Namespace Notes

env

http://www.w3.org/2003/05/soap-envelope

A normative XML Schema[24][25] document for the http://www.w3.org/2003/05/soap-envelope namespace can be found at http://www.w3.org/2003/05/soap-envelope.

xsd

http://www.w3.org/2001/XMLSchema

The namespace of the XML schema[24][25] specification

wsdl

http://schemas.xmlsoap.org/wsdl/

The namespace of the WSDL schema[5]

soap

http://schemas.xmlsoap.org/wsdl/soap/

The namespace of the WSDL SOAP binding schema[24][25]

jaxb

https://jakarta.ee/xml/ns/jaxb

The namespace of the Jakarta XML Binding[9] specification

jaxws

https://jakarta.ee/xml/ns/jaxws

The namespace of the Jakarta XML Web Services specification

wsa

http://www.w3.org/2005/08/addressing

The namespace of the WS-Addressing 1.0[26] schema

wsam

http://www.w3.org/2007/05/addressing/metadata

The namespace of the WS-Addressing 1.0 - Metadata[27] schema

wsp

http://www.w3.org/ns/ws-policy

The namespace of the Web Services Policy 1.5 - Framework[28] schema

Namespace names of the general form 'http://example.org/…​' and 'http://example.com/…​' represent application or context-dependent URIs (see RFC 2396[21]).

All parts of this specification are normative, with the exception of examples, notes and sections explicitly marked as 'Non-Normative'.

1.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, Inc.)
Jim Frost (Art Technology Group Inc)
Alastair Harwood (Cap Gemini)
Marc Hadley (Sun Microsystems, Inc.)
Kevin R. Jones (Developmentor)
Lukas Jungmann (Oracle)
Anish Karmarkar (Oracle)
Toshiyuki Kimura (NTT Data Corp)
Jim Knutson (IBM)
Doug Kohlert (Sun Microsystems, Inc)
Daniel Kulp (IONA Technologies PLC)
Sunil Kunisetty (Oracle)
Changshin Lee (Tmax Soft, Inc)
Carlo Marcoli (Cap Gemini)
Srividya Natarajan (Nokia Corporation)
Sanjay Patil (SAP AG)
Greg Pavlik (Oracle)
Bjarne Rasmussen (Novell, Inc)
Sebastien Sahuc (Intalio, Inc.)
Rahul Sharma (Motorola)
Rajiv Shivane (Pramati Technologies)
Richard Sitze (IBM)
Dennis M. Sosnoski (Sosnoski Software)
Christopher St. John (WebMethods Corporation)
Mark Stewart (ATG)
Neal Yin (BEA Systems)
Brian Zotter (BEA Systems)
Nicholas L Gallardo (IBM)
Alessio Soldano (Red Hat)

1.6.1. JWS Expert Group Members

The following people have been part of the original JWS Specification Expert Group:

Alexander Aptus (Togethersoft Corporation)
John Bossons
Charles Campbell
Shih-Chang Chen (Oracle)
Alan Davies (SeeBeyond Technology Corp)
Stuart Edmondston (BEA Systems)
John Harby
RajivMordani (Sun Microsystems)
Michael Morton (IBM)
Simon Nash (IBM)
Mark Pollack
Srividya Rajagopalan (Nokia)
Krishna Sankar (Cisco Systems)
Manfred Schneider (SAP AG)
John Schneider (BEA Systems)
Kalyan Seshu (Paramati Technologies)
Rahul Sharma (Motorola)
Michael Shenfield (Research In Motion)
Evan Simeone (PalmSource)
Brian Zotter (BEA Systems)

1.7. Acknowledgements

Robert Bissett, Arun Gupta, Graham Hamilton, Mark Hapner, Jitendra Kotamraju, Vivek Pandey, Santiago Pericas-Geertsen, Eduardo Pelegri-Llopart, Rama Pulavarthi, Paul Sandoz, Bill Shannon, and Kathy Walsh (all from Sun Microsystems) have provided invaluable technical input to the JAX-WS 2.0 specification.

Roberto Chinnici, Marc Hadley, Kohsuke Kawaguchi, and Bill Shannon (all from Sun Microsystems) have provided invaluable technical input to the JAX-WS 2.2 specification. I would like to thank Rama Pulavarthi for his contributions to the 2.2 reference implementation and to the specification. JAX-WS TCK team (Arthur Frechette, Alan Frechette) and SQE team (Jonathan Benoit) assisted the conformance testing of the 2.2 specification.

Manoj Cheenath (BEA Systems), Don Ferguson (BEA Systems), Chris Fry (BEA Systems), Neal Yin (BEA Systems), Beverley Talbott (BEA Systems), Matt Mihic, Jim Trezzo, Doug Kohlert (Sun Microsystems), Jitendra Kotamraju (Sun Microsystems), and Rama Pulavarthi (Sun Microsystems) have all provided valuable technical input to the JWS specification.

2. WSDL 1.1 to Java Mapping

This chapter describes the mapping from WSDL 1.1 to Java. This mapping is used when generating web service interfaces for clients and endpoints from a WSDL 1.1 description.

Conformance (WSDL 1.1 support): Implementations MUST support mapping WSDL 1.1 to Java.

The following sections describe the default mapping from each WSDL 1.1 construct to the equivalent Java construct. In WSDL 1.1, the separation between the abstract port type definition and the binding to a protocol is not complete. Bindings impact the mapping between WSDL elements used in the abstract port type definition and Java method parameters. Section 2.6, “Binding” describes binding dependent mappings.

An application MAY customize the mapping using embedded binding declarations (see Section 9.3, “Embedded Binding Declarations”) or an external binding file (see Section 9.4, “External Binding File”).

Conformance (Customization required): Implementations MUST support customization of the WSDL 1.1 to Java mapping using the Jakarta XML Web Services binding language defined in Chapter 9, Customizations.

In order to enable annotations to be used at runtime for method dispatching and marshalling, this specification requires generated Java classes and interfaces to be annotated with the Web service annotations described in Section 8.11, “Annotations Defined by Jakarta XML Web Services Metadata”. 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, as well as the customizations embedded in them and those specified via any external binding files.

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.

2.1. Definitions

A WSDL document has a root wsdl:definitions element. A wsdl:definitions element and its associated targetNamespace attribute is mapped to a Java package. Jakarta XML Binding[39] (see appendix D) defines a standard mapping from a namespace URI to a Java package name. By default, this algorithm is used to map the value of a wsdl:definitions element’s targetNamespace attribute to a Java package name.

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 Jakarta XML Binding[39].

An application MAY customize this mapping using the jaxws:package binding declaration defined in Section 9.7.1, “Definitions”.

No specific authoring style is required for the input WSDL document; implementations should support WSDL that uses the WSDL and XML Schema import directives.

Conformance (WSDL and XML Schema import directives): Implementations MUST support the WS-I Basic Profile 1.1[20] defined mechanisms (See R2001, R2002, and R2003) for use of WSDL and XML Schema import directives.

2.1.1. Extensibility

WSDL 1.1 allows extension elements and attributes to be added to many of its constructs. Jakarta XML Web Services specification specifies the mapping to Java of the extensibility elements and attributes defined for the SOAP and MIME bindings. Jakarta XML Web Services 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. Future versions of Jakarta XML Web Services might add additional support for standard extensions as these become available.

Conformance (Optional WSDL extensions): An implementation MAY support mapping of additional WSDL extensibility elements and attributes not described in Jakarta XML Web Services.

Note that such support may limit interoperability and application portability.

2.2. Port Type

A WSDL port type is a named set of abstract operation definitions. A wsdl:portType element is mapped to a Java interface in the package mapped from the wsdl:definitions element (see Section 2.1, “Definitions” for a description of wsdl:definitions mapping). A Java interface mapped from a wsdl:portType is called a Service Endpoint Interface or SEI for short.

Conformance (SEI naming): In the absence of customizations, 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.8, “XML Names”.

An application MAY customize this mapping using the jaxws:class binding declaration defined in Section 9.7.2, “PortType”.

Conformance (jakarta.jws.WebService required): A mapped SEI MUST be annotated with a jakarta.jws.WebService annotation.

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 Jakarta XML Web Services. The jakarta.xml.bind.XmlSeeAlso annotation from Jakarta XML Binding is used on the generated SEI to specify any additional types from the WSDL.

Conformance (jakarta.xml.bind.XmlSeeAlso required): An SEI generated from a WSDL that defines types not directly referenced by the Port MUST contain the jakarta.xml.bind.XmlSeeAlso annotation with all of the additional types referenced either directly or indirectly.

2. Directly and indirectly @XmlSeeAlso annotated SEI
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;
public class A { ... }

package example1;
public class B extends A { ... }

package example2;
public class C extends A { ... }

// Directly annotated SEI with classes B and C
@WebService
@XmlSeeAlso({B.class, C.class})
public interface MyService {
    public A echo(A a);
}

// Indirectly annotated SEI using generated JAXB ObjectFatories
@XmlSeeAlso({example1.ObjectFactory.class, example2.ObjectFactory.class})
public interface MyService {
    public A echo(A a);
}

Figure 2, “Directly and indirectly @XmlSeeAlso annotated SEI” shows how an SEI can be annotated with jakarta.xml.bind.XmlSeeAlso. This figures shows some of the types that may have been created while importing a WSDL and the different approaches to annotating the SEI.

An SEI contains Java methods mapped from the wsdl:operation child elements of the corresponding wsdl:portType, see Section 2.3, “Operation” for further details on wsdl:operation mapping. WSDL 1.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.

Conformance (Method naming): In the absence of customizations, 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.8, “XML Names”.

An application MAY customize this mapping using the jaxws:method binding declaration defined in Section 9.7.3, “PortType Operation”.

Conformance (jakarta.jws.WebMethod required): A mapped Java method MUST be annotated with a jakarta.jws.WebMethod annotation. The annotation MAY be omitted if all its properties would have the default values.

The WS-I Basic Profile[20] 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 interfaces with overloaded methods. However, for backwards compatibility, Jakarta XML Web Services supports operation name overloading provided the overloading does not cause conflicts (as specified in the Java Language Specification[29]) in the mapped Java service endpoint interface declaration.

Conformance (Transmission primitive support): An implementation MUST support mapping of operations that use the one-way and request-response transmission primitives.

Conformance (Using jakarta.jws.OneWay): A Java method mapped from a one-way operation MUST be annotated with a jakarta.jws.OneWay annotation.

Mapping of notification and solicit-response operations is out of scope.

2.3.1. Message and Part

Each wsdl:operation refers to one or more wsdl:message elements via child wsdl:input, wsdl:output, and wsdl:fault elements that describe the input, output, and fault messages for the operation respectively. Each operation can specify one input message, zero or one output message, and zero or more fault messages.

Fault messages are mapped to application specific exceptions (see Section 2.5, “Fault”). The contents of input and output messages are mapped to Java method parameters using two different styles: non-wrapper style and wrapper style. The two mapping styles are described in the following subsections. Note that the binding of a port type can affect the mapping of that port type to Java, see Section 2.6, “Binding” for details.

Conformance (Using jakarta.jws.SOAPBinding): An SEI mapped from a port type that is bound using the WSDL SOAP binding MUST be annotated with a jakarta.jws.SOAPBinding annotation describing the choice of style, encoding and parameter style. The annotation MAY be omitted if all its properties would have the default values (i.e. document/literal/wrapped).

Conformance (Using jakarta.jws.WebParam): Generated Java method parameters MUST be annotated with a jakarta.jws.WebParam annotation. If the style is rpc or if the style is Document and the parameter style is BARE then the partName element of jakarta.jws.WebParam MUST refer to the wsdl:part name of the parameter.

Conformance (Using jakarta.jws.WebResult): Generated Java methods MUST be annotated with a jakarta.jws.WebResult annotation. If the style is rpc or if the style is Document and the parameter style is BARE then the partName element of jakarta.jws.WebResult MUST refer to the wsdl:part name of the parameter. The annotation MAY be omitted if all its properties would have the default values.

WSDL description may have wsam:Action attribute on wsdl:input, wsdl:output, wsdl:fault elements in a wsdl:operation. This wsam:Action attribute is used to explicitly define the value of the WS-Addressing Action header and this needs to be mapped on to the corresponding Java method.

Conformance (Generating @Action): Generated Java Methods MUST be annotated with @Action and @FaultAction annotations for the corresponding wsdl:input, wsdl:output and wsdl:fault messages that contain wsam:Action attributes

Conformance (Generating @Action input): If a wsdl:input element contains a wsam:Action attribute, the value of the attribute MUST be set to the input element of @Action

Conformance (Generating @Action output): If a wsdl:output element contains a wsam:Action attribute, the value of the attribute MUST be set to the output element of @Action

Conformance (Generating @Action fault): If a wsdl:fault element contains a wsam:Action attribute, the value of the attribute MUST be set to the value element of @FaultAction. The className element of @FaultAction MUST be the exception class name associated with the wsdl:fault

Figure 3, “Mapping of wsam:Action metadata” shows an example of the wsam:Action mapping described above.

3. Mapping of wsam:Action metadata
1
2
3
4
5
6
7
8
9
10
11
12
<operation name="getPrice">
  <input message="tns:getPrice" />
  <output message="tns:getPriceResponse" wsam:Action="outAction"/>
  <fault name="InvalidTickerException"
         message="tns:InvalidTickerException" wsam:Action="faultAction"/>
</operation>

// the mapped java method
@Action(output = "outAction", fault = {
        @FaultAction(className=InvalidTickerException.class,
                     value="faultAction")})
float getPrice(String ticker) throws InvalidTickerException;

When generating an SEI from WSDL and XML schema, occasionally ambiguities occur on what XML infoset should be used to represent a method’s return value or parameters. In order to remove these ambiguities, Jakarta XML Binding 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. A Jakarta XML Binding 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. If the default XML infoset for the return type or parameters correctly represents the XML infoset, no Jakarta XML Binding annotations are needed.

Conformance (use of Jakarta XML Binding annotations): An SEI method MUST contain the appropriate Jakarta XML Binding annotations to assure that the proper XML infoset is used when marshalling/unmarshalling the return type. Parameters of an SEI method MUST contain the appropriate Jakarta XML Binding annotations to assure that the proper XML infoset is used when marshalling/unmarshalling the parameters of the method. The set of Jakarta XML Binding annotations that MUST be supported are: jakarta.xml.bind.annotation.XmlAttachementRef, jakarta.xml.bind.annotation.XmlList, jakarta.xml.bind.XmlMimeType and jakarta.xml.bind.annotation.adapters.XmlJavaTypeAdapter.

2.3.1.1. Non-wrapper Style

A wsdl:message is composed of zero or more wsdl:part elements. Message parts are classified as follows:

in

The message part is present only in the operation’s input message.

out

The message part is present only in the operation’s output message.

in/out

The message part is present in both the operation’s input message and output message.

Two parts are considered equal if they have the same values for their name attribute and they reference the same global element or type. Using non-wrapper style, message parts are mapped to Java parameters according to their classification as follows:

in

The message part is mapped to a method parameter.

out

The message part is mapped to a method parameter using a holder class (see Section 2.3.3, “Holder Class”) or is mapped to the method return type.

in/out

The message part is mapped to a method parameter using a holder class.

Conformance (Non-wrapped parameter naming): In the absence of any customizations, 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 Section 2.8, “XML Names” and Section 2.8.1, “Name Collisions”.

An application MAY customize this mapping using the jaxws:parameter binding declaration defined in Section 9.7.3, “PortType Operation”.

Section 2.3.2, “Parameter Order and Return Type” 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.

2.3.1.2. Wrapper Style

A WSDL operation qualifies for wrapper style mapping only if the following criteria are met:

  1. The operation’s input and output messages (if present) each contain only a single part

  2. The input message part refers to a global element declaration whose localname is equal to the operation name

  3. The output message (if present) part refers to a global element declaration

  4. 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

  5. The wrapper elements only contain child elements, they MUST not contain other structures such as wildcards (element or attribute), xsd:choice, substitution groups (element references are not permitted) or attributes; furthermore, they MUST not be nillable.

Conformance (Default mapping mode): Operations that do not meet the criteria above MUST be mapped using non-wrapper style.

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.

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 9.7.3, “PortType Operation”).

Using wrapper style, the child elements of the wrapper element (henceforth called wrapper children) are mapped to Java parameters, wrapper children are classified as follows:

in

The wrapper child is only present in the input message part’s wrapper element.

out

The wrapper child is only present in the output message part’s wrapper element.

in/out

The wrapper child is present in both the input and output message part’s wrapper element.

Two wrapper children are considered equal if they have the same local name, the same XML schema type and the same Java type after mapping (see Section 2.4, “Types” for XML Schema to Java type mapping rules). The mapping depends on the classification of the wrapper child as follows:

in

The wrapper child is mapped to a method parameter.

out

The wrapper child is mapped to a method parameter using a holder class (see Section 2.3.3, “Holder Class”) or is mapped to the method return value.

in/out

The wrapper child is mapped to a method parameter using a holder class.

Conformance (Wrapped parameter naming): In the absence of customization, 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 Section 2.8, “XML Names” and Section 2.8.1, “Name Collisions”.

An application MAY customize this mapping using the jaxws:parameter binding declaration defined in Section 9.7.3, “PortType Operation”.

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, see Section 2.3.2, “Parameter Order and Return Type”, then this is reported as an error and requires developer intervention to correct, either by disabling wrapper style mapping, modifying the source WSDL or by specifying a customized parameter name mapping.

Conformance (Using jakarta.xml.ws.RequestWrapper): If wrapper style is used, generated Java methods MUST be annotated with a jakarta.xml.ws.RequestWrapper annotation. The annotation MAY be omitted if all its properties would have the default values.

Conformance (Using jakarta.xml.ws.ResponseWrapper): If wrapper style is used, generated Java methods MUST be annotated with a jakarta.xml.ws.ResponseWrapper annotation. The annotation MAY be omitted if all its properties would have the default values.

2.3.1.3. Example

Figure 4, “Wrapper and non-wrapper mapping styles” shows a WSDL extract and the Java method that results from using wrapper and non-wrapper mapping styles. For readability, annotations are omitted.

4. Wrapper and non-wrapper mapping styles
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 -->
<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);

// wrapper style mapping
void setLastTradePrice(String tickerSymbol, float lastTradePrice);

2.3.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. If the value of a wsdl:part element’s name attribute is present in the parameterOrder attribute then the part is listed, otherwise it is unlisted.

    Note

    R2305 in WS-I Basic Profile 1.1[20] requires that if the parameterOrder attribute is present then at most one part may be unlisted. However, the algorithm outlined in this section supports WSDLs that do not conform with this requirement.

  • Parameters that are mapped from message parts are either listed or unlisted. Parameters that are mapped from listed parts are listed; parameters that are mapped from unlisted parts are unlisted.

  • Parameters that are mapped from wrapper children (wrapper style mapping only) are unlisted.

  • 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, parts from other messages (see e.g. Section 2.6.2.1, “Header Binding Extension”) do not qualify. If there is a single unlisted out part in the abstract output message then it forms the method return type, otherwise the return type is void.

    Wrapper style mapping

    If there is a single out wrapper child then it forms the method return type, if there is an out wrapper child with a local name of "return" then it forms the method return type, otherwise the return type is void.

  • Unlisted parameters that do not form the return type follow the listed parameters in the following order:

    1. Parameters mapped from in and in/out parts appear in the same order the corresponding parts appear in the input message.

    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.

    3. Parameters mapped from out parts appear in the same order the corresponding parts appear in the output message.

    4. Parameters mapped from out wrapper children (wrapper style mapping only) appear in the same order as the corresponding wrapper children appear in the wrapper.

2.3.3. Holder Class

Holder classes are used to support out and in/out parameters in mapped method signatures. They provide a mutable wrapper for otherwise immutable object references. Jakarta XML Web Services defines a generic holder class (jakarta.xml.ws.Holder<T>) that can be used for any Java class.

Parameters whose XML data type would normally be mapped to a Java primitive type (e.g., 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. E.g., an out or in/out parameter whose XML data type would normally be mapped to a Java int is instead mapped to Holder<java.lang.Integer>.

Conformance (Use of jakarta.xml.ws.Holder): Implementations MUST map out and in/out method parameters using jakarta.xml.ws.Holder<T>, with the exception of a out part that has been mapped to the method’s return type.

2.3.4. Asynchrony

In addition to the synchronous mapping of wsdl:operation described above, a client side asynchronous mapping is also supported. 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.

Conformance (Asynchronous mapping required): An implementation MUST support the asynchronous mapping.

Conformance (Asynchronous mapping option): An implementation MUST support use of the jaxws:enableAsyncMapping binding declaration defined in Section 9.7.3, “PortType Operation” to enable and disable the asynchronous mapping.

Editors Note

Jakarta XML Web Services Metadata currently does not define annotations that can be used to mark a method as being asynchronous.

2.3.4.1. Standard Asynchronous Interfaces

The following standard interfaces are used in the asynchronous operation mapping:

jakarta.xml.ws.Response

A generic interface that is used to group the results of a method invocation with the response context. Response extends Future<T> to provide asynchronous result polling capabilities.

jakarta.xml.ws.AsyncHandler

A generic interface that clients implement to receive results in an asynchronous callback.

2.3.4.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. See below for further details on ResponseBean.

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. The object returned from Future<?>.get() has no standard type. Client code should not attempt to cast the object to any particular type as this will result in non-portable behavior.

Conformance (Asynchronous method naming): In the absence of customizations, 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 Section 2.8, “XML Names” and Section 2.8.1, “Name Collisions”.

Conformance (Asynchronous parameter naming): The name of the method parameter for the callback handler MUST be "asyncHandler". Parameter name collisions require user intervention to correct, see Section 2.8.1, “Name Collisions”.

An application MAY customize this mapping using the jaxws:method binding declaration defined in Section 9.7.3, “PortType Operation”.

Conformance (Failed method invocation): If there is any error prior to invocation of the operation, an implementation MUST throw a WebServiceException[1].

2.3.4.3. Message and Part

The asynchronous mapping supports both wrapper and non-wrapper mapping styles, 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.1, “Message and Part”.

out

The part or wrapper child is mapped to a property of the response bean (see below).

in/out

The part or wrapper child is mapped to a method parameter (no holder class) and to a property of the response bean.

2.3.4.4. Response Bean

A response bean is a mapping of an operation’s output message, it contains properties for each out and in/out message part or wrapper child.

Conformance (Response bean naming): In the absence of customizations, 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 Section 2.8, “XML Names” and Section 2.8.1, “Name Collisions”.

A response bean is mapped from a global element declaration following the rules described in Section 2.4, “Types”. 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.

  • Synthesize a global element declaration of a complex type defined using the xsd:sequence compositor. 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.

    • 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. In this case, if the property is a Java primitive type then it is boxed using the Java wrapper type (e.g. int to Integer) to enable its use with Response.

2.3.4.5. Faults

Mapping of WSDL faults to service specific exceptions is identical for both asynchronous and synchronous cases, Section 2.5, “Fault” describes the mapping. However, mapped asynchronous methods do not throw service specific exceptions directly. Instead a java.util.concurrent.ExecutionException is thrown when a client attempts to retrieve the results of an asynchronous method invocation via the Response.get method.

Conformance (Asynchronous fault reporting): A WSDL fault that occurs during execution of an asynchronous method invocation MUST be mapped to a java.util.concurrent.ExecutionException thrown when the client calls Response.get.

Response is a static generic interface whose get method cannot throw service specific exceptions. Instead of throwing a service specific exception, a Response instance throws an ExecutionException whose cause is set to an instance of the service specific exception mapped from the corresponding WSDL fault.

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, if there is one, otherwise the ProtocolException mapped from the WSDL fault (see Section 6.4, “Exceptions”).

2.3.4.6. Mapping Examples

Figure 5, “Asynchronous operation mapping” shows an example of the asynchronous operation mapping. 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.

5. Asynchronous operation 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
<!-- 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);
}

// asynchronous mapping
@WebService
public interface StockQuote {
    float getPrice(String ticker);
    Response<Float> getPriceAsync(String ticker);
    Future<?> getPriceAsync(String ticker, AsyncHandler<Float>);
}
2.3.4.7. Usage Examples
  • Synchronous use.

Service service = ...;
StockQuote quoteService = (StockQuote) service.getPort(portName);
Float quote = quoteService.getPrice(ticker);
  • Asynchronous polling use.

Service service = ...;
StockQuote quoteService = (StockQuote) service.getPort(portName);
Response<Float> response = quoteService.getPriceAsync(ticker);
while (!response.isDone()) {
    // do something while we wait
}
Float quote = response.get();
  • Asynchronous callback use.

class MyPriceHandler implements AsyncHandler<Float> {
    ...
    public void handleResponse(Response<Float> response) {

2.4. Types

Mapping of XML Schema types to Java is described by the Jakarta XML Binding specification[39]. The contents of a wsdl:types section is passed to Jakarta XML Binding along with any additional type or element declarations (e.g., see Section 2.3.4, “Asynchrony”) required to map other WSDL constructs to Java. E.g., Section 2.3.4, “Asynchrony” defines an algorithm for synthesizing additional global element declarations to provide a mapping from WSDL operations to asynchronous Java method signatures.

Jakarta XML Binding supports mapping XML types to either Java interfaces or classes. By default Jakarta XML Web Services uses the class based mapping of Jakarta XML Binding but also allows use of the interface based mapping.

Conformance (Jakarta XML Binding class mapping): In the absence of user customizations, an implementation MUST use the Jakarta XML Binding class based mapping with generateValueClass set to true and generateElementClass set to false when mapping WSDL types to Java.

Conformance (Jakarta XML Binding customization use): An implementation MUST support use of Jakarta XML Binding customizations during mapping as detailed in Section 9.5, “Using Jakarta XML Binding Binding Declarations”.

Conformance (Jakarta XML Binding customization clash): To avoid clashes, if a user customizes the mapping, an implementation MUST NOT add the default class based mapping customizations.

In addition, for ease of use, Jakarta XML Web Services strips any JAXBElement<T> wrapper off the type of a method parameter if the normal Jakarta XML Binding mapping would result in one[2]. E.g. a parameter that Jakarta XML Binding would map to JAXBElement<Integer> is instead be mapped to Integer.

Jakarta XML Binding provides support for the SOAP MTOM[30] /XOP[31] mechanism for optimizing transmission of binary data types. Jakarta XML Web Services provides the MIME processing required to enable Jakarta XML Binding to serialize and deserialize MIME based MTOM/XOP packages. The contract between Jakarta XML Binding and an MTOM/XOP package processor is defined by the jakarta.xml.bind.AttachmentMarshaller and jakarta.xml.bind.AttachmentUnmarshaller classes. A Jakarta XML Web Services implementation can plug into it by registering its own AttachmentMarshaller and AttachmentUnmarshaller at runtime using the setAttachmentUnmarshaller method of jakarta.xml.bind.Unmarshaller (resp. the setAttachmentMarshaller method of jakarta.xml.bind.Marshaller).

2.4.1. W3CEndpointReference

Jakarta XML Binding by default does not map wsa:EndpointReference to the jakarta.xml.ws.wsaddressing.W3CEndpointReference class. However, for Jakarta XML Web Services developers to fully utilize the use of a wsa:EndpointReference, Jakarta XML Web Services implementations MUST map the wsa:EndpointReference and its subtypes to javax.ws.xml.ws.W3CEndpointReference by default. Jakarta XML Binding provides a standard customization that can be used to cause this mapping. Implementations may provide a way to map these types differently.

Conformance (jakarta.xml.ws.wsaddressing.W3CEndpointReference): Any schema element of the type wsa:EndpointReference or its subtypes MUST be mapped to jakarta.xml.ws.wsaddressing.W3CEndpointReference by default.

2.5. Fault

A wsdl:fault element is mapped to a Java exception.

Conformance (jakarta.xml.ws.WebFault required): A mapped exception MUST be annotated with a jakarta.xml.ws.WebFault annotation.

Conformance (Exception naming): In the absence of customizations, 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 Section 2.8, “XML Names” and Section 2.8.1, “Name Collisions”.

An application MAY customize this mapping using the jaxws:class binding declaration defined in Section 9.7.4, “PortType Fault Message”.

Multiple operations within the same service can define equivalent faults. Faults defined within the same service are equivalent if the values of their message attributes are equal.

Conformance (Fault equivalence): An implementation MUST map equivalent faults within a service to a single Java exception class.

A wsdl:fault element refers to a wsdl:message that contains a single part. The global element declaration[3] referred to by that part is mapped to a Java bean, henceforth called a fault bean, using the mapping described in Section 2.4, “Types”. An implementation generates a wrapper exception class that extends java.lang.Exception and contains the following methods:

WrapperException(String message, 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.

WrapperException(String message, FaultBean faultInfo, 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. The last argument, cause, may be used to convey protocol specific fault information, see Section 6.4.1, “Protocol Specific Exception Handling”.

FaultBean getFaultInfo()

Getter to obtain the fault information, where FaultBean is replaced by the name of the generated fault bean.

The WrapperException class is annotated using the WebFault annotation (see Section 8.2, “jakarta.xml.ws.WebFault”) to capture the local and namespace name of the global element mapped to the 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.

Conformance (Fault equivalence): At runtime an implementation MAY map a serialized fault into any equivalent Java exception.

2.5.1. Example

Figure 6, “Fault mapping” shows an example of the WSDL fault mapping described above.

6. Fault 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
<!-- WSDL extract -->
<types>
  <xsd:schema targetNamespace="...">
    <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", targetNamespace="...")
class OperationException extends Exception {
    OperationException(String message, FaultDetail faultInfo) {...}
    OperationException(String message, FaultDetail faultInfo, Throwable cause) {...}
    FaultDetail getFaultInfo() {...}
}

2.6. Binding

The mapping from WSDL 1.1 to Java is based on the abstract description of a wsdl:portType and its associated operations. However, 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.1 protocol bindings.

Conformance (Required WSDL extensions): An implementation MUST support mapping of the WSDL 1.1 specified extension elements for the WSDL SOAP and MIME bindings.

2.6.1. General Considerations

R2209 in WS-I Simple SOAP Binding Profile 1.1[32] recommends that all parts of a message be bound but does not require it.

Conformance (Unbound message parts): To preserve the protocol independence of mapped operations, an implementation MUST NOT ignore unbound message parts when mapping from WSDL 1.1 to Java. 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.

2.6.2. SOAP Binding

This section describes changes to the WSDL 1.1 to Java mapping that may result from use of certain SOAP binding extensions.

2.6.2.1. Header Binding Extension

A soap:header element may be used to bind a part from a message to a SOAP header. As clarified by R2208 in WS-I Basic Profile 1.1[20], 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.3, “Operation”. Such a part is always mapped using the non-wrapper style.

  • 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. When mapped to a parameter, the part is treated as an additional unlisted part for the purposes of the mapping described in Section 2.3, “Operation”. This additional part does not affect eligibility for wrapper style mapping of the message bound by the soap:body (see Section 2.3.1, “Message and Part”); 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.0[8]. 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.

Conformance (Duplicate headers in binding): When mapping, 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.

Conformance (Duplicate headers in message): An implementation MUST generate a runtime error if, during unmarshalling, there is more than one instance of a header whose qualified name is mapped to a method parameter.

2.6.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. The WS-I Attachments Profile[33] describes two separate attachment mechanisms, both based on use of the WSDL 1.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.

mime:content

A binding construct that may be used to bind a message part to an attachment.

Jakarta XML Binding[39] describes the mapping from the WS-I defined wsiap:swaref schema type to Java and, since Jakarta XML Web Services inherits this capability, it is not discussed further here. Use of the mime:content construct is outside the scope of Jakarta XML Binding mapping and the following subsection describes changes to the WSDL 1.1 to Java mapping that results from its use.

2.6.3.1. mime:content

Message parts are mapped to method parameters as described in Section 2.3, “Operation” regardless of whether the part is bound to the SOAP message or to an attachment. Jakarta XML Binding rules are used to determine the Java type of message parts based on the XML schema type referenced by the wsdl:part. However, 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 Jakarta XML Binding mapping. This use of additional metadata in mime:content elements is disabled by default for WSDL to Java mapping, but can be enabled using jaxws:enableMIMEContent customization (Section 9.7.5, “Binding”).

Conformance (Use of MIME type information): An implementation MUST support using the jaxws:enableMIMEContent binding declaration defined in Section 9.7.5, “Binding” to enable or disable the use of the additional metadata in mime:content elements when mapping from WSDL to Java.

Jakarta XML Binding defines a mapping between MIME types and Java types. When a part is bound using one or more mime:content elements[4] and use of the additional metadata is enabled then the Jakarta XML Binding mapping is customized to use the most specific type allowed by the set of MIME types described for the part in the binding. 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. Please refer to appendix H in the Jakarta XML Binding specification [39] for details of the type mapping.

The part belongs to the message bound by the soap:body then it is mapped to a method parameter as described in Section 2.3, “Operation”. Such a part is always mapped using the non-wrapper style.

Parts bound to MIME using the mime:content WSDL extension are mapped as described in Section 2.3, “Operation”. These parts are mapped using the non-wrapper style.

Figure 7, “Use of mime:content metadata” shows an example WSDL and two mapped interfaces: one without using the mime:content metadata, the other using the additional metadata to narrow the binding. Note that in the latter the type of the claimPhoto method parameter is Image rather than the default byte[].

7. Use of mime:content metadata
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="..."/>
    <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, byte claimPhoto[]);
}

// Mapped Java interface using mime:content metadata
@WebService
public interface ClaimPortType {
    public String sendClaim(ClaimDetail detail, Image claimPhoto);
}

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.

Conformance (MIME part identification): An implementation MUST use the algorithm defined in the WS-I Attachments Profile[33] when generating the MIME Content-ID header field value for a part bound using mime:content.

2.7. Service and Port

A wsdl:service is a collection of related wsdl:port elements. A wsdl:port element describes a port type bound to a particular protocol (a wsdl:binding) that is available at particular endpoint address. On the client side, a wsdl:service element is mapped to a generated service class that extends jakarta.xml.ws.Service (see Section 4.1, “jakarta.xml.ws.Service” for more information on the Service class).

Conformance (Service superclass required): A generated service class MUST extend the jakarta.xml.ws.Service class.

Conformance (Service class naming): In the absence of customization, 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 Section 2.8, “XML Names” and Section 2.8.1, “Name Collisions”.

An application MAY customize the name of the generated service class using the jaxws:class binding declaration defined in Section 9.7.7, “Service”.

In order to allow an implementation to identify the Web service that a generated service class corresponds to, the latter is required to be annotated with jakarta.xml.ws.WebServiceClient annotation. The annotation contains all the information necessary to locate a WSDL document and uniquely identify a wsdl:service inside it.

Conformance (jakarta.xml.ws.WebServiceClient required): A generated service class MUST be annotated with a jakarta.xml.ws.WebServiceClient annotation.

Jakarta XML Web Services mandates that six constructors be present on every generated service class.

Conformance (Generated service default constructor): A generated service class MUST have a default (i.e. zero-argument) public constructor. This constructor MUST call the jakarta.xml.ws.Service(URL, QName) protected constructor, passing as arguments the WSDL location and the service name. The values of the actual arguments for this call MUST be equal (in the java.lang.Object.equals sense) to the values specified in the mandatory WebServiceClient annotation on the generated service class itself.

Conformance (Generated service (WebServiceFeature …​) constructor): A generated service class MUST have a public constructor that takes one argument, the web service features (a varargs jakarta.xml.ws.WebServiceFeature). This constructor MUST call the jakarta.xml.ws.Service(URL, QName, WebServiceFeature …​) protected constructor, passing as arguments the WSDL location, the service name and the web service features. The values of the actual arguments WSDL location, service name for this call are as specified in the mandatory WebServiceClient annotation on the generated service class itself, and the value of the web service features argument is with which it was invoked.

Conformance (Generated service (URL) constructor): The implementation class MUST have a public constructor that takes one argument, the WSDL location (a java.net.URL). This constructor MUST call the jakarta.xml.ws.Service(URL, QName) protected constructor. The values of the actual arguments WSDL location is with which it was invoked and the service name is as specified in the mandatory WebServiceClient annotation on the generated service class itself.

Conformance (Generated service (URL, WebServiceFeature…​) constructor): The implementation class MUST have a public constructor that takes two arguments, the WSDL location (a java.net.URL) and the web service features (a varargs jakarta.xml.ws.WebServiceFeature). This constructor MUST call the jakarta.xml.ws.Service(URL, QName, WebServiceFeature …​) protected constructor, passing as arguments the WSDL location, the service name and the web service features. The values of the actual arguments WSDL location and the web services features are with which it was invoked and the service name is as specified in the mandatory WebServiceClient annotation on the generated service class itself.

Conformance (Generated service (URL, QName) constructor): The implementation class MUST have a public constructor that takes two arguments, the WSDL location (a java.net.URL) and the service name (a javax.xml.namespace.QName). This constructor MUST call the jakarta.xml.ws.Service(URL, QName) protected constructor, passing as arguments the WSDL location and the service name values with which it was invoked.

Conformance (Generated service (URL, QName,WebServiceFeature …​) constructor): The implementation class MUST have a public constructor that takes three arguments, the WSDL location (a java.net.URL), the service name (a javax.xml.namespace.QName) and the web service features (a varargs jakarta.xml.ws.WebServiceFeature). This constructor MUST call the jakarta.xml.ws.Service(URL, QName, WebServiceFeature …​) protected constructor, passing as arguments the WSDL location, the service name and the web service feature values with which it was invoked.

For each port in the service, the generated client side service class contains the following methods, two for each port defined by the WSDL service and whose binding is supported by the Jakarta XML Web Services implementation:

getPortName()

One required method that takes no parameters and returns a proxy that implements the mapped service endpoint interface. The method generated delegates to the Service.getPort(…​) method passing it the port name. The value of the port name MUST be equal to the value specified in the mandatory WebEndpoint annotation on the method itself.

getPortName(WebServiceFeature…​ features)

One required method that takes a variable-length array of jakarta.xml.ws.WebServiceFeature and returns a proxy that implements the mapped service endpoint interface. The method generated delegates to the Service.getPort(QName portName, Class<T> SEI, WebServiceFeature…​ features) method passing it the port name, the SEI and the features. The value of the port name MUST be equal to the value specified in the mandatory WebEndpoint annotation on the method itself.

Conformance (Failed getPort Method): A generated getPortName method MUST throw jakarta.xml.ws.WebServiceException on failure.

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.8, “XML Names”, this Java identifier is then treated as a JavaBean property for the purposes of deriving the getPortName method name.

An application MAY customize the name of the generated methods for a port using the jaxws:method binding declaration defined in Section 9.7.8, “Port”.

In order to enable an implementation to determine the wsdl:port that a port getter method corresponds to, the latter is required to be annotated with a jakarta.xml.ws.WebEndpoint annotation.

Conformance (jakarta.xml.ws.WebEndpoint required): The getPortName methods of generated service interface MUST be annotated with a jakarta.xml.ws.WebEndpoint annotation.

2.7.1. Example

The following shows a WSDL extract and the resulting generated service class.

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
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
<!-- 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",
                  targetNamespace="http://example.com/stocks",
                  wsdlLocation="http://example.com/stocks.wsdl")
public class StockQuoteService extends jakarta.xml.ws.Service {

    public StockQuoteService() {
        super(new URL("http://example.com/stocks.wsdl"),
              new QName("http://example.com/stocks", "StockQuoteService"));
    }

    public StockQuoteService(WebServiceFeature ... featurs) {
        super(new URL("http://example.com/stocks.wsdl"),
              new QName("http://example.com/stocks", "StockQuoteService"),
              features);
    }

    public StockQuoteService(URL wsdlLocation) {
        super(wsdlLocation,
              new QName("http://example.com/stocks", "StockQuoteService"));
    }

    public StockQuoteService(URL wsdlLocation, WebServiceFeature ... features) {
        super(wsdlLocation,
              new QName("http://example.com/stocks", "StockQuoteService"),
              features);
    }

    public StockQuoteService(URL wsdlLocation, QName serviceName) {
        super(wsdlLocation, serviceName);
    }

    public StockQuoteService(URL wsdlLocation, QName serviceName,
                             WebServiceFeature ... features) {
        super(wsdlLocation, serviceName, features);
    }

    @WebEndpoint(name="StockQuoteHTTPPort")
    public StockQuoteProvider getStockQuoteHTTPPort() {
        return (StockQuoteProvider) super.getPort(
                    new QName("http://example.com/stocks","StockQuoteHTTPPort"),
                    StockQuoteProvider.class);
    }

    @WebEndpoint(name="StockQuoteHTTPPort")
    public StockQuoteProvider getStockQuoteHTTPPort(WebServiceFeature... features) {
        return (StockQuoteProvider) super.getPort(
                    new QName("http://example.com/stocks","StockQuoteHTTPPort"),
                    StockQuoteProvider.class,
                    features);
    }

    @WebEndpoint(name="StockQuoteSMTPPort")
    public StockQuoteProvider getStockQuoteSMTPPort() {
        return (StockQuoteProvider) super.getPort(
                    new QName("http://example.com/stocks","StockQuoteSMTPPort"),
                    StockQuoteProvider.class);
    }

    @WebEndpoint(name="StockQuoteSMTPPort")
    public StockQuoteProvider getStockQuoteSMTPPort(WebServiceFeature... features) {
        return (StockQuoteProvider) super.getPort(
                    new QName("http://example.com/stocks","StockQuoteSMTPPort"),
                    StockQuoteProvider.class,
                    features);
    }
}

In the above, StockQuoteProvider is the service endpoint interface mapped from the WSDL port type for both referenced bindings.

2.8. XML Names

Appendix D of Jakarta XML Binding[39] defines a mapping from XML names to Java identifiers. Jakarta XML Web Services 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, the get or set prefix is not added. Instead the first word in the word-list has its first character converted to lower case.

Parameter identifiers

When mapping wsdl:part names or wrapper child local names to Java method parameter identifiers, the first word in the word-list has its first character converted to lower case. Clashes with Java language reserved words are reported as errors and require use of appropriate customizations to fix the clash.

2.8.1. Name Collisions

WSDL name scoping rules may result in name collisions when mapping from WSDL 1.1 to Java. E.g., a port type and a service are both mapped to Java classes but WSDL allows both to be given the same name. This section defines rules for resolving such name collisions.

The order of precedence for name collision resolution is as follows (highest to lowest);

  1. Service endpoint interface

  2. Non-exception Java class

  3. Exception class

  4. Service class

If a name collision occurs between two identifiers with different precedences, the lower precedence item has its name changed as follows:

Non-exception Java class

The suffix "_Type" is added to the class name.

Exception class

The suffix "_Exception" is added to the class name.

Service class

The suffix "_Service" is added to the class name.

If a name collision occurs between two identifiers with the same precedence, 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.

If a name collision occurs between a mapped Java method and a method in jakarta.xml.ws.BindingProvider (an interface that proxies are required to implement, see Section 4.2, “jakarta.xml.ws.BindingProvider”), the prefix “_” is added to the mapped method.

3. Java to WSDL 1.1 Mapping

This chapter describes the mapping from Java to WSDL 1.1. This mapping is used when generating web service endpoints from existing Java interfaces.

Conformance (WSDL 1.1 support): Implementations MUST support mapping Java to WSDL 1.1.

The following sections describe the default mapping from each Java construct to the equivalent WSDL 1.1 artifact.

An application MAY customize the mapping using the annotations defined in Chapter 8, Annotations.

Conformance (Standard annotations): An implementation MUST support the use of annotations defined in Chapter 8, Annotations to customize the Java to WSDL 1.1 mapping.

3.1. Java Names

Conformance (Java identifier mapping): In the absence of annotations described in this specification, Java identifiers MUST be mapped to XML names using the algorithm defined in appendix B of SOAP 1.2 Part 2[4].

3.1.1. Name Collisions

WS-I Basic Profile 1.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.

Conformance (Method name disambiguation): An implementation MUST support the use of the jakarta.jws.WebMethod annotation to disambiguate overloaded Java method names when mapped to WSDL.

3.2. Package

A Java package is mapped to a wsdl:definitions element and an associated targetNamespace attribute. 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.

A default value for the targetNamespace attribute is derived from the package name as follows:

  1. The package name is tokenized using the “.” character as a delimiter.

  2. The order of the tokens is reversed.

  3. The value of the targetNamespace attribute is obtained by concatenating “http://” to the list of tokens separated by “.” and “/”.

E.g., the Java package "com.example.ws" would be mapped to the target namespace "http://ws.example.com/".

Conformance (Package name mapping): The jakarta.jws.WebService annotation (see Section 8.11.1, “jakarta.jws.WebService”) 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. In the absence of a jakarta.jws.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.

No specific authoring style is required for the mapped WSDL document; implementations are free to generate WSDL that uses the WSDL and XML Schema import directives.

Conformance (WSDL and XML Schema import directives): Generated WSDL MUST comply with the WS-I Basic Profile 1.0[8] restrictions (See R2001, R2002, and R2003) on usage of WSDL and XML Schema import directives.

3.3. Class

A Java class (not an interface) annotated with a jakarta.jws.WebService annotation can be used to define a Web service.

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, then the interface referred by this element is for all purposes the SEI associated with the class.

Otherwise, the class implicitly defines a service endpoint interface (SEI) which comprises all of the public non-static or non-final methods that satisfy one of the following conditions:

  1. They are annotated with the jakarta.jws.WebMethod annotation with the exclude element set to false or missing (since false is the default for this annotation element).

  2. They are not annotated with the jakarta.jws.WebMethod annotation but their declaring class has a jakarta.jws.WebService annotation.

For mapping purposes, 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.

In pratice, in order to exclude a public method of a class annotated with WebService and not directly specifying a endpointInterface from the implicitly defined SEI, it is necessary to annotate the method with a WebMethod annotation with the exclude element set to true.

Conformance (Class mapping): An implementation MUST support the mapping of jakarta.jws.WebService annotated classes to implicit service endpoint interfaces.

For mapping purposes, this class must be a top level class or a static inner class. As defined by Jakarta XML Web Services Metadata, a class annotated with jakarta.jws.WebService must have a default public constructor.

3.4. Interface

A Java service endpoint interface (SEI) is mapped to a wsdl:portType element. 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. An SEI is a Java interface that meets all of the following criteria:

Conformance (portType naming): The jakarta.jws.WebService annotation (see section Section 8.11.1, “jakarta.jws.WebService”) MAY be used to customize the name and targetNamespace attributes of the wsdl:portType element. If not customized, 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 Section 3.2, “Package”.

Figure 8, “Java interface to WSDL portType mapping using document style” shows an example of a Java SEI and the corresponding wsdl:portType.

Multiple SEIs in the same package may result in name clashes as the result of sections Section 3.6.2.1, “Document Wrapped” and Section 3.7, “Service Specific Exception” of the specification. Customizations may be used to resolve these clashes. See sections Section 8.2, “jakarta.xml.ws.WebFault”, Section 8.3, “jakarta.xml.ws.RequestWrapper” and Section 8.4, “jakarta.xml.ws.ResponseWrapper” for more information on these customizations.

3.4.1. Inheritance

WSDL 1.1 does not define a standard representation for the inheritance of wsdl:portType elements. When mapping an SEI that inherits from another interface, the SEI is treated as if all methods of the inherited interface were defined within the SEI.

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.

Conformance (Inherited interface mapping): An implementation MAY map inherited interfaces to additional wsdl:portType elements within the wsdl:definitions element.

3.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.

Conformance (Operation naming): In the absence of customizations, the value of the name attribute of the wsdl:operation element MUST be the name of the Java method. The jakarta.jws.WebMethod (see Section 8.11.2, “jakarta.jws.WebMethod”) 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. If the exclude element of the jakarta.jws.WebMethod is set to true then the Java method MUST NOT be present in the wsdl as a wsdl:operation element.

Methods are either one-way or two-way: one way methods have an input but produce no output, two way methods have an input and produce an output. Section 3.5.1, “One Way Operations” describes one way operations further.

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.

  • (Two-way methods only) an optional wsdl:output element that refers to a wsdl:message to describe the operation output.

  • (Two-way methods only) zero or more wsdl:fault child elements, one for each exception thrown by the method. The wsdl:fault child elements refer to associated wsdl:message elements to describe each fault. See Section 3.7, “Service Specific Exception” for further details on exception mapping.

  • wsdl:input, wsdl:output (if any), and wsdl:fault (if any) child elements must have wsam:Action attribute to describe WS-Addressing Action property. The value of the wsam:Action attribute is computed using the algorithm in Section 3.5.2, “wsam:Action Computation Algorithm”

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. Naming of fault messages is described in Section 3.7, “Service Specific Exception”.

Conformance (Generating wsam:Action): wsdl:operation’s child elements wsdl:input, wsdl:output, and wsdl:fault MUST have the wsam:Action attribute. wsam:Action attribute MUST be computed using the algorithm that is specified in Section 3.5.2, “wsam:Action Computation Algorithm”

Each wsdl:message element has one of the following[5]:

Document style

A single wsdl:part child element that refers, via an element attribute, to a global element declaration in the wsdl:types section.

RPC style

Zero or more wsdl:part child elements (one per method parameter and one for a non-void return value) that refer, via a type attribute, to named type declarations in the wsdl:types section.

Figure 8, “Java interface to WSDL portType mapping using document style” shows an example of mapping a Java interface containing a single method to WSDL 1.1 using document style. Figure 9, “Java interface to WSDL portType mapping using RPC style” shows an example of mapping a Java interface containing a single method to WSDL 1.1 using RPC style.

Section 3.6, “Method Parameters and Return Type” describes the mapping from Java methods and their parameters to corresponding global element declarations and named types in the wsdl:types section.

8. Java interface to WSDL portType mapping using document style
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
// Java
package com.example;
@WebService
public interface StockQuoteProvider {
    float getPrice(String tickerSymbol)
        throws TickerException;
}

<!-- WSDL extract -->
<types>
  <xsd:schema targetNamespace="...">
    <!-- 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 -->
    ...
  </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" wsam:action="..."/>
    <output message="tns:getPriceResponse" wsam:action="..."/>
    <fault message="tns:TickerException" wsam:action="..."/>
  </operation>
</portType>
9. Java interface to WSDL portType mapping using RPC style
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
// Java
package com.example;
@WebService
public interface StockQuoteProvider {
    float getPrice(String tickerSymbol)
        throws TickerException;
}

<!-- WSDL extract -->
<types>
  <xsd:schema targetNamespace="...">
    <!-- element declarations -->
    <xsd:element name="TickerException"
        type="tns:TickerExceptionType"/>

    <!-- type definitions -->
    ...
  </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>

3.5.1. One Way Operations

Only Java methods whose return type is void, that have no parameters that implement Holder and that do not throw any checked exceptions can be mapped to one-way operations. 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.

Conformance (One-way mapping): Implementations MUST support use of the jakarta.jws.OneWay (see Section 8.11.3, “jakarta.jws.OneWay”) annotation to specify which methods to map to one-way operations. Methods that are not annotated with jakarta.jws.OneWay MUST NOT be mapped to one-way operations.

Conformance (One-way mapping errors): Implementations MUST prevent mapping to one-way operations of methods that do not meet the necessary criteria.

3.5.2. wsam:Action Computation Algorithm

All wsdl:operation’s child elements wsdl:input, wsdl:output and wsdl:fault must have the wsam:Action attribute in the the generated WSDL. The algorithm to compute wsam:Action from SEI method is as follows:

  1. A non-default @Action(input=…​) or @WebMethod(action=…​) value on a SEI method MUST result into wsdl:input[@wsam:Action] attribute in the corresponding wsdl:operation. Also, @Action(input=…​) and @WebMethod(action=…​) annotation element values MUST be same, if present.

  2. A non-default @Action(output=…​) value on a SEI method MUST result into wsdl:output[@wsam:Action attribute in the corresponding wsdl:operation.

  3. A non-default @Action(@FaultAction=…​) value on a SEI method MUST result into wsdl:fault[@wsam:Action attribute in the corresponding wsdl:operation. The wsdl:fault element MUST correspond to the exception specified by className annotated element value.

  4. If wsdl:input[@wsam:Action] cannot be mapped from the above steps, then wsam:Action is generated using the metadata defaulting algorithm as if wsdl:input[@name] is not present in WSDL.

  5. If wsdl:output[@wsam:Action] cannot be mapped from the above steps, then wsam:Action is generated using the metadata defaulting algorithm as if wsdl:output[@name] is not present in WSDL.

  6. If wsdl:fault[@wsam:Action] cannot be mapped from the above steps, then wsam:Action is generated using the metadata defaulting algorithm as if wsdl:fault[@name] is the corresponding exception class name.

For example:

1
2
3
4
5
6
7
8
9
10
11
12
@Action(input="inAction")
public float getPrice(String ticker) throws InvalidTickerException;

// the mapped wsdl:operation if targetNamespace="http://example.com" and
// portType="StockQuoteProvider"
<operation name="getPrice">
  <input name="foo" message="tns:getPrice" wsam:Action="inAction"/>
  <output name="bar" message="tns:getPriceResponse"
    wsam:Action="http://example.com/StockQuoteProvider/getPriceResponse" />
  <fault name="FooTickerException" message="tns:InvalidTickerException"
    wsam:Action="http://example.com/StockQuoteProvider/getPrice/Fault/InvalidTickerException"/>
</operation>

3.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. Parameters can be mapped to components of the message or global element declaration for either the operation input message, operation output message or both. The mapping depends on the parameter classification.The jakarta.jws.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. The jakarta.jws.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.

Since Jakarta XML Web Services uses Jakarta XML Binding for it data binding, Jakarta XML Binding annotations on methods and method parameters MUST be honored. A Jakarta XML Binding 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 Jakarta XML Binding annotations): An implementation MUST honor any Jakarta XML Binding 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. The set of Jakarta XML Binding annotations that MUST be supported are: jakarta.xml.bind.annotation.XmlAttachementRef, jakarta.xml.bind.annotation.XmlList, jakarta.xml.bind.XmlMimeType and jakarta.xml.bind.annotation.adapters.XmlJavaTypeAdapter

Jakarta XML Binding doesn’t define any namespace by default to types and elements. In the web services, typically these entities that are created for method parameters and return parameters are qualified.

Conformance (Overriding Jakarta XML Binding types empty namespace): Jakarta XML Web Services tools and runtimes MUST override the default empty namespace for Jakarta XML Binding types and elements to SEI’s targetNamespace.

3.6.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.

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.

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.

A methods return type is always out. For method parameters, holder classes are used to determine the classification. jakarta.xml.ws.Holder. A parameter whose type is a parameterized jakarta.xml.ws.Holder<T> class is classified as in/out or out, all other parameters are classified as in.

Conformance (Parameter classification): The jakarta.jws.WebParam annotation (see Section 8.11.4, “jakarta.jws.WebParam”) MAY be used to specify whether a holder parameter is treated as in/out or out. If not specified, the default MUST be in/out.

Conformance (Parameter naming): The jakarta.jws.WebParam annotation (see Section 8.11.4, “jakarta.jws.WebParam”) MAY be used to specify the name of the wsdl:part or XML Schema element declaration corresponding to a Java parameter. If both the name and partName elements are used in the jakarta.jws.WebParam annotation then the partName MUST be used for the wsdl:part name attribute and the name element from the annotation will be ignored. If not specified, the default is "argN", where N is replaced with the zero-based argument index. Thus, for instance, the first argument of a method will have a default parameter name of "arg0", the second one "arg1" and so on.

Conformance (Result naming): The jakarta.jws.WebResult annotation (see Section 8.11.4, “jakarta.jws.WebParam”) MAY be used to specify the name of the wsdl:part or XML Schema element declaration corresponding to the Java method return type. If both the name and partName elements are used in the jakarta.jws.WebResult annotations then the partName MUST be used for the wsdl:part name attribute and the name elment from the annotation will be ignored. In the absence of customizations, the default name is return.

Conformance (Header mapping of parameters and results): The jakarta.jws.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. The jakarta.jws.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.

3.6.2. Use of Jakarta XML Binding

Jakarta XML Binding defines a mapping from Java classes to XML Schema constructs. Jakarta XML Web Services 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.

Three styles of Java to WSDL mapping are supported: document wrapped, document bare and RPC. The styles differ in what XML Schema constructs are generated for a method. The three styles are described in the following subsections.

The jakarta.jws.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.

3.6.2.1. Document Wrapped

This style is identified by a jakarta.jws.SOAPBinding annotation with the following properties: a style of DOCUMENT, a use of LITERAL and a parameterStyle of WRAPPED.

For the purposes of utilizing the Jakarta XML Binding mapping, 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). Application’s programming model doesn’t use these bean classes, so the applications need not package these classes. Jakarta XML Web Services implementations may generate these classes dynamically as specified in this section.

Conformance (Dynamically generating wrapper beans): A Jakarta XML Web Services implementation SHOULD not require an application to package request and response bean classes. However, when the bean classes are packaged, they MUST be used.

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. 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, the wrapper beans package MUST be a generated jaxws subpackage of the SEI package.

The jakarta.xml.ws.RequestWrapper and jakarta.xml.ws.ResponseWrapper annotations (see Section 8.3, “jakarta.xml.ws.RequestWrapper” and Section 8.4, “jakarta.xml.ws.ResponseWrapper”) MAY be used to customize the name of the generated wrapper bean classes.

Conformance (Wrapper element names): The jakarta.xml.ws.RequestWrapper and jakarta.xml.ws.ResponseWrapper annotations (see Section 8.3, “jakarta.xml.ws.RequestWrapper” and Section 8.4, “jakarta.xml.ws.ResponseWrapper”) MAY be used to specify the qualified name of the elements generated for the wrapper beans.

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. Clashes during generation MUST be reported as an error and require user intervention via name customization to correct. Note that some platforms do not distiguish filenames based on case so comparisons MUST ignore case.

The name of wsdl:part for the wrapper must be named as "parameters" for input messages in the generated WSDL. If a SEI method doesn’t have any header parameters or return type, then the name of wsdl:part for the wrapper must be named as "parameters" for output messages in the generated WSDL, otherwise it would be named as "result". The RequestWrapper and ResponseWrapper annotations MAY be used to customize the name of the wsdl:part for the wrapper part.

Conformance (Default Wrapper wsdl:part names): In the absence of customizations, the name of the wsdl:part for the wrapper MUST be named as parameters for input messages in the generated WSDL. In the absence of customizations, when there are no header parameters or return type in a SEI method, the name of the wsdl:part for the wrapper MUST be named as parameters for output messages. In all other cases, it MUST be named as result.

Conformance (Customizing Wrapper wsdl:part names): Non-default partName values of the RequestWrapper and ResponseWrapper annotations, if specified on a SEI method, MUST be used as wsdl:part name for the corresponding input and output messages in the generated WSDL.

A request bean is generated containing properties for each in and in/out non-header parameter. A response bean is generated containing properties for the method return value, each out non-header parameter, and in/out non-header parameter. Method return values are represented by an out property named "return". The order of the properties in the request bean is the same as the order of parameters in the method signature. 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.

If a SEI’s method parameter or return type is annotated with @XmlElement, that annotation is used for the wrapper bean properties. This can be used to map corresponding XML schema element declaration’s attributes like minOccurs, maxOccurs, and nillable etc. It is an error to specify @XmlElement with a parameter or return type that is mapped to header part. If both @XmlElement and @WebParam/@WebResult are present, then it is an error to specify @XmlElement’s name, and namespace elements different from @WebParam/@WebResult’s name and targetNamespace elements respectively.

Conformance (Wrapper property): If a SEI’s method parameter or return type is annotated with @XmlElement, that annotation MUST be used on the wrapper bean property.

The request and response beans are generated with the appropriate Jakarta XML Binding customizations to result in a global element declaration for each bean class when mapped to XML Schema by Jakarta XML Binding. The corresponding global element declarations MUST NOT have the nillable attribute set to a value of true. Whereas the element name is derived from the RequestWrapper or ResponseWrapper annotations, 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).

10. Wrapper mode bean representation of an operation
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
float getPrice(@WebParam(name="tickerSymbol") String sym);

@XmlRootElement(name="getPrice", targetNamespace="...")
@XmlType(name="getPrice", targetNamespace="...")
@XmlAccessorType(AccessType.FIELD)
public class GetPrice {
    @XmlElement(name="tickerSymbol", targetNamespace="")
    public String tickerSymbol;
}

@XmlRootElement(name="getPriceResponse", targetNamespace="...")
@XmlType(name="getPriceResponse", targetNamespace="...")
@XmlAccessorType(AccessType.FIELD)
public class GetPriceResponse {
    @XmlElement(name="return", targetNamespace="")
    public float _return;
}

When the Jakarta XML Binding 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.

out

The parameter or return value is mapped to a child element of the global element declaration for the response bean. In the case of a parameter, the class of the value of the holder class (see Section 3.6.1, “Parameter and Return Type Classification”) is used for the mapping rather than the holder class itself.

in/out

The parameter is mapped to a child element of the global element declarations for the request and response beans. The class of the value of the holder class (see Section 3.6.1, “Parameter and Return Type Classification”) is used for the mapping rather than the holder class itself.

The global element declarations are used as the values of the wsdl:part elements element attribute, see figure 8, “Java interface to WSDL portType mapping using document style”.

3.6.2.2. Document Bare

This style is identified by a jakarta.jws.SOAPBinding annotation with the following properties: a style of DOCUMENT, a use of LITERAL and a parameterStyle of BARE.

In order to qualify for use of bare mapping mode a Java method must fulfill all of the following criteria:

  1. It must have at most one in or in/out non-header parameter.

  2. If it has a return type other than void it must have no in/out or out non-header parameters.

  3. If it has a return type of void it must have at most one in/out or out non-header parameter.

If present, the type of the input parameter is mapped to a named XML Schema type using the mapping defined by Jakarta XML Binding. If the input parameter is a holder class then the class of the value of the holder is used instead.

If present, the type of the output parameter or return value is mapped to a named XML Schema type using the mapping defined by Jakarta XML Binding. If an output parameter is used then the class of the value of the holder class is used.

A global element declaration is generated for the method input and, in the absence of a WebParam annotation, its local name is equal to the operation name. A global element declaration is generated for the method output and, in the absence of a WebParam or WebResult annotation, the local name is equal to the operation name suffixed with "Response". 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.

The namespace name of the input and output global elements is the value of the targetNamespace attribute of the WSDL definitions element.

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.

The global element declarations are used as the values of the wsdl:part elements element attribute, see figure 8, “Java interface to WSDL portType mapping using document style”.

3.6.2.3. RPC

This style is identified by a jakarta.jws.SOAPBinding annotation with the following properties: a style of RPC, a use of LITERAL and a parameterStyle of WRAPPED [6].

The Java types of each in, out and in/out parameter and the return value are mapped to named XML Schema types using the mapping defined by Jakarta XML Binding. For out and in/out parameters the class of the value of the holder is used rather than the holder itself.

Each method parameter and the return type is mapped to a message part according to the parameter classification:

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.

in/out

The parameter is mapped to a part of the input and output message.

The named types are used as the values of the wsdl:part elements type attribute, see figure 9, “Java interface to WSDL portType mapping using RPC style”. 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.

Due to the limitations described in section 5.3.1 of the WS-I Basic Profile specification (see [8]), null values cannot be used as method arguments or as the return value from a method which uses the rpc/literal binding.

Conformance (Null Values in rpc/literal): If a null value is passed as an argument to a method, or returned from a method, that uses the rpc/literal style, then an implementation MUST throw a WebServiceException.

3.7. Service Specific Exception

A service specific Java exception is mapped to a wsdl:fault element, a wsdl:message element with a single child wsdl:part element and an XML Schema global element declaration. 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 wsdl:part element refers to an XML Schema global element declaration that describes the fault.

Conformance (Exception naming): In the absence of customizations, the name of the global element declaration for a mapped exception MUST be the name of the Java exception. The jakarta.xml.ws.WebFault annotation MAY be used to customize the local name and namespace name of the element.

Conformance (wsdl:message naming): In the absence of customizations, the name of the wsdl:message element MUST be the name of the Java exception.

The jakarta.xml.ws.WebFault annotation may be used to customize the name of the wsdl:message element and also to resolve any conflicts.

Conformance (wsdl:message naming using WebFault): If an exception has @WebFault, then messageName MUST be the name of the corresponding wsdl:message element.

Service specific exceptions are defined as all checked exceptions except java.rmi.RemoteException and its subclasses.

Conformance (java.lang.RuntimeExceptions and java.rmi.RemoteExceptions): java.lang.RuntimeException and java.rmi.RemoteException and their subclasses MUST NOT be treated as service specific exceptions and MUST NOT be mapped to WSDL.

Jakarta XML Binding 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. For exceptions that match the pattern described in Section 2.5, “Fault” (i.e. exceptions that have a getFaultInfo method and WebFault annotation), the FaultBean is used as input to Jakarta XML Binding when mapping the exception to XML Schema. For exceptions that do not match the pattern described in Section 2.5, “Fault”, Jakarta XML Web Services maps those exceptions to Java beans and then uses those Java beans as input to the Jakarta XML Binding mapping. The following algorithm is used to map non-matching exception classes to the corresponding Java beans for use with Jakarta XML Binding:

  1. In the absence of customizations, the name of the bean is the same as the name of the Exception suffixed with "Bean".

  2. In the absence of customizations, the package of the bean is a generated jaxws subpackage of the SEI package. E.g. if the SEI package is com.example.stockquote then the package of the bean would be com.example.stockquote.jaxws.

  3. For each getter in the exception and its superclasses, a property of the same type and name is added to the bean. The getCause, getLocalizedMessage and getStackTrace getters from java.lang.Throwable and the getClass getter from java.lang.Object are excluded from the list of getters to be mapped.

  4. The bean is annotated with a Jakarta XML Binding @XmlType annotation. If the exception class has a @XmlType annotation, then it is used for the fault bean’s @XmlType annotation. Otherwise, the fault bean’s @XmlType annotation is computed with name property set to the name of the exception and the namespace property set to the target namespace of the corresponding portType. Additionally, 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, sorted lexicographically according to the Unicode value of each of their characters (i.e. using the same algorithm that the int java.lang.String.compareTo(String) method uses).

  5. The bean is annotated with a Jakarta XML Binding @XmlRootElement annotation whose name property is set, in the absence of customizations, to the name of the exception.

Conformance (Fault bean’s @XmlType): If an exception class has a @XmlType annotation, then it MUST be used for the fault bean’s @XmlType annotation.

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. Clashes during generation MUST be reported as an error and require user intervention via name customization to correct. Note that some platforms do not distiguish filenames based on case so comparisons MUST ignore case.

11. Mapping of an exception to a bean for use with Jakarta XML Binding.
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", targetNamespace="...")
public class UnknownTicker extends Exception {
    ...
    public UnknownTicker(Sting ticker) { ... }
    public UnknownTicker(Sting ticker, String message) { ... }
    public UnknownTicker(Sting ticker, String message, Throwable cause)
        { ... }
    public String getTicker() { ... }
}

@XmlRootElement(name="UnknownTickerFault" targetNamespace="...")
@XmlAccessorType(AccessType.FIELD)
@XmlType(name="UnknownTicker", namespace="...",
    propOrder={"message", "ticker"})
public class UnknownTickerBean {
    ...
    public UnknownTickerBean() { ... }
    public String getTicker() { ... }
    public void setTicker(String ticker) { ... }
    public String getMessage() { ... }
    public void setMessage(String message) { ... }
}

Application’s programming model doesn’t use these bean classes, so the applications need not package these classes. Jakarta XML Web Services implementations may generate these classes dynamically as specified in this section.

Conformance (Dynamically generating exception beans): Jakarta XML Web Services implementations SHOULD not require an application to package exception bean classes. However, when the exception bean classes are packaged, they MUST be used.

3.8. Bindings

In WSDL 1.1, an abstract port type can be bound to multiple protocols.

Conformance (Binding selection): An implementation MUST generate a WSDL binding according to the rules of the binding denoted by the BindingType annotation (see Section 8.8, “jakarta.xml.ws.BindingType”), if present, otherwise the default is the SOAP 1.1/HTTP binding (see Chapter 11, SOAP Binding).

Each protocol binding extends a common extensible skeleton structure and there is one instance of each such structure for each protocol binding. An example of a port type and associated binding skeleton structure is shown in figure 12, “WSDL portType and associated binding”.

12. WSDL portType and associated binding
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">
  <!-- binding specific extensions possible here -->
  <operation name="getPrice">
    <!-- binding specific extensions possible here -->
    <input message="tns:getPrice">
      <!-- binding specific extensions possible here -->
    </input>
    <output message="tns:getPriceResponse">
      <!-- binding specific extensions possible here -->
    </output>
    <fault message="tns:unknowntickerException">
      <!-- binding specific extensions possible here -->
    </fault>
  </operation>
</binding>

The common skeleton structure is mapped from Java as described in the following subsections.

3.8.1. Interface

A Java SEI is mapped to a wsdl:binding element and zero or more wsdl:port extensibility elements.

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. The value of the name attribute of the wsdl:binding is not significant, by convention it contains the qualified name of the corresponding wsdl:portType suffixed with "Binding".

The wsdl:port extensibility elements define the binding specific endpoint address for a given port, see Section 3.11, “Service and Ports”.

3.8.2. Method and Parameters

Each method in a Java SEI is mapped to a wsdl:operation child element of the corresponding wsdl:binding. The value of the name attribute of the wsdl:operation element is the same as the corresponding wsdl:operation element in the bound wsdl:portType. The wsdl:operation element has wsdl:input, wsdl:output, and wsdl:fault child elements if they are present in the corresponding wsdl:operation child element of the wsdl:portType being bound.

3.9. Generics

In Jakarta XML Web Services when starting from Java and if generics are used in the document wrapped case, impelementations are required to use type erasure(see JLS section 4.6 for definition of Type Erasure) when generating the request / response wrapper beans and exception beans except in the case of Collections. Type erasure is a mapping from parameterized types or type variables to types that are never parameterized types or type variables. Erasure basically gets rid of all the generic type information from the runtime representation. In the case of Collection instead of applying erasure on the Collection itself, erasure would be applied to the type of Collection i.e it would be Collection<erasure(T)>. 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, Color color) {
    shape.setColor(color);
    return shape;
}

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
@XmlRootElement(name = "setColor", namespace = "...")
@XmlAccessorType(AccessType.FIELD)
@XmlType(name = "setColor", namespace = "...")
public class SetColor {

    @XmlElement(name = "arg0", namespace = "")
    private Shape arg0;

    @XmlElement(name = "arg1", namespace = "")
    private Color arg0;

    public Shape getArg0() {
        return this.arg0;
    }

    public void setArg0(Shape arg0) {
        this.arg0 = arg0;
    }

    public Color getArg1() {
        return this.arg1;
    }

    public void setArg1(Color arg1) {
        this.arg1 = arg1;
    }
}

The following code snippets shows the resulting wrapper bean when using Collections:

1
2
3
public List<Shape> echoShapeList(List<Shape> list) {
    return list;
}

The generated wrapper bean would be

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
@XmlRootElement(name = "echoShapeList", namespace = "...")
@XmlAccessorType(AccessType.FIELD)
@XmlType(name = "echoShapeList", namespace = "...")
public class EchoShapeList {

    @XmlElement(name = "arg0", namespace = "")
    private List<Shape> arg0;

    public List<Shape> getArg0() {
        return this.arg0;
    }

    public void setArg0(List<Shape> arg0) {
        this.arg0 = arg0;
    }
}
1
2
3
4
5
public <T> T echoTList(List<T> list) {
    if (list.size() == 0)
        return null;
    return list.iterator().next();
}

The generated wrapper bean would be

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
@XmlRootElement(name = "echoTList", namespace = "...")
@XmlAccessorType(AccessType.FIELD)
@XmlType(name = "echoTList", namespace = "...")
public class EchoTList {

    @XmlElement(name = "arg0", namespace = "")
    private List<Object> arg0;

    public List<Object> getArg0() {
        return this.arg0;
    }

    public void setArg0(List<Object> arg0) {
        this.arg0 = arg0;
    }
}
1
2
3
4
5
6
7
public List<? extends Shape> setArea(List<? extends Shape> list) {
    Iterator iterator = list.iterator();
    while(iterator.haNext()) {
        iterator.next().setArea(...);
    }
    return list;
}

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", namespace = "...")
@XmlAccessorType(AccessType.FIELD)
@XmlType(name = "setArea", namespace = "...")
public class SetArea {

    @XmlElement(name = "arg0", namespace = "")
    private List<Shape> arg0;

    public List<Shape> getArg0() {
        return this.arg0;
    }

    public void setArg0(List<Shape> arg0) {
        this.arg0 = arg0;
    }
}

3.10. SOAP HTTP Binding

This section describes the additional WSDL binding elements generated when mapping Java to WSDL 1.1 using the SOAP HTTP binding.

Conformance (SOAP binding support): Implementations MUST be able to generate SOAP HTTP bindings when mapping Java to WSDL 1.1.

Figure 13, “WSDL SOAP HTTP binding” shows an example of a SOAP HTTP binding.

13. WSDL SOAP HTTP binding
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.xmlsoap.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>

3.10.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.11, “Service and Ports”).

The value of the transport attribute of the soap:binding is http://schemas.xmlsoap.org/soap/http. The value of the style attribute of the soap:binding is either document or rpc.

Conformance (SOAP binding style required): Implementations MUST include a style attribute on a generated soap:binding.

3.10.2. Method and Parameters

Each method in a Java SEI is mapped to a soap:operation child element of the corresponding wsdl:operation. The value of the style attribute of the soap:operation is document or rpc. If not specified, the value defaults to the value of the style attribute of the soap:binding. WS-I Basic Profile[8] requires that all operations within a given SOAP HTTP binding instance have the same binding style.

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. The value of the use attribute of the soap:body is literal. Figure 14, “WSDL definition using document style” shows an example using document style, figure 15, “WSDL definition using rpc style” shows the same example using rpc style.

14. WSDL definition using document style
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
<types>
  <schema targetNamespace="...">
    <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.xmlsoap.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>
15. WSDL definition using rpc style
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="...">
    <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>

3.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 latter is mapped from the value of the targetNamespace element of the WebService annotation, if non-empty value, otherwise from the package of the Java service implementation class according to the rules in Section 3.2, “Package”.

In mapping a @WebService-annotated class (see Section 3.3, “Class”) to a wsdl:service, the serviceName element of the WebService annotation are used to derive the service name. The value of the name attribute of the wsdl:service element is computed according to the Jakarta XML Web Services Metadata [16] specification. It is given by the serviceName element of the WebService annotation, if present with a non-default value, otherwise the name of the implementation class with the "Service" suffix appended to it.

Conformance (Service creation): Implementations MUST be able to map classes annotated with the jakarta.jws.WebService annotation to WSDL wsdl:service elements.

A WSDL 1.1 service is a collection of related wsdl:port elements. A wsdl:port element describes a port type bound to a particular protocol (a wsdl:binding) that is available at particular endpoint address.

Each desired port is represented by a wsdl:port child element of the single wsdl:service element mapped from the Java package. Jakarta XML Web Services allows specifying one port of one binding type for each service defined by the application. Implementations MAY support additional ports, as long as their names do not conflict with the standard one.

Conformance (Port selection): The portName element of the WebService annotation, if present, MUST be used to derive the port name to use in WSDL. In the absence of a portName element, an implementation MUST use the value of the name element of the WebService annotation, if present, suffixed with "Port". Otherwise, an implementation MUST use the simple name of the class annotated with WebService suffixed with "Port".

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 Section 3.8, “Bindings”).

Binding specific child extension elements of the wsdl:port element define the endpoint address for a port. E.g. see the soap:address element described in Section 3.10.1, “Interface”.

If the endpoint enables Addressing, that can be indicated in the generated WSDL as per the Addressing 1.0 - Metadata[27].

Conformance (Use of Addressing): Endpoint’s use of addressing, if any, MUST be indicated in the wsdl:binding or wsdl:port sections of the WSDL 1.1 as per WS-Addressing 1.0 - Metadata[27].

Example 1: Possible Policy assertion for @Addressing in the generated WSDL

1
2
3
<wsam:Addressing wsp:Optional="true">
  <wsp:Policy/>
</wsam:Addressing>

Example 2: Possible Policy assertion for @Addressing(required=true) in the generated WSDL

1
2
3
<wsam:Addressing>
  <wsp:Policy/>
</wsam:Addressing>

Example 3: Possible Policy assertion for @Addressing(responses=Responses.NON ANONYMOUS) in the generated WSDL

1
2
3
4
5
<wsam:Addressing wsp:Optional="true">
  <wsp:Policy>
    <wsam:NonAnonymousResponses/>
  </wsp:Policy>
</wsam:Addressing>

4. Client APIs

This chapter describes the standard APIs provided for client side use of Jakarta XML Web Services. These APIs allow a client to create proxies for remote service endpoints and dynamically construct operation invocations.

Conformance requirements in this chapter use the term 'implementation' to refer to a client side Jakarta XML Web Services runtime system.

4.1. jakarta.xml.ws.Service

Service is an abstraction that represents a WSDL service. A WSDL service is a collection of related ports, each of which consists of a port type bound to a particular protocol and available at a particular endpoint address.

Service instances are created as described in Section 4.1.1, “Service Usage”. Service instances provide facilities to:

  • Create an instance of a proxy via one of the getPort methods. See Section 4.2.3, “Proxies” for information on proxies.

  • Create a Dispatch instance via the createDispatch method. See Section 4.3, “jakarta.xml.ws.Dispatch” for information on the Dispatch interface.

  • Create a new port via the addPort method. 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.

  • Configure per-service, per-port, and per-protocol message handlers using a handler resolver (see Section 4.1.3, “Handler Resolver”).

  • Configure the java.util.concurrent.Executor to be used for asynchronous invocations (see Section 4.1.4, “Executor”).

Conformance (Service completeness): A Service implementation MUST be capable of creating proxies, Dispatch instances, and new ports.

All the service methods except the static create methods and the constructors delegate to jakarta.xml.ws.spi.ServiceDelegate, see Section 6.3, “jakarta.xml.ws.spi.ServiceDelegate”.

4.1.1. Service Usage

4.1.1.1. Dynamic case

In the dynamic case, when nothing is generated, a Java SE service client uses Service.create to create Service instances, the following code illustrates this process.

1
2
3
URL wsdlLocation = new URL("http://example.org/my.wsdl");
QName serviceName = new QName("http://example.org/sample", "MyService");
Service s = Service.create(wsdlLocation, serviceName);

The following create methods may be used:

create(URL wsdlLocation, QName serviceName)

Returns a service object for the specified WSDL document and service name.

create(QName serviceName)

Returns a service object for a service with the given name. No WSDL document is attached to the service.

create(URL wsdlLocation, QName serviceName, WebServiceFeature …​ features)

Returns a service object for the specified WSDL document and service name. The created service needs to be configured with the web service features.

create(QName serviceName, WebServiceFeature …​ features)

Returns a service object for a service with the given name. No WSDL document is attached to the service. The created service needs to be configured with the web service features.

Conformance (Service Creation Failure): If a create method fails to create a service object, it MUST throw WebServiceException. The cause of that exception SHOULD be set to an exception that provides more information on the cause of the error (e.g. an IOException).

Conformance (Service creation using features): The created service object MUST honor the web service features. If a Jakarta XML Web Services implementation doesn’t understand any passed-in feature, it MUST throw WebServiceException.

4.1.1.2. Static case

When starting from a WSDL document, a concrete service implementation class MUST be generated as defined in Section 2.7, “Service and Port”. The generated implementation class MUST have all the public constructors as shown in the example below.

When using the constructors, the default WSDL location and service name are implicitly taken from the WebServiceClient annotation that decorates the generated class.

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
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
// Generated Service Class
@WebServiceClient(name="StockQuoteService",
                  targetNamespace="http://example.com/stocks",
                  wsdlLocation="http://example.com/stocks.wsdl")
public class StockQuoteService extends jakarta.xml.ws.Service {
    public StockQuoteService() {
        super(new URL("http://example.com/stocks.wsdl"),
              new QName("http://example.com/stocks", "StockQuoteService"));
    }

    public StockQuoteService(WebServiceFeature ... features) {
        super(new URL("http://example.com/stocks.wsdl"),
              new QName("http://example.com/stocks", "StockQuoteService"),
              features);
    }

    public StockQuoteService(URL wsdlLocation) {
        super(wsdlLocation,
              new QName("http://example.com/stocks", "StockQuoteService"));
    }

    public StockQuoteService(URL wsdlLocation, WebServiceFeature ... features) {
        super(wsdlLocation,
              new QName("http://example.com/stocks", "StockQuoteService"),
              features);
    }

    public StockQuoteService(URL wsdlLocation, QName serviceName) {
        super(wsdlLocation, serviceName);
    }

    public StockQuoteService(URL wsdlLocation, QName serviceName,
                             WebServiceFeature ... features) {
        super(wsdlLocation, serviceName, features);
    }

    ...
}

4.1.2. Provider and Service Delegate

Internally, the Service class delegates all of its functionality to a ServiceDelegate object, which is part of the SPI used to allow pluggability of implementations.

For this to work, every Service object internally MUST hold a reference to a jakarta.xml.ws.spi.ServiceDelegate object (see Section 6.3, “jakarta.xml.ws.spi.ServiceDelegate”) to which it delegates every non-static method call. The field used to hold the reference MUST be private.

The delegate is set when a new Service instance is created, which must necessarily happen when the protected, two-argument constructor defined on the Service class is called. The constructor MUST obtain a Provider instance (see Section 6.2.2, “Creating Endpoint Objects”) and call its createServiceDelegate method, passing the two arguments received from its caller and the class object for the instance being created (i.e. this.getClass()).

In order to ensure that the delegate is properly constructed, the static create method defined on the Service class MUST call the protected constructor to create a new service instance, passing the same arguments that it received from the application.

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
public class Service {

    private ServiceDelegate delegate;

    protected Service(java.net.URL wsdlDocumentLocation,
                      QName serviceName) {
        delegate = Provider.provider()
                           .createServiceDelegate(wsdlDocumentLocation
                                                  serviceName,
                                                  this.getClass());
    }

    public static Service create(java.net.URL wsdlDocumentLocation,
                                 QName serviceName) {
        return new Service(wsdlDocumentLocation, serviceName);
    }

    // begin delegated methods
    public <T> T getPort(Class<T> serviceEndpointInterface) {
        return delegate.getPort(serviceEndpointInterface);
    }

    ...
}

4.1.3. Handler Resolver

Jakarta XML Web Services provides a flexible plug-in framework for message processing modules, known as handlers, that may be used to extend the capabilities of a Jakarta XML Web Services runtime system. Chapter 10, Handler Framework describes the handler framework in detail. 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 per-service, per-port or per-protocol binding basis.

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. Subsequent changes to the handler resolver configured for a Service instance do not affect the handlers on previously created proxies, or Dispatch instances.

4.1.4. Executor

Service instances can be configured with a java.util.concurrent.Executor. The executor will then be used to invoke any asynchronous callbacks requested by the application. The setExecutor and getExecutor methods of Service can be used to modify and retrieve the executor configured for a service.

Conformance (Use of Executor): If an executor object is successfully configured for use by a Service via the setExecutor method, 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, if any.

Conformance (Default Executor): Lacking an application-specified executor, an implementation MUST use its own executor, a java.util.concurrent.ThreadPoolExecutor or analogous mechanism, to deliver callbacks. An implementation MUST NOT use application-provided threads to deliver callbacks, e.g. by "borrowing" them when the application invokes a remote operation.

4.2. jakarta.xml.ws.BindingProvider

The BindingProvider interface represents a component that provides a protocol binding for use by clients, it is implemented by proxies and is extended by the Dispatch interface. Figure 1, “Binding Provider Class Relationships” illustrates the class relationships.

bindingprovider
Figure 1. Binding Provider Class Relationships

A web service client can get an jakarta.xml.ws.EndpointReference from a BindingProvider instance that will reference the target endpoint.

Conformance (jakarta.xml.ws.BindingProvider.getEndpointReference): An implementation MUST be able to return an jakarta.xml.ws.EndpointReference for the target endpoint if a SOAP binding is being used. If the BindingProvider instance has a binding that is either SOAP 1.1/HTTP or SOAP 1.2/HTTP, then a W3CEndpointReference MUST be returned. If the binding is XML/HTTP an java.lang.UnsupportedOperationException MUST be thrown.

Conformance (BindingProvider’s W3CEndpointReference): The returned W3CEndpointReference MUST contain wsam:ServiceName and wsam:ServiceName[@EndpointName] as per Addressing 1.0 - Metadata[27]. The wsam:InterfaceName MAY be present in the W3CEndpointReference. If there is an associated WSDL, then the WSDL location MUST be referenced using wsdli:wsdlLocation in the W3CEndpointReference’s wsa:Metadata.

The BindingProvider interface provides methods to obtain the Binding and to manipulate the binding providers context. Further details on Binding can be found in Section 6.1, “jakarta.xml.ws.Binding”. The following subsection describes the function and use of context with BindingProvider instances.

4.2.1. Configuration

Additional metadata is often required to control information exchanges, this metadata forms the context of an exchange.

A BindingProvider instance maintains separate contexts for the request and response phases of a message exchange with a service:

Request

The contents of the request context are used to initialize the message context (see Section 10.4.1, “jakarta.xml.ws.handler.MessageContext”) prior to invoking any handlers (see Chapter 10, Handler Framework) 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 10, Handler Framework) 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.

4.2.1.1. Standard Properties

Table 2, “Standard BindingProvider properties” 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 2. Standard BindingProvider properties
Name Type Mandatory Description

jakarta.xml.ws.service.endpoint

.address

String

Y

The address of the service endpoint as a protocol specific URI. The URI scheme must match the protocol binding in use.

jakarta.xml.ws.security.auth

.username

String

Y

Username for HTTP basic authentication.

.password

String

Y

Password for HTTP basic authentication.

jakarta.xml.ws.session

.maintain

Boolean

Y

Used by a client to indicate whether it is prepared to participate in a service endpoint initiated session. The default value is false.

jakarta.xml.ws.soap.http.soapaction

.use

Boolean

N

Controls whether the SOAPAction HTTP header is used in SOAP/HTTP requests. Default value is false.

.uri

String

N

The value of the SOAPAction HTTP header if the jakarta.xml.ws.soap.http.soapaction.use property is set to true . Default value is an empty string.

Conformance (Required BindingProvider properties): An implementation MUST support all properties shown as mandatory in Table 2, “Standard BindingProvider properties”.

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 2, “Standard BindingProvider properties”.

4.2.1.2. Additional Properties

Conformance (Additional context properties): Implementations MAY define additional implementation specific properties not listed in Table 2, “Standard BindingProvider properties”. The java.* and javax.* namespaces are reserved for use by Java specifications.

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 Section 2.3.4, “Asynchrony” and Section 4.3.3, “Asynchronous Response” 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 Section 4.1.4, “Executor” 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. Proxy instances are not guaranteed to be thread safe. If the instances are accessed by multiple threads, usual synchronization techniques can be used to support multiple threads.

Conformance (Proxy support): An implementation MUST support proxies.

Conformance (Implementing BindingProvider): An instance of a proxy MUST implement jakarta.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 during invocations on the endpoint. The epr MUST NOT be used as the value of any addressing header such as wsa:ReplyTo. The specified features MUST be enabled/disabled and configured as specified. Any Jakarta XML Web Services supported epr metadata MUST match the Service instance’s ServiceName, otherwise a WebServiceExeption MUST be thrown. Any Jakarta XML Web Services supported epr metadata MUST match the PortName for the sei, otherwise a WebServiceException MUST be thrown. If the Service instance has an associated WSDL, its WSDL MUST be used to determine any binding information, any WSDL in a Jakarta XML Web Services suppported epr metadata MUST be ignored. If the Service instance does not have a WSDL, then any WSDL inlined in the Jakarta XML Web Services supported metadata of the epr MUST be used to determine binding information. If there is not enough metadata in the Service instance or in the epr metadata to determine a port, then a WebServiceException MUST be thrown.

The serviceEndpointInterface parameter specifies the interface that will be implemented by the proxy. The service endpoint interface provided by the client needs to conform to the WSDL to Java mapping rules specified in Chapter 2, WSDL 1.1 to Java Mapping. 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.

Conformance (Service.getPort failure): If creation of a proxy fails, an implementation MUST throw jakarta.xml.ws.WebServiceException. The cause of that exception SHOULD be set to an exception that provides more information on the cause of the error (e.g. an IOException).

The use of WS-Addressing requirements can be indicated in a WSDL as per Addressing 1.0 - Metadata[27]. A proxy created using getPort() calls is configured with the addressing requirements as specified in the associated WSDL or explicitly passing jakarta.xml.ws.soap.AddressingFeature web service feature.

Conformance (Proxy’s Addressing use): A proxy MUST be configured with the use of addressing requirements as indicated in the associated WSDL. But if the proxy is created using jakarta.xml.ws.soap.AddressingFeature web service feature, the feature’s addressing requirements MUST take precedence over WSDL’s addressing requirements.

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.g., lazy and eager validation are both acceptable).

4.2.3.1. Example

The following example shows the use of a proxy to invoke a method (getLastTradePrice) on a service endpoint interface (com.example.StockQuoteProvider). Note that no statically generated stub class is involved.

1
2
3
4
5
6
7
jakarta.xml.ws.Service service = ...;
com.example.StockQuoteProvider proxy = service.getPort(portName,
    com.example.StockQuoteProvider.class)
jakarta.xml.ws.BindingProvider bp = (jakarta.xml.ws.BindingProvider) proxy;
Map<String,Object> context = bp.getRequestContext();
context.setProperty("jakarta.xml.ws.session.maintain", Boolean.TRUE);
proxy.getLastTradePrice("ACME");

Lines 1–3 show how the proxy is created. Lines 4–6 perform some configuration of the proxy. Lines 7 invokes a method on the proxy.

4.2.4. Exceptions

All methods of an SEI can throw jakarta.xml.ws.WebServiceException and zero or more service specific exceptions.

Conformance (Remote Exceptions): If an error occurs during a remote operation invocation, an implemention MUST throw a service specific exception if possible. If the error cannot be mapped to a service specific exception, an implementation MUST throw a ProtocolException or one of its subclasses, as appropriate for the binding in use. See Section 6.4.1, “Protocol Specific Exception Handling” for more details.

Conformance (Exceptions During Handler Processing): Exceptions thrown during handler processing on the client MUST be passed on to the application. If the exception in question is a subclass of WebServiceException then an implementation MUST rethrow it as-is, without any additional wrapping, otherwise it MUST throw a WebServiceException whose cause is set to the exception that was thrown during handler processing.

Conformance (Other Exceptions): For all other errors, i.e. all those that don’t occur as part of a remote invocation or handler processing, an implementation MUST throw a WebServiceException whose cause is the original local exception that was thrown, if any.

For instance, an error in the configuration of a proxy instance may result in a WebServiceException whose cause is a java.lang.IllegalArgumentException thrown by some implementation code.

4.3. jakarta.xml.ws.Dispatch

XML Web Services use XML messages for communication between services and service clients. The higher level Jakarta XML Web Services APIs are designed to hide the details of converting between Java method invocations and the corresponding XML messages, but in some cases operating at the XML message level is desirable. The Dispatch interface provides support for this mode of interaction.

Conformance (Dispatch support): Implementations MUST support the jakarta.xml.ws.Dispatch interface.

Dispatch supports two usage modes, identified by the constants jakarta.xml.ws.Service.Mode.MESSAGE and jakarta.xml.ws.Service.Mode.PAYLOAD respectively:

Message

In this mode, client applications work directly with protocol-specific message structures. E.g., when used with a SOAP protocol binding, a client application would work directly with a SOAP message.

Message Payload

In this mode, client applications work with the payload of messages rather than the messages themselves. E.g., when used with a SOAP protocol binding, a client application would work with the contents of the SOAP Body rather than the SOAP message as a whole.

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. Dispatch is a generic class that supports input and output of messages or message payloads of any type. Implementations are required to support the following types of object:

javax.xml.transform.Source

Use of Source objects allows clients to use XML generating and consuming APIs directly. Source objects may be used with any protocol binding in either message or message payload mode. When used with the HTTP binding (see Chapter 12, HTTP Binding) in payload mode, the HTTP request and response entity bodies must contain XML directly or a MIME wrapper with an XML root part. A null value for Source is allowed to make it possible to invoke an HTTP GET method in the HTTP Binding case. A WebServiceException MUST be thrown when a Dispatch<Source> is invoked and the Service returns a MIME message. When used in message mode, if the message is not an XML message a WebServiceException MUST be thrown.

Jakarta XML Binding Objects

Use of Jakarta XML Binding allows clients to use Jakarta XML Binding objects generated from an XML Schema to create and manipulate XML representations and to use these objects with Jakarta XML Web Services without requiring an intermediate XML serialization. Jakarta XML Binding objects may be used with any protocol binding in either message or message payload mode. When used with the HTTP binding (see Chapter 12, HTTP Binding) in payload mode, the HTTP request and response entity bodies must contain XML directly or a MIME wrapper with an XML root part. When used in mssage mode, if the message is not an XML message a WebServiceException MUST be thrown.

jakarta.xml.soap.SOAPMessage

Use of SOAPMessage objects allows clients to work with SOAP messages using the convenience features provided by the jakarta.xml.soap package. SOAPMessage objects may only be used with Dispatch instances that use the SOAP binding (see Chapter 11, SOAP Binding) in message mode.

jakarta.activation.DataSource

Use of DataSource objects allows clients to work with MIME-typed messages. DataSource objects may only be used with Dispatch instances that use the HTTP binding (see Chapter 12, HTTP Binding) in message mode.

A Jakarta XML Web Services implementation MUST honor all WebServiceFeatures (Section 6.5, “jakarta.xml.ws.WebServiceFeature”) for Dispatch based applications.

4.3.1. Configuration

Dispatch instances are obtained using the createDispatch factory methods of a Service instance. The mode parameter of createDispatch controls whether the new Dispatch instance is message or message payload oriented. The type parameter controls the type of object used for messages or message payloads. Dispatch instances are not thread safe.

Dispatch instances are not required to be dynamically configurable for different protocol bindings; the WSDL binding from which the Dispatch instance is generated contains static information including the protocol binding and service endpoint address. However, 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.2.1.1, “Standard Properties” for a list of standard properties.

4.3.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.

Asynchronous request response (invokeAsync methods)

The method returns immediately, any results are provided either through a callback or via a polling object.

One-way (invokeOneWay methods)

The method is logically non-blocking, subject to the capabilities of the underlying protocol, no results are returned.

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, message mode and the MEP. So for example when using -

  • SOAP 1.1 / HTTP binding in payload mode using null will send a soap message with an empty body.

  • SOAP 1.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 (Failed Dispatch.invoke): When an operation is invoked using an invoke method, 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.

Conformance (Failed Dispatch.invokeAsync): When an operation is invoked using an invokeAsync method, an implementation MUST throw a WebServiceException if there is any error in the configuration of the Dispatch instance. Errors that occur during the invocation are reported when the client attempts to retrieve the results of the operation.

Conformance (Failed Dispatch.invokeOneWay): When an operation is invoked using an invokeOneWay method, an implementation MUST throw a WebServiceException if there is any error in the configuration of the Dispatch instance or if an error is detected[7] during the remote operation invocation.

See Section 11.4.1, “HTTP” for additional SOAP/HTTP requirements.

4.3.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.

Callback

The client supplies an AsyncHandler (see below) and the runtime calls the handleResponse method when the results of the operation are available. The invokeAsync method returns a wildcard Future (Future<?>) that may be polled to determine when the operation has completed. The object returned from Future<?>.get() has no standard type. Client code should not attempt to cast the object to any particular type as this will result in non-portable behavior.

In both cases, errors that occur during the invocation are reported via an exception when the client attempts to retrieve the results of the operation.

Conformance (Reporting asynchronous errors): If the operation invocation fails, an implementation MUST throw a java.util.concurrent.ExecutionException from the Response.get method.

The cause of an ExecutionException is the original exception raised. In the case of a Response instance this can only be a WebServiceException or one of its subclasses.

The following interfaces are used to obtain the results of an operation invocation:

jakarta.xml.ws.Response

A generic interface that is used to group the results of an invocation with the response context. Response extends java.util.concurrent.Future<T> to provide asynchronous result polling capabilities.

jakarta.xml.ws.AsyncHandler

A generic interface that clients implement to receive results in an asynchronous callback. It defines a single handleResponse method that has a Response object as its argument.

4.3.4. Using Jakarta XML Binding

Service provides a createDispatch factory method for creating Dispatch instances that contain an embedded JAXBContext. The context parameter contains the JAXBContext instance that the created Dispatch instance will use to marshall and unmarshall messages or message payloads.

Conformance (Marshalling failure): If an error occurs when using the supplied JAXBContext to marshall a request or unmarshall a response, an implementation MUST throw a WebServiceException whose cause is set to the original JAXBException.

4.3.5. Examples

The following examples demonstrate use of Dispatch methods in the synchronous, asynchronous polling, and asynchronous callback modes. For ease of reading, error handling has been omitted.

4.3.5.1. Synchronous, Payload-Oriented
1
2
3
4
5
Source reqMsg = ...;
Service service = ...;
Dispatch<Source> disp = service.createDispatch(portName,
    Source.class, PAYLOAD);
Source resMsg = disp.invoke(reqMsg);
4.3.5.2. Synchronous, Message-Oriented
1
2
3
4
5
SOAPMessage soapReqMsg = ...;
Service service = ...;
Dispatch<SOAPMessage> disp = service.createDispatch(portName,
    SOAPMessage.class, MESSAGE);
SOAPMessage soapResMsg = disp.invoke(soapReqMsg);
4.3.5.3. Synchronous, Payload-Oriented With Jakarta XML Binding Objects
1
2
3
4
5
6
7
JAXBContext jc = JAXBContext.newInstance("primer.po");
Unmarshaller u = jc.createUnmarshaller();
PurchaseOrder po = (PurchaseOrder) u.unmarshal(
    new FileInputStream("po.xml"));
Service service = ...;
Dispatch<Object> disp = service.createDispatch(portName, jc, PAYLOAD);
OrderConfirmation conf = (OrderConfirmation) disp.invoke(po);

In the above example PurchaseOrder and OrderConfirmation are interfaces pre-generated by Jakarta XML Binding from the schema document 'primer.po'.

4.3.5.4. Asynchronous, Polling, Message-Oriented
1
2
3
4
5
6
7
8
9
SOAPMessage soapReqMsg = ...;
Service service = ...;
Dispatch<SOAPMessage> disp = service.createDispatch(portName,
    SOAPMessage.class, MESSAGE);
Response<SOAPMessage> res = disp.invokeAsync(soapReqMsg);
while (!res.isDone()) {
    // do something while we wait
}
SOAPMessage soapResMsg = res.get();
4.3.5.5. Asynchronous, Callback, Payload-Oriented
1
2
3
4
5
6
7
8
9
10
11
12
13
14
class MyHandler implements AsyncHandler<Source> {
    ...
    public void handleResponse(Response<Source> res) {
        Source resMsg = res.get();
        // do something with the results
    }
}

Source reqMsg = ...;
Service service = ...;
Dispatch<Source> disp = service.createDispatch(portName,
    Source.class, PAYLOAD);
MyHandler handler = new MyHandler();
disp.invokeAsync(reqMsg, handler);

4.4. Catalog Facility

Jakarta XML Web Services 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, specifically WSDL and XML Schema documents.

The facility in question is the OASIS XML Catalogs 1.1 specification [34]. 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.

  • Mapping the URI reference of a resource to another URI reference.

Using the entity catalog, an application can package one or more description and/or schema documents in jar files, avoiding costly remote accesses, or remap remote URIs to other, possibly local ones. Since the catalog is an XML document, a deployer can easily alter it to suit the local environment, unbeknownst to the application code.

The catalog is assembled by taking into account all accessible resources whose name is META-INF/jax-ws-catalog.xml. Each resource MUST be a valid entity catalog according to the XML Catalogs 1.1 specification. When running on the Java SE platform, the current context class loader MUST be used to retrieve all the resources with the specified name. Relative URIs inside a catalog file are relative to the location of the catalog that contains them.

Conformance (Use of the Catalog): In the process of resolving a URI that points to a WSDL document or any document reachable from it, a Jakarta XML Web Services implementation MUST perform a URI resolution for it, as prescribed by the XML Catalogs 1.1 specification, using the catalog defined above as its entity catalog.

In particular, every Jakarta XML Web Services 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.

Although defined in the client API chapter for reasons of ease of exposure, use of the catalog is in no way restricted to client uses of WSDL location URIs. In particular, resolutions of URIs to WSDL and schema documents that arise during the publishing of the contract for an endpoint (see Section 5.2.5, “Determining the Contract for an Endpoint”) are subject to the requirements in this section, resulting in catalog-based URI resolutions.

4.5. jakarta.xml.ws.EndpointReference

A jakarta.xml.ws.EndpointReference is an abstraction that represents an invocable web service endpoint. 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 EndpointReference class delegates to the jakarta.xml.ws.spi.Provider to perform the getPort operation. The following method can be used to get a proxy for a Port.

getPort(Class<T> serviceEndpointInterface, WebServiceFeature…​ features)

Gets a proxy for the serviceEndpointInterface that can be used to invoke operations on the endpoint referred to by the EndpointReference instance. The specified features MUST be enabled/disabled and configured as specified. The returned proxy MUST use the EndpointReference instance to determine the endpoint address and any reference parameters to be sent on endpoint invocations. The EndpointReference instance MUST NOT be used directly as the value of an WS-Addressing header such as wsa:ReplyTo. 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.

5. Service APIs

This chapter describes requirements on Jakarta XML Web Services service implementations and standard APIs provided for their use.

5.1. jakarta.xml.ws.Provider

Jakarta XML Web Services services typically implement a native Java service endpoint interface (SEI), perhaps mapped from a WSDL port type, either directly or via the use of annotations. Section 3.4, “Interface” describes the requirements that a Java interface must meet to qualify as a Jakarta XML Web Services SEI. Section 2.2, “Port Type” describes the mapping from a WSDL port type to an equivalent Java SEI.

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. However, in some cases it is desirable for services to be able to operate at the XML message level. The Provider interface offers an alternative to SEIs and may be implemented by services wishing to work at the XML message level.

Conformance (Provider support required): An implementation MUST support Provider<Source> in payload mode with all the predefined bindings. It MUST also support Provider<SOAPMessage> in message mode in conjunction with the predefined SOAP bindings and Provider<jakarta.activation.DataSource> in message mode in conjunction with the predefined HTTP binding.

Conformance (Provider default constructor): A Provider based service endpoint implementation MUST provide a public default constructor.

An empty Source payload can be used in payload mode to send a response with no payload. An empty source can be constructed using zero-argument default constructors of DOMSource, SAXSource, and StreamSource.

A typed Provider interface is one in which the type parameter has been bound to a concrete class, e.g. Provider<Source> or Provider<SOAPMessage>, as opposed to being left unbound, as in Provider<T>.

Conformance (Provider implementation): A Provider based service endpoint implementation MUST implement a typed Provider interface.

Conformance (WebServiceProvider annotation): A Provider based service endpoint implementation MUST carry a WebServiceProvider annotation (see Section 8.7, “jakarta.xml.ws.WebServiceProvider”).

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. The generic nature of Provider allows use with a variety of message object types.

A Jakarta XML Web Services implementation MUST honor all WebServiceFeatures (Section 6.5, “jakarta.xml.ws.WebServiceFeature”) for Provider based applications.

5.1.1. Invocation

A Provider based service instance’s invoke method is called for each message received for the service. When an invoke method returns null, it is considered that no response needs to be sent by service.

5.1.1.1. Exceptions

The service runtime is required to catch exceptions thrown by a Provider instance. A Provider instance may make use of the protocol specific exception handling mechanism as described in Section 6.4.1, “Protocol Specific Exception Handling”. 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.

5.1.2. Configuration

The ServiceMode annotation is used to configure the messaging mode of a Provider instance. Use of @ServiceMode(value=MESSAGE) indicates that the provider instance wishes to receive and send entire protocol messages (e.g. a SOAP message when using the SOAP binding); absence of the annotation or use of @ServiceMode(value=PAYLOAD) indicates that the provider instance wishes to receive and send message payloads only (e.g. the contents of a SOAP Body element when using the SOAP binding).

Provider instances MAY use the WebServiceContext facility (see Section 5.3, “jakarta.xml.ws.WebServiceContext”) to access the message context and other information about the request currently being served.

The Jakarta XML Web Services runtime makes certain properties available to a Provider instance that can be used to determine its configuration. These properties are passed to the Provider instance each time it is invoked using the MessageContext instance accessible from the WebServiceContext.

5.1.3. Examples

For brevity, error handling is omitted in the following examples.

16. Simple echo service, reply message is the same as the input message
1
2
3
4
5
6
7
8
9
10
@WebServiceProvider
@ServiceMode(value=Service.Mode.MESSAGE)
public class MyService implements Provider<SOAPMessage> {
    public MyService() {
    }

    public SOAPMessage invoke(SOAPMessage request) {
        return request;
    }
}
17. Simple static reply, 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.Mode.PAYLOAD)
public class MyService implements Provider<Source> {
    public MyService() {
    }

    public Source invoke(Source request) {
        Source requestPayload = request.getPayload();
        ...
        String replyElement = "<n:ack xmlns:n=’...’/>";
        StreamSource reply = new StreamSource(new StringReader(replyElement));
        return reply;
    }
}
18. Using Jakarta XML Binding 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.Mode.PAYLOAD)
public class MyService implements Provider<Source> {
    public MyService() {
    }

    public Source invoke(Source request) {
        JAXBContent jc = JAXBContext.newInstance(...);
        Unmarshaller u = jc.createUnmarshaller();
        Object requestObj = u.unmarshall(request);
        ...
        Acknowledgement reply = new Acknowledgement(...);
        return new JAXBSource(jc, reply);
    }
}

5.2. jakarta.xml.ws.Endpoint

The Endpoint class can be used to create and publish Web service endpoints.

An endpoint consists of an object that acts as the Web service implementation (called here implementor) plus some configuration information, e.g. a Binding. Implementor and binding are set when the endpoint is created and cannot be modified later. Their values can be retrieved using the getImplementor and getBinding methods respectively. Other configuration information may be set at any time after the creation of an Endpoint but before its publication.

5.2.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. If the implementor specifies a binding using the jakarta.xml.ws.BindingType annotation it MUST be used else a default binding of SOAP 1.1 / HTTP binding MUST be used.

create(Object implementor, WebServiceFeature …​ features)

Same as the above create() method. The created Endpoint is configured with the web service features. These features override the corresponding features that are specified in WSDL, if present.

create(String bindingID, Object implementor)

Creates and returns an Endpoint for the specified binding and implementor. If the bindingID is null and no binding information is specified via the jakarta.xml.ws.BindingType annotation then a default SOAP 1.1 / HTTP binding MUST be used.

create(String bindingID, Object implementor, WebServiceFeature …​ features)

Same as the above create() method. The created Endpoint is configured with the web service features. These features override the corresponding features that are specified in WSDL, if present.

publish(String address, Object implementor)

Creates and publishes an Endpoint for the given implementor. The binding is chosen by default based on the URL scheme of the provided address (which must be a URL). If a suitable binding if found, the endpoint is created then published as if the Endpoint.publish(String address) method had been called. The created Endpoint is then returned as the value of the method.

publish(String address, Object implementor, WebServiceFeature …​ features)

Same as the above publish() method. The created Endpoint is configured with the web service features. These features override the corresponding features that are specified in WSDL, if present.

These methods MUST delegate the creation of Endpoint to the jakarta.xml.ws.spi.Provider SPI class (see Section 6.2, “jakarta.xml.ws.spi.Provider”) by calling the createEndpoint and createAndPublishEndpoint methods respectively.

An implementor object MUST be either an instance of a class annotated with the @WebService annotation according to the rules in Chapter 3, Java to WSDL 1.1 Mapping or an instance of a class annotated with the WebServiceProvider annotation and implementing the Provider interface (see Section 5.1, “jakarta.xml.ws.Provider”).

The publish(String,Object) method is provided as a shortcut for the common operation of creating and publishing an Endpoint. 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();
Endpoint e = Endpoint.publish("http://localhost:8080/test", test);

Conformance (Endpoint publish(String address, 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, then invoking the publish(String address) method on the resulting endpoint.

Conformance (Default Endpoint Binding): In the absence of a specified binding, if the URL scheme for the address argument of the Endpoint.publish method is "http" or "https" then an implementation MUST use the SOAP 1.1/HTTP binding (see Chapter 11, SOAP Binding) as the binding for the newly created endpoint.

Conformance (Other Bindings): An implementation MAY support using the Endpoint.publish method with addresses whose URL scheme is neither "http" nor "https".

The success of the Endpoint.publish method is conditional to the presence of the appropriate permission as described in Section 5.2.3, “Publishing Permission”.

Endpoint implementors MAY use the WebServiceContext facility (see Section 5.3, “jakarta.xml.ws.WebServiceContext”) to access the message context and other information about the request currently being served. Injection of the WebServiceContext, if requested, MUST happen the first time the endpoint is published. After any injections have been performed and before any requests are dispatched to the implementor, the implementor method which carries a jakarta.annotation.PostConstruct annotation, if present, MUST be invoked. Such a method MUST satisfy the requirements for lifecycle methods in Jakarta Annotations [35].

5.2.2. Publishing

An Endpoint is in one of three states: not published (the default), published or stopped. Published endpoints are active and capable of receiving incoming requests and dispatching them to their implementor. Non published endpoints are inactive. Stopped endpoint were in the published until some time ago, then got stopped. Stopped endpoints cannot be published again. 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). The address MUST use a URL scheme compatible with the endpoint’s binding.

publish(Object serverContext)

Publishes the endpoint using the specified server context. The server context MUST contain address information for the resulting endpoint and it MUST be compatible with the endpoint’s binding.

Conformance (Publishing over HTTP): If the Binding for an Endpoint is a SOAP (see Chapter 11, SOAP Binding) or HTTP (see Chapter 12, HTTP Binding) binding, then an implementation MUST support publishing the Endpoint to a URL whose scheme is either "http" or "https".

The WSDL contract for an endpoint is created dynamically based on the annotations on the implementor class, the Binding in use and the set of metadata documents specified on the endpoint (see Section 5.2.4, “Endpoint Metadata”).

Conformance (WSDL Publishing): An Endpoint that uses the SOAP 1.1/HTTP binding (see Chapter 11, SOAP Binding) MUST make its contract available as a WSDL 1.1 document at the publishing address suffixed with "?WSDL" or "?wsdl".

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. 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 success of the two Endpoint.publish methods described above is conditional to the presence of the appropriate permission as described in Section 5.2.3, “Publishing Permission”.

Applications that wish to modify the configuration information (e.g. the metadata) for an Endpoint must make sure the latter is in the not-published state. 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, the changes they entail may not be reflected on the endpoint until the next time it is published. In other words, the effects of configuration changes on a currently published endpoint are undefined.

The stop method can be used to stop publishing an endpoint. A stopped endpoint may not be restarted. It is an error to invoke a publish method on a stopped endpoint. After the stop method returns, the runtime MUST NOT dispatch any further invocations to the endpoint’s implementor.

An Endpoint will be typically invoked to serve concurrent requests, so its implementor should be written so as to support multiple threads. The synchronized keyword may be used as usual to control access to critical sections of code. For finer control over the threads used to dispatch incoming requests, an application can directly set the executor to be used, as described in Section 5.2.7, “Executor”.

5.2.2.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.

1
2
3
4
5
6
7
8
// assume Test is an endpoint implementation class annotated with @WebService
Test test = new Test();
HttpServer server = HttpServer.create(new InetSocketAddress(8080),10);
server.setExecutor(Executor.newFixedThreadPool(10));
server.start();
HttpContext context = server.createContext("/test");
Endpoint endpoint = Endpoint.create(SOAPBinding.SOAP11HTTP_BINDING, test);
endpoint.publish(context);

Note that the specified server context uses its own executor mechanism. At runtime then, any other executor set on the Endpoint instance would be ignored by the Jakarta XML Web Services implementation.

5.2.3. Publishing Permission

For security reasons, administrators may want to restrict the ability of applications to publish Web service endpoints. To this end, Jakarta XML Web Services defines a new permission class, jakarta.xml.ws.WebServicePermission, and one named permission, publishEndpoint.

Conformance (Checking publishEndpoint Permission): When any of the publish methods defined by the Endpoint class are invoked, an implementation MUST check whether a SecurityManager is installed with the application. If it is, implementations MUST verify that the application has the WebServicePermission identified by the target name publishEndpoint before proceeding. If the permission is not granted, implementations MUST NOT publish the endpoint and they MUST throw a java.lang.SecurityException.

5.2.4. Endpoint Metadata

A set of metadata documents can be associated with an Endpoint by means of the setMetadata(List<Source>) method. By setting the metadata of an Endpoint, an application can bypass the automatic generation of the endpoint’s contract and specify the desired contract directly. This way it is possible, e.g., 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 Chapter 8, Annotations).

Conformance (Required Metadata Types): An implementation MUST support WSDL 1.1 and XML Schema 1.0 documents as metadata.

Conformance (Unknown Metadata): An implementation MUST ignore metadata documents whose type it does not recognize.

When specifying a list of documents as metadata, an application may need to establish references between them. For instance, a WSDL document may import one or more XML Schema documents. In order to do so, the application MUST use the systemId property of the javax.xml.transform.Source class by setting its value to an absolute URI that uniquely identifies it among all supplied metadata documents, then using the given URI in the appropriate construct (e.g. wsdl:import or xsd:import).

5.2.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.

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. If such an annotation element is present on the endpoint implementation class and has a value other than the default one (i.e. it is not the empty string), then a Jakarta XML Web Services implementation MUST use the document referred to from the wsdlLocation annotation element to determine the contract, according to the rules in Section 5.2.5.3, “Use of @WebService(wsdlLocation) and Metadata”.

In addition to the case in which the Endpoint API is explicitly used, the requirements in this section are also applicable to the publishing of an endpoint via declarative means, e.g. in a servlet container. In this case, there may not be an equivalent for the notion of metadata as described in Section 5.2.4, “Endpoint Metadata”. In such an occurrence, the rules in this section MUST be applied using an empty set of metadata documents as the metadata for the endpoint.

In the context of the Jakarta EE Platform, Jakarta Enterprise Web Services [17] defines deployment descriptor elements that may be used to override the value of the wsdlLocation annotation element. Please refer to that specification for more details.

As we specify additional rules to be used in determining the contract for an endpoint, we distinguish two cases: that of a SEI-based endpoint (i.e. an endpoint that is annotated with a WebService annotation) and that of a Provider-based endpoint.

5.2.5.1. SEI-based Endpoints

For publishing to succeed, a SEI-based endpoint MUST have an associated contract.

If the wsdlLocation annotation element is the empty string, then a Jakarta XML Web Services implementation must obey the following rules, depending on the binding used by the endpoint:

SOAP 1.1/HTTP Binding

A Jakarta XML Web Services implementation MUST generate a WSDL description for the endpoint based on the rules in Section 5.2.5.3, “Use of @WebService(wsdlLocation) and Metadata” below.

SOAP 1.2/HTTP Binding

A Jakarta XML Web Services implementation MUST NOT generate a WSDL description for the endpoint.

HTTP Binding

A Jakarta XML Web Services implementation MUST NOT generate a WSDL description for the endpoint.

Any Implementation-Specific Binding

A Jakarta XML Web Services implementation MAY generate a WSDL description for 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.

A generated contract MUST follow the rules in Chapter 3, Java to WSDL 1.1 Mapping and those in the Jakarta XML Binding specification [39].

5.2.5.2. Provider-based Endpoints

Provider-based endpoints SHOULD have a non-empty wsdlLocation pointing to a valid WSDL description of the endpoint.

If the wsdlLocation annotation element is the empty string, then a Jakarta XML Web Services implementation MUST NOT generate a WSDL description for the endpoint.

5.2.5.3. Use of @WebService(wsdlLocation) and Metadata

A WSDL document contains two different kinds of information: abstract information (i.e. portTypes and any schema-related information) which affects the format of the messages and the data being exchanged, and binding-related one (i.e. bindings and ports) which affects the choice of protocol and transport as well as the on-the-wire format of the messages. Annotations (see Chapter 8, Annotations) are provided to capture the former aspects but not the latter. (The @SOAPBinding annotation is a bit of a hybrid, because it captures the signature-related aspects of the soap:binding binding extension in WSDL 1.1.)

At runtime, annotations must be followed for all the abstract aspects of an interaction, but binding information has to come from somewhere else. Although the choice of binding is made at the time an endpoint is created, this specification does not attempt to capture all possible binding properties in its APIs, since the extensibility of WSDL would make it a futile exercise. Rather, when an endpoint is published, a description for it, if present, is consulted to determine binding information, using the wsdl:service and wsdl:port qualified names as a key.

In terms of priority, the description specified using the wsdlLocation annotation element, if present, comes first, and the metadata documents are secondary. In the absence of a non-empty, non-default wsdlLocation annotation element, the metadata documents are consulted to identify as many description components as possible that can be reused when producing the contract for the endpoint.

There are some restrictions on the packaging of the description and any associated metadata documents. The goal of these restrictions is to make it possible to publish an endpoint without forcing a Jakarta XML Web Services implementation to retrieve, store and patch multiple documents from potentially remote sites.

The value of the wsdlLocation annotation element on an endpoint implementation class, if any, MUST be a relative URL. The document it points to MUST be packaged with the application. Moreover, it MUST follow the requirements in Section 5.2.5.4, “Application-specified Service” below ("Application-specified Service").

In the Java SE platform, relative URLs are treated as resources. When running on the Jakarta EE platform, the dispositions in the Jakarta Enterprise Web Services specification apply.

For ease of identification, let’s call this document the "root description document", to distinguish it from any WSDL documents it might import.

At publishing time, a Jakarta XML Web Services implementation MUST patch the endpoint address in the root description document to match the actual address the endpoint is deployed at.

In order to state the requirements for patching the locations of any wsdl:import-ed or xsd:import-ed documents, let’s define a document as being local if and only if

  1. it is the root description document, or

  2. 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.e. a Source object which is a member of the list of metadata documents and whose systemId property is equal to the URL in question).

A Jakarta XML Web Services implementation MUST patch the location attributes of all wsdl:import and xsd:import statement in local documents that point to local documents. An implementation MUST NOT patch any other location attributes.

Please note that, although the catalog facility (see Section 4.4, “Catalog Facility”) 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, those absolute URLs will not be rewritten when the importing document is published, since documents resolved via the catalog are not considered local, even if the catalog maps them to resources packaged with the application.

In what follows, for better readability, the term "metadata document" should be interpreted as also covering the description document pointed to by the wsdlLocation annotation element (if any), while keeping in mind the processing rules in the preceding paragraphs.

As a guideline, the generated contract must reuse as much as possible the set of metadata documents provided by the application. In order to simplify an implementor’s task, this specification requires that only a small number of well-defined scenarios in which the application provides metadata documents be supported.

Implementations MAY support other use cases, but they MUST follow the general rule that any application-provided metadata element takes priority over an implementation-generated one, with the exception of the overriding of a port address.

For instance, if the application-provided metadata contains a definition for portType foo that in no case should the Jakarta XML Web Services implementation create its own foo portType to replace the one provided by the application in the final contract for the endpoint.

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, 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.

When publishing the main WSDL document for an endpoint, an implementation MUST ensure that all references between documents are correct and resolvable. This may require remapping the metadata documents to URLs different from those set as their systemId property. The renaming MUST be consistent, in that the "imports" and "includes" relationships existing between documents when the metadata was supplied to the endpoint MUST be respected at publishing time. Moreover, the same metadata document SHOULD NOT be published at multiple, different URLs.

When resolving URI references to other documents when processing metadata documents or any of the documents they may transitively reference, a Jakarta XML Web Services implementation MUST use the catalog facility defined in Section 4.4, “Catalog Facility”, except when there is a metadata document whose system id matches the URI in question. In other words, metadata documents have priority over catalog-based mappings.

The scenarios which are required to be supported are the following:

5.2.5.4. Application-specified Service

One of the metadata documents, say D, contains a definition for a WSDL service whose qualified name , say S, matches that specified by the endpoint being published. In this case, a Jakarta XML Web Services implementation MUST use D as the service description. No further generation of contract-related artifacts may occur.

Table 3. Standard Endpoint properties.
Name Type Description

jakarta.xml.ws.wsdl

.service

QName

Specifies the qualified name of the service.

.port

QName

Specifies the qualified name of the port.

The implementation MUST also override the port address in D and the location and schemaLocation attributes as detailed in the preceding paragraphs. It is an error if more than one metadata document contains a definition for the sought-after service S.

5.2.5.5. Application-specified PortType

No metadata document contains a definition for the sought-after service S, but a metadata document, say D, contains a definition for the WSDL portType whose qualified name, say P, matches that specified by the endpoint being published. In this case, a Jakarta XML Web Services implementation MUST create a new description for S, including an appropriate WSDL binding element referencing portType P. The metadata document D MUST be imported/included so that the published contract uses the definition of P provided by D. No schema generation occurs,as P is assumed to embed or import schema definitions for all the types/elements it requires. Like in the previous case, the implementation MUST override any location and schemaLocation attributes. It is an error if more than one metadata document contains a definition for the sought-after portType P.

5.2.5.6. Application-specified Schema or No Metadata

No metadata document contains a definition for the sought-after service S and portType P. In this case, a Jakarta XML Web Services implementation MUST generate a complete WSDL for S. When it comes to generating a schema for a certain target namespace, say T, the implementation MUST reuse the schema for T among the available metadata documents, if any. Like in the preceding case, the implementation MUST override any schemaLocation attributes. 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.

Note

The three scenarios described above cover several applicative use cases. The first one represents an application that has full control over all aspects of the contract. The Jakarta XML Web Services runtime just uses what the application provided, with a minimum of adjustments to ensure consistency. The second one corresponds to an application that defines all abstract aspects of the WSDL, i.e. portType(s) and schema(s), leaving up to the Jakarta XML Web Services runtime to generate the concrete portions of the contract. Finally, the third case represents an application that uses one or more well-known schema(s), possibly taking advantage of lots of facets/constraints that Jakarta XML Binding cannot capture, and wants to reuse it as-is, leaving all the WSDL-specific aspects of the contract up to the runtime. This use case also covers an application that does not specify any metadata, leaving WSDL and schema generation up to the Jakarta XML Web Services (and Jakarta XML Binding) implementation.

5.2.6. Endpoint Properties

An Endpoint has an associated set of properties that may be read and written using the getProperties and setProperties methods respectively.

Table 3, “Standard Endpoint properties.” lists the set of standard Endpoint properties.

When present, the WSDL-related properties override the values specified using the WebService and WebServiceProvider annotations. This functionality is most useful with provider objects (see Section 8.7, “jakarta.xml.ws.WebServiceProvider”), since the latter are naturally more suited to a more dynamic usage. For instance, 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.

5.2.7. Executor

Endpoint instances can be configured with a java.util.concurrent.Executor. The executor will then be used to dispatch any incoming requests to the application. The setExecutor and getExecutor methods of Endpoint can be used to modify and retrieve the executor configured for a service.

Conformance (Use of Executor): If an executor object is successfully set on an Endpoint via the setExecutor method, then an implementation MUST use it to dispatch incoming requests upon publication of the Endpoint by means of the publish(String address) method. If publishing is carried out using the publish(Object serverContext)) method, an implementation MAY use the specified executor or another one specific to the server context being used.

Conformance (Default Executor): If an executor has not been set on an Endpoint, an implementation MUST use its own executor, a java.util.concurrent.ThreadPoolExecutor or analogous mechanism, to dispatch incoming requests.

5.2.8. jakarta.xml.ws.EndpointReference

The following methods can be used on a published Endpoint to retrieve an jakarta.xml.ws.EndpointReference for the Endpoint instance.

getEndpointReference(List<Element> referenceParameters)

Creates and returns and jakarta.xml.ws.EndpointReference for a published Endpoint. If the binding is SOAP 1.1/HTTP or SOAP 1.2/HTTP, then a jakarta.xml.ws.wsaddressing.W3CEndpointReference MUST be returned. A returned W3CEndpointReference MUST also contain the specified referenceParameters. An implementation MUST throw a jakarta.xml.ws.WebServiceException if the Endpoint instance has not been published. An implementation MUST throw java.lang.UnsupportedOperationException if the Endpoint instance uses the XML/HTTP binding.

getEndpointReference(Class<T> clazz, List<Element> referenceParameters)

Creates and returns and jakarta.xml.ws.EndpointReference of type clazz for a published Endpoint instance. If clazz is of type jakarta.xml.ws.wsaddressing.W3CEndpointReference, then the returned W3CEndpointReference MUST contain the specified referenceParameters. An implementation MUST throw a jakarta.xml.ws.WebServiceException if the Endpoint instance has not been published. If the Class clazz is not a subclass of EndpointReference or the Endpoint implementation does not support EndpointReferences of type clazz a jakarta.xml.ws.WebServiceException MUST be thrown. An implementation MUST throw java.lang.UnsupportedOperationException if the Endpoint instance uses the XML/HTTP binding.

Conformance (Endpoint’s W3CEndpointReference): The returned W3EndpointReference MUST contain wsam:ServiceName and wsam:ServiceName[@EndpointName] as per Addressing 1.0 - Metadata[27]. The wsam:InterfaceName MAY be present in the W3CEndpointReference. If there is an associated WSDL, then the WSDL location MUST be referenced using wsdli:wsdlLocation in the W3CEndpointReference’s wsa:Metadata.

5.3. jakarta.xml.ws.WebServiceContext

The jakarta.xml.ws.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.

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 SHOULD throw a java.lang.IllegalStateException if it detects such a usage.

The WebServiceContext is treated as an injectable resource that can be set at the time an endpoint is initialized. 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.

In Java SE, the resource injection denoted by the WebServiceContext annotation is REQUIRED to take place only when the annotated class is an endpoint implementation class.

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;

    public String reverse(String inputString) { ... }
}

The jakarta.annotation.Resource annotation defined by Jakarta Annotations [35] is used to request injection of the WebServiceContext. The following constraints apply to the annotation elements of a Resource annotation used to inject a WebServiceContext:

  • The type element MUST be either java.lang.Object (the default) or jakarta.xml.ws.WebServiceContext. If the former, then the resource MUST be injected into a field or a method. In this case, the type of the field or the type of the JavaBeans property defined by the method MUST be jakarta.xml.ws.WebServiceContext.

  • The authenticationType, shareable elements, if they appear, MUST have their respective default values.

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. Moreover, the field/method type must be assignable from the type described by the annotation’s type element.

When running on the Java SE platform, the name and mappedName elements are ignored. As a consequence, 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), since it won’t be accessible at runtime via JNDI.

When running on the Jakarta EE platform, resources of type WebServiceContext are treated just like all other injectable resources there and are subject to the constraints prescribed by the platform specification [36].

An endpoint implementation can retrieve an jakarta.xml.ws.EndpointReference for the endpoint using getEndpointReference(List<Element> referenceParameters), and getEndpointReference( Class<T> clazz, List<Element> referenceParameters) methods. These methods have the same semantics as the Endpoint.getEndpointReference() methods specified in the Section 5.2.8, “jakarta.xml.ws.EndpointReference”.

Note

When using method-based injection, it is recommended that the method be declared as non-public, otherwise it will be exposed as a web service operation. Alternatively, 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.

5.3.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 10, Handler Framework). The restrictions are as follows:

  • Only properties whose scope is APPLICATION are visible using a MessageContext obtained from a WebServiceContext; the get method returns null for properties with HANDLER scope, the Set returned by keySet only includes properties with APPLICATION scope.

  • New properties set in the context are set in the underlying MessageContext with APPLICATION scope.

  • An attempt to set the value of property whose scope is HANDLER in the underlying MessageContext results in an IllegalArgumentException being thrown.

  • Only properties whose scope is APPLICATION can be removed using the context. An attempt to remove a property whose scope is HANDLER in the underlying MessageContext results in an IllegalArgumentException being thrown.

  • The Map.putAll method can be used to insert multiple properties at once. Each property is inserted individually, each insert operation being carried out as if enclosed by a try/catch block that traps any IllegalArgumentException. Consequently, 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, restricting access to context properties in this way ensures that endpoint implementations can only access properties intended for their use.

5.4. jakarta.xml.ws.wsaddressing.W3CEndpointReferenceBuilder

Occasionally it is necessary for one application component to create an EndpointReference for another web service endpoint. The W3CEndpointReferenceBuilder class provides a standard API for creating W3CEndpointReference instances for web service endpoints.

Conformance (Building W3CEndpointReference): W3CEndpointReferenceBuilder.build() method MUST construct an EndpointReference as per the Addressing 1.0 - Metadata[27].

6. Core APIs

This chapter describes the standard core APIs that may be used by both client and server side applications.

6.1. jakarta.xml.ws.Binding

The jakarta.xml.ws.Binding interface acts as a base interface for Jakarta XML Web Services protocol bindings. Bindings to specific protocols extend Binding and may add methods to configure specific aspects of that protocol binding’s operation. Chapter 11, SOAP Binding describes the Jakarta XML Web Services SOAP binding; Chapter 12, HTTP Binding describes the Jakarta XML Web Services XML/HTTP binding.

Applications obtain a Binding instance from a BindingProvider (a proxy or Dispatch instance) or from an Endpoint using the getBinding method (see Section 4.2, “jakarta.xml.ws.BindingProvider”, Section 5.2, “jakarta.xml.ws.Endpoint”).

A concrete binding is identified by a binding id, i.e. a URI. This specification defines a number of standard bindings and their corresponding identifiers (see Chapter 11, SOAP Binding and Chapter 12, HTTP Binding). Implementations MAY support additional bindings. In order to minimize conflicts, the identifier for an implementation-specific binding SHOULD use a URI scheme that includes a domain name or equivalent, e.g. the "http" URI scheme. Such identifiers SHOULD include a domain name controlled by the implementation’s vendor.

Binding provides methods to manipulate the handler chain configured on an instance (see Section 10.2.1, “Programmatic Configuration”).

Conformance (Read-only handler chains): An implementation MAY prevent changes to handler chains configured by some other means (e.g. via a deployment descriptor) by throwing UnsupportedOperationException from the setHandlerChain method of Binding

6.2. jakarta.xml.ws.spi.Provider

Provider is an abstract service provider interface (SPI) factory class that provides various methods for the creation of Endpoint instances and ServiceDelegate instances. These methods are designed for use by other Jakarta XML Web Services API classes, such as Service (see Section 4.1, “jakarta.xml.ws.Service”) and Endpoint (see Section 5.2, “jakarta.xml.ws.Endpoint”) and are not intended to be called directly by applications.

The Provider SPI allows an application to use a different Jakarta XML Web Services implementation from the one bundled with the platform without any code changes.

Conformance (Concrete jakarta.xml.ws.spi.Provider required): An implementation MUST provide a concrete class that extends jakarta.xml.ws.spi.Provider. Such a class MUST have a public constructor which takes no arguments.

6.2.1. Configuration

The Provider implementation class is determined using the following algorithm. The steps listed below are performed in sequence. At each step, at most one candidate implementation class name will be produced. The implementation will then attempt to load the class with the given class name using the current context class loader or, if missing one, the java.lang.Class.forName(String) method. As soon as a step results in an implementation class being successfully loaded, the algorithm terminates.

  1. If a system property with the name jakarta.xml.ws.spi.Provider is defined, then its value is used as the name of the implementation class. This phase of the look up enables per-JVM override of the Jakarta XML Web Services implementation.

  2. Use the service-provider loading facilities, defined by the java.util.ServiceLoader class, to attempt to locate and load an implementation of jakarta.xml.ws.spi.Provider service using the default loading mechanism .

  3. Finally, if all the steps above fail, then the rest of the lookup is unspecified. That said, the recommended behavior is to simply look for some hard-coded platform default Jakarta XML Web Services implementation. This phase of the lookup is so that the environment can have its own Jakarta XML Web Services implementation as the last resort.

6.2.2. Creating Endpoint Objects

Endpoints can be created using the following methods on Provider:

createEndpoint(String bindingID, Object implementor)

Creates and returns an Endpoint for the specified binding and implementor. If the bindingId is null and no binding information is specified via the jakarta.xml.ws.BindingType annotation then a default SOAP1.1/HTTP binding MUST be used.

createEndpoint(String bindingID, Object implementor, WebServiceFeature …​ features)

Same as the above createEndpoint() method. The created Endpoint is configured with the web service features.

createAndPublishEndpoint(String address, Object implementor)

Creates and publishes an Endpoint for the given implementor. The binding is chosen by default based on the URL scheme of the provided address (which must be a URL). If a suitable binding if found, the endpoint is created then published as if the Endpoint.publish(String address) method had been called. The created Endpoint is then returned as the value of the method.

createAndPublishEndpoint(String address, Object implementor, WebServiceFeature …​ features)

Same as the above createAndPublishEndpoint() method. The created Endpoint is configured with the web service features.

createEndpoint(String bindingId, Class<?> implementorClass, Invoker invoker, WebServiceFeature …​ features)

Creates an Endpoint for the implementor class and the endpoint invocation is handled by the Invoker. If the bindingId is null and no binding information is specified via the jakarta.xml.ws.BindingType annotation then a default SOAP1.1/HTTP binding MUST be used. The created Endpoint is configured with the web service features.

An implementor object MUST be either:

The createAndPublishEndpoint(String,Object) method is provided as a shortcut for the common operation of creating and publishing an Endpoint. It corresponds to the static publish method defined on the Endpoint class, see Section 5.2.1, “Endpoint Usage”.

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, then invoking the publish(String address) method on the resulting endpoint.

6.2.3. Creating ServiceDelegate Objects

jakarta.xml.ws.spi.ServiceDelegate Section 6.3, “jakarta.xml.ws.spi.ServiceDelegate” can be created using the following methods on Provider:

createServiceDelegate(URL wsdlDocumentLocation, QName serviceName, Class <? extends Service> serviceClass)

Creates and returns a ServiceDelegate for the specified service. When starting from WSDL the serviceClass will be the generated service class as described in Section 2.7, “Service and Port”. In the dynamic case where there is no service class generated it will be jakarta.xml.ws.Service. The serviceClass is used by the ServiceDelegate to get access to the annotations.

createServiceDelegate(URL wsdlDocumentLocation, QName serviceName, Class <? extends Service> serviceClass, WebServiceFeature …​ features)

Same as the above createServiceDelegate() method and it also configures the delegate with all the web service features.

6.2.4. EndpointReferences

The Provider class provides the following methods to create EndpointReference instances.

readEndpointReference(javax.xml.transform.Source source)

Unmarshalls and returns a jakarta.xml.ws.EndpointReference from the infoset contained in source.

createW3CEndpointReference(String address, QName serviceName, QName portName, List<Element> metadata, String wsdlDocumentLocation, List<Element> referenceParameters)

Creates a W3CEndpointReference using the specified String address, QName serviceName, QName portName, List<Element> metadata, String wsdlDocumentLocation, and List<Element> referenceParameters parameters.

createW3CEndpointReference(String address, QName interfaceName, QName serviceName, QName portName, List<Element> metadata, String wsdlDocumentLocation, List<Element> referenceParameters, List<Element> elements, Map<QName, String> attributes)

Creates W3CEndpointReference using the specified parameters. This method adds support for extension elements, extension attributes, and porttype name.

6.2.5. Getting Port Objects

The following method can be used to get a proxy for a Port.

getPort(EndpointReference epr, Class<T> sei, WebServiceFeature…​ features)

Gets a proxy for the sei that can be used to invoke operations on the endpoint referred to by the epr. The specified features MUST be enabled/disabled and configured as specified. The returned proxy MUST use the epr to determine the endpoint address and any reference parameters that MUST be sent on endpoint invocations. The epr MUST NOT be used directly as the value of an WS-Addressing header such as wsa:ReplyTo.

6.3. jakarta.xml.ws.spi.ServiceDelegate

The jakarta.xml.ws.spi.ServiceDelegate class is an abstract class that implementations MUST provide. This is the class that jakarta.xml.ws.Service Section 4.1, “jakarta.xml.ws.Service” class delegates all methods, except the static create methods to. ServiceDelegate is defined as an abstract class for future extensibility purpose.

Conformance (Concrete jakarta.xml.ws.spi.ServiceDelegate required): An implementation MUST provide a concrete class that extends jakarta.xml.ws.spi.ServiceDelegate.

6.4. Exceptions

The following standard exceptions are defined by Jakarta XML Web Services.

jakarta.xml.ws.WebServiceException

A runtime exception that is thrown by methods in Jakarta XML Web Services APIs when errors occur during local processing.

jakarta.xml.ws.ProtocolException

A base class for exceptions related to a specific protocol binding. 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.

jakarta.xml.ws.soap.SOAPFaultException

A subclass of ProtocolException, may be used to carry SOAP specific information.

jakarta.xml.ws.http.HTTPException

A subclass of ProtocolException, may be used to carry HTTP specific information.

Editors Note

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.g. a broken connection or an unresolvable server name). Currently, both kinds of errors are mapped to WebServiceException, but the latter kind would be more usefully mapped to its own exception type, much like ProtocolException is.

6.4.1. Protocol Specific Exception Handling

Conformance (Protocol specific fault generation): When throwing an exception as the result of a protocol level fault, an implementation MUST ensure that the exception is an instance of the appropriate ProtocolException subclass. For SOAP the appropriate ProtocolException subclass is SOAPFaultException, for XML/HTTP is is HTTPException.

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, an implementation MUST reflect the information contained in the ProtocolException subclass within the generated protocol level fault.

6.4.1.1. Client Side Example
1
2
3
4
5
6
try {
    response = dispatch.invoke(request);
} catch (SOAPFaultException e) {
    QName soapFaultCode = e.getFault().getFaultCodeAsQName();
    ...
}
6.4.1.2. Server Side Example
1
2
3
4
5
6
7
8
9
public void endpointOperation() {
    ...
    if (someProblem) {
        SOAPFault fault = soapBinding.getSOAPFactory().createFault(
            faultcode, faultstring, faultactor, detail);
        throw new SOAPFaultException(fault);
    }
    ...
}
6.4.1.3. One-way Operations

Conformance (One-way operations): When sending a one-way message, implementations MUST throw a WebServiceException if any error is detected when sending the message.

6.5. jakarta.xml.ws.WebServiceFeature

Jakarta XML Web Services introduces the notion of features. A feature is associated with a particular functionality or behavior. Some features may only have meaning when used with certain bindings while other features may be generally useful. These features can be used while creating service and proxy instances. Jakarta XML Web Services introduces three standard features for creating proxy instances, AddressingFeature, MTOMFeature and RespectBindingFeature as well as the base WebServiceFeature class. There are no standard features for service creation in the current specification. A Jakarta XML Web Services implementation may define its own features but they will be non-portable across all Jakarta XML Web Services implementations.

Each feature is derived from the jakarta.xml.ws.WebServiceFeature class. This allows the web service developer to pass different types of WebServiceFeatures to the various Jakarta XML Web Services APIs that utilize them. Also, each feature should be documented using JavaDocs on the derived classes. Each WebServiceFeature MUST have a public static final String ID field that is used to uniquely identify the feature.

Conformance (jakarta.xml.ws.WebServiceFeatures): Each derived type of jakarta.xml.ws.WebServiceFeature MUST contain a public static final String ID field that uniquely identifies the feature against all features of all implementations.

Since vendors can specify their own features, care MUST be taken when creating a feature ID so as to not conflict with another vendor’s ID.

The WebServiceFeature class also has an enabled property that is used to store whether a particular feature should be enabled or disabled. 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. The meaning of enabled or disabled is determined by each individual WebServiceFeature. It is important that web services developers be able to enable/disable specific features when writing their web applications. For example, a developer may choose to implement WS-Addressing himself while using the Dispatch and Provider APIs and thus he MUST be able to tell Jakarta XML Web Services to disable addressing.

Conformance (enabled property): Each derived type of jakarta.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. The public default constructor MUST by default set the enabled property to true. An implementation MUST honor the value of the enabled property of any supported WebServiceFeature.

6.5.1. jakarta.xml.ws.soap.AddressingFeature

The AddressingFeature is used to control the use of WS-Addressing[26] by Jakarta XML Web Services. This feature MUST be supported with the SOAP 1.1/HTTP or SOAP 1.2/HTTP bindings. Using this feature with any other binding is undefined. This feature corresponds to the Addressing annotation described in Section 8.14.1, “jakarta.xml.ws.soap.Addressing”.

Enabling this feature on the server will result in the runtime being capable of consuming and responding to WS-Addressing headers.

Enabling this feature on the client will cause the Jakarta XML Web Services runtime to include WS-Addressing headers in SOAP messages as specified by WS-Addressing[26].

Disabling this feature will prevent a Jakarta XML Web Services runtime from processing or adding WS-Addressing headers from/to SOAP messages even if the associated WSDL specifies otherwise. This may be necessary if a client or endpoint needs to implement Addressing themselves. For example, a client that desires to use non-anonymous ReplyTo can do so by disabling the AddressingFeature and by using Dispatch<Source> with Message mode.

The AddressingFeature’s required property can be configured to control whether all incoming messages MUST contain Addressing headers.

The AddressingFeature’s responses property can be configured to control whether the endpoint requires the use of anonymous, non-anonymous and all responses.

This feature is automatically enabled if the WSDL indicates the use of addressing as per the WS-Addressing 1.0 - Metadata[27]. Developers may choose to prevent this from happening by explicitly disabling the AddressingFeature.

6.5.1.1. jakarta.xml.ws.EndpointReference

The abstract EndpointReference class is used by the Jakarta XML Web Services APIs to reference a particular endpoint in accordance with the W3C Web Services Addressing 1.0[26]. Each concrete instance of an EndpointReference MUST contain a wsa:Address.

Applications may also use the EndpointReference class in method signatures. Jakarta XML Binding will bind the EndpointReference base class to xs:anyType. Applications should instead use concrete implementations of EndpointReference such as jakarta.xml.ws.W3CEndpointReference which will provide better binding. Jakarta XML Web Services implementations are required to support the W3CEndpointReference class but they may also provide other EndpointReference subclasses that represent different versions of Addressing.

6.5.1.2. jakarta.xml.ws.W3CEndpointReference

The W3CEndpointReference class is a concrete implementation of the jakarta.xml.ws.EndpointReference class and is used to reference endpoints that are compliant with the W3C Web Services Addressing 1.0 - Core[26] recommendation. Applications may use this class to pass EndpointReference instances as method parameters or return types. Jakarta XML Binding will bind the W3CEndpointReference class to the W3C EndpointReference XML Schema in the WSDL.

6.5.2. jakarta.xml.ws.soap.MTOMFeature

The MTOMFeature is used to specify if MTOM should be used with a web service. This feature should be used instead of the jakarta.xml.ws.soap.SOAPBinding.SOAP11HTTP_MTOM_BINDING, jakarta.xml.ws.soap.SOAPBinding.SOAP12HTTP_MTOM_BINDING and the jakarta.xml.ws.soap.SOAPBinding.setMTOMEnabled(). This feature MUST be supported with the SOAP 1.1/HTTP or SOAP 1.2/HTTP bindings. Using this feature with any other bindings is undefined. This feature corresponds to the MTOM annotation described in Section 8.14.2, “jakarta.xml.ws.soap.MTOM”.

Enabling this feature on either the server or client will result the Jakarta XML Web Services runtime using MTOM and for binary data being sent as an attachment.

The MTOMFeature has one property threshold, that can be configured to serve as a hint for which binary data SHOULD be sent as an attachment. The threshold is the size in bytes that binary data SHOULD be in order to be sent as an attachment. The threshold MUST not be negative. The default value is 0.

Conformance (jakarta.xml.ws.soap.MTOMFeature): An implementation MUST support the jakarta.xml.ws.soap.MTOMFeature and its threshold property.

6.5.3. jakarta.xml.ws.RespectBindingFeature

The RespectBindingFeature is used to control whether a Jakarta XML Web Services implementation MUST respect/honor the contents of the wsdl:binding associated with an endpoint. It has a corresponding RespectBinding annotation described in Section 8.14.3, “jakarta.xml.ws.RespectBinding”.

Conformance (jakarta.xml.ws.RespectBindingFeature): When the jakarta.xml.ws.RespectBindingFeature is enabled, a Jakarta XML Web Services 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. All required wsdl:extensions MUST be supported and honored by a Jakarta XML Web Services implementation unless a specific wsdl:extension has be explicitly disabled via a WebServiceFeature.

When this feature is enabled, a Jakarta XML Web Services implementation must support and honor the addressing policy, if specified, in the WSDL. However, such addressing requirements can be explicitly disabled via AddressingFeature.

In order to not break backward compatibility with JAX-WS 2.0, the behavior with regards to respecting the wsdl:binding when this feature is disabled is undefined.

6.6. jakarta.xml.ws.spi.http (HTTP SPI)

The classes in this package can be used for a portable deployment of Jakarta XML Web Services web services in a HTTP container (for example, servlet container). This SPI enables to decouple the Jakarta XML Web Services deployment and runtime and is not meant for end developers but for container or its extension developers.

The HTTP SPI allows a deployment to use any available web services runtime for HTTP transport.

The HTTP SPI consists of the following classes:

jakarta.xml.ws.spi.http.HttpContext

HttpContext represents a mapping between the root URI path of a web service to a HttpHandler which is invoked to handle requests destined for that path on the associated container.

jakarta.xml.ws.spi.http.HttpExchange

This class encapsulates a HTTP request received and a response to be generated in one exchange.

jakarta.xml.ws.spi.http.HttpHandler

A handler which is invoked to process HTTP exchanges.

jakarta.xml.ws.spi.Invoker

Invoker hides the detail of calling into application endpoint implementation.

Typical portable deployment is done as below:

  1. Container creates Endpoint objects for an application. The necessary information to create Endpoint objects may be got from web service deployment descriptor files.

  2. Container creates HttpContext objects for the deployment. For example, a HttpContext could be created using servlet configuration(for e.g. url-pattern) for a web service in servlet container case.

  3. Then publishes all the endpoints using Endpoint.publish(HttpContext). During publish(), Jakarta XML Web Services runtime registers a HttpHandler callback to handle incoming requests or HttpExchange objects. The HttpExchange object encapsulates HTTP request and response.

  Container                               Jakarta XML Web Services runtime
  ---------                               --------------
  1. Creates Invoker1, ... InvokerN
  2. Provider.createEndpoint(...)     --> 3. creates Endpoint1
     configures Endpoint1
     ...
  4. Provider.createEndpoint(...)     --> 5. creates EndpointN
     configures EndpointN
  6. Creates EndpointContext with
     Endpoint1, ..., EndpointN
     and sets it on all endpoints.
  7. creates HttpContext1, ... HttpContextN
  8. Endpoint1.publish(HttpContext1)  --> 9. creates HttpHandler1
                                          HttpContext1.setHandler(HttpHandler1)
     ...
 10. EndpointN.publish(HttpContextN)  --> 11. creates HttpHandlerN
                                          HttpContextN.setHandler(HttpHandlerN)

Typical request processing is done as below(for every request):

  Container                               Jakarta XML Web Services runtime
  ---------                               --------------
  1. Creates a HttpExchange
  2. Gets handler from HttpContext
  3. HttpHandler.handle(HttpExchange) --> 4. reads request from HttpExchange
                                      <-- 5. Calls Invoker
  6. Invokes the actual instance
                                          7. Writes the response to HttpExchange

Typical portable undeployment is done as below:

  Container                               Jakarta XML Web Services runtime
  ---------                               --------------
  1. @preDestroy on instances
  2. Endpoint1.stop()
  ...
  3. EndpointN.stop()

7. Jakarta Web Services Metadata

7.1. Concepts

This section summarizes the following concepts and processes of the Jakarta Web Services Metadata specification:

  • Programming model for Jakarta Web Services Metadata annotated Web services

  • Use of metadata in Jakarta Web Services

  • Non-normative processing model for a JWS file

  • Runtime requirements for a Jakarta Web Services Metadata container

  • Annotations used for WSDL, binding and configuration

The metadata is formally described in section 4.

7.1.1. Programming Model Overview

Jakarta Web Services Metadata Specification, along with Jakarta XML Web Services Specification and Jakarta Enterprise Web Services Specification, defines a programming model for building a Web Service. A developer who builds a Web Service with these technologies is required to write and manage several artifacts: a WSDL document describing the external Web Service contract; a service endpoint interface defining the Java representation of the Web Service interface; a service implementation bean containing the Web Service implementation; and one or more deployment descriptors linking the WSDL, interface, and implementation into a single artifact. Jakarta Web Services Metadata Specification simplifies this model by allowing the developer to write only the service implementation bean - actual business logic – and use annotations to generate the remaining artifacts.

7.1.2. Development Models

Jakarta Web Services Metadata Specification defines several different models of Web Service development. Only the Start with Java development model is REQUIRED by implementations.

7.1.2.1. Start with Java

Following the “Start with Java” development model, the developer begins by writing a Java class to expose as a Web Service. The developer then runs this Java class through the Jakarta Web Services Metadata processor, which produces WSDL, schema, and other deployment artifacts from the annotated Java code. By default, the WSDL produced from the Java source follows the Java to XML/WSDL mapping defined by Jakarta XML Web Services Specification. However, the developer may customize the generated WSDL through annotations on the Java source. For example, the developer may use the @WebService.name annotation to set explicitly the name of the wsdl:portType representing the Web Service.

Jakarta Web Services Metadata Specification also supports a development model where the service is defined in Java but the messages and types are defined in XML schema. In this model, the developer starts by defining a set of types and elements in XML schema. The schema definitions are passed through a “schema to Java” compiler to produce a corresponding set of Java types. The resulting Java types are then used as parameters and return values on methods in an annotated service implementation bean. The WSDL produced from this service implementation bean imports or directly includes the schema definitions that match the Java types used by the service.

7.1.2.2. Start with WSDL

Following the “start with WSDL” development model, the developer uses Jakarta Web Services Metadata Specification to implement a predefined WSDL interface. Typically, this process begins with the developer passing a pre-existing WSDL 1.1 file through an implementation-supplied tool to produce a service endpoint interface that represents the Java contract, along with Java classes that represent the schema definitions and message parts contained in the WSDL. The developer then writes a service implementation bean that implements the service endpoint interface. In this model, Jakarta Web Services Metadata annotations supply implementation details that are left out of the original WSDL contract, such as binding or service location information.

7.1.2.3. Start with WSDL and Java

Following the “start with WSDL and Java” development model, the developer uses Jakarta Web Services Metadata annotations to associate a service implementation bean with an existing WSDL contract. In this model, the Jakarta Web Services Metadata annotations map constructs on the Java class or interface to constructs on the WSDL contract. For example, the developer could use the @WebMethod.operationName annotation to associate a method on the service implementation bean with a predefined wsdl:operation. A Jakarta Web Services Metadata implementation that supports this model MUST provide feedback when a service implementation bean no longer adheres to the contract defined by the original WSDL. The form that this feedback takes depends on the implementation. For example, a source editing tool might provide feedback by highlighting the offending annotations, while a command line tool might generate warnings or fail to process a service implementation bean that does not match the associated WSDL.

7.1.3. Processor Responsibilities

The term “Jakarta Web Services Metadata processor” denotes the code that processes the annotations in a Jakarta Web Services Metadata JWS file to create a runnable Web Service. Typically this involves generating the WSDL and schemas that represent the service and its messages and the deployment descriptors that configure the service for the target runtime. It may also result in the generation of additional source artifacts.

This specification does not require implementations to follow a particular processing model. An implementation MAY use whatever processing model is appropriate to its environment, as long as it produces a running Web Service with the proper contract and runtime behavior. For example, one implementation might process the Jakarta Web Services Metadata annotations directly within the Java compiler to generate a deployable Web Service as the output of compilation; another might provide tools to convert a compiled service implementation bean into a set of artifacts that can be deployed into the container; and a third might configure its runtime container directly off the Java source or class file. Each implementation is conformant with Jakarta Web Services Metadata Specification as long as it produces a Web Service with the proper runtime behavior.

7.1.4. Runtime Responsibilities

The runtime environment provides lifecycle management, concurrency management, transport services, and security services. This specification defines the set of annotations that a developer may use to specify declaratively the behavior of an application, but does not define a specific runtime environment or container. Instead, the Jakarta Web Services Metadata processor is responsible for mapping the annotated Java classes onto a specific runtime environment. This specification envisions – but does not require – several such runtime environments:

  • Automatic deployment to a server directory – This is a “drag and drop” deployment model, similar to that used by Jakarta Server Pages. The annotated JWS file is copied in source or class form to a directory monitored by the container. The container examines the annotations in the file to build a WSDL and configures the runtime machinery required for dispatching. This approach provides a simplified deployment model for prototyping and rapid application development (RAD).

  • Automatic deployment with external overrides – Similar to previous approach, but with the addition of an external configuration file containing overrides to annotations. The additional configuration file allows an administrator to customize the behavior or configuration of the Web Service – such as the endpoint URL - without changing the Java source.

  • Generation of Jakarta EE Web Services - In this model, a tool uses the metadata in the annotated Java class to generate a Jakarta EE Web Service based on Jakarta Enterprise Web Services and Jakarta XML Web Services Specifications. The initial Web Service is generated from the annotated Java source, and the result can be further customized through standard deployment tools, including Jakarta Deployment plans. This feature allows customization of externally modifiable properties at deployment or runtime, without requiring access to the source file for modification and recompilation.

7.1.5. Metadata Use

The metadata that annotates the service implementation bean conforms to the JSR-175 specification and the specific Jakarta Web Services Metadata annotation type declarations that are defined in this specification in conjunction with the JSR-175 metadata facility. These annotation type declarations are contained in packages that MUST be imported by every Jakarta Web Services Metadata JWS source file. JSR-175 provides the syntax for expressing the annotation element declarations that are in these packages. This specification specifies the contents of the jakarta.jws and jakarta.jws.soap packages (see attached APIs).

Developers use a standard Java compiler with support for JSR-175 to compile and validate the service implementation bean. The compiler uses the annotation type declarations in the jakarta.jws and jakarta.jws.soap packages to check for syntax and type mismatch errors in the Web Service metadata. The result of compilation is a Java .class file containing the Web Service metadata along with the compiled Java code. The class file format for these annotations is specified by JSR-175. Any Web Service metadata that this JSR designates as runtime-visible is also accessible through the standard java.lang.reflect classes from the run-time environment.

7.1.5.1. Error Checking

Although the compiler can check for syntax and type errors by using the annotation type declaration, syntactically valid metadata may still contain semantic errors. Implementations MUST provide a validation mechanism to perform additional semantic checking to ensure that a service implementation bean is correct. The validation MAY be performed in a separate tool or as part of deployment.

Examples of semantic checks include:

  • Ensuring that annotation values match extended types. The Java compiler can ensure that a particular annotation member-value is of the type specified in the annotation type declaration. However, JSR-175 restricts annotations to simple types such as primitives, Strings, and enums. As a result, the compiler cannot ensure that, for example, an annotation member is a valid URL. It can only verify that the member is a String. The Jakarta Web Services Metadata implementation MUST perform the additional type checking to ensure that the value is a valid URL.

  • Ensuring that annotations match the code. For example, the developer MAY use the @Oneway annotation to indicate that a particular operation does not produce an output message. If the operation is marked @Oneway, it MUST NOT have a return value or out/in-out parameters. The Jakarta Web Services Metadata implementation MUST provide feedback if this constraint is violated.

  • Ensuring that annotations are consistent with respect to other annotations. For example, it is not legal to annotate a method with the @Oneway annotation unless there is also a corresponding @WebMethod annotation. The Jakarta Web Services Metadata implementation MUST ensure these constraints are met.

Note: Certain types of errors MAY only be caught when the Web Service is deployed or run.

7.1.5.2. Default Values

Jakarta Web Services Metadata Specification defines appropriate defaults for most annotation members. This feature exempts the JWS author from providing tags for the most common Web Service definitions. Although this specification uses the JSR-175 default mechanism wherever possible, this mechanism is only suitable for defining defaults that are constant values. In contrast, many actual default values are not constants but are instead computed from the Java source or other annotations. For example, the default value for the @WebService.name annotation is the simple name of the Java class or interface. This value cannot be represented directly as a JSR-175 default. In scenarios where JSR-175 defaults are not sufficient to describe the required default, a “marker” constant is used instead. When the Jakarta Web Services Metadata processor encounters this marker constant, the processor treats the member-value as though it had the computed default described in section 4. For example, when the Jakarta Web Services Metadata processor encounters a @WebService.name annotation with a value of “” (the empty string), it behaves as though the name of the Web Service were the name of the Java class.

7.1.6. Web Services Metadata

Jakarta Web Services Metadata Specification describes declaratively how the logic of a service implementation bean is exposed over networking protocols as a Web Service. The @WebService tag marks a Java class as implementing a Web Service. @WebMethod tags identify the individual methods of the Java class that are exposed externally as Web Service operations, as illustrated in the following example. The example uses JSR-175 syntax and the annotation type declarations defined in the jakarta.jws and jakarta.jws.soap packages.

import jakarta.jws.WebService;
import jakarta.jws.WebMethod;

@WebService
public class HelloWorldService {
   @WebMethod
   public String helloWorld() {
     return "Hello World!";
   }
}

Most of these metadata tags have reasonable defaults, which are explicitly called out in section 4. Most of these metadata tags have reasonable defaults, which are explicitly called out in this document. The JWS author can avoid providing tags for the most common Web Service definitions.

Sections 2.6.1 through 2.6.3 describe the types of annotations provided by Jakarta Web Services Metadata Specification.

7.1.6.1. WSDL Mapping Annotations

WSDL mapping annotations control the mapping from Java source onto WSDL constructs. As described in section 2.2 Development Models, this specification supports both a “start with Java” and a “start with WSDL” development model. In “start with Java,” the WSDL mapping annotations control the shape of the WSDL generated from the Java source. In “start with WSDL,” the WSDL mapping annotations associate the Java source with pre-existing WSDL constructs.

7.1.6.2. Binding Annotations

Binding annotations specify the network protocols and message formats that are supported by the Web Service. For example, the presence of a @SOAPBinding annotation tells the processor to make the service available over the SOAP 1.1 message. Fields on this annotation allow the developer to customize the way the mapping of the implementation object onto SOAP messages.

Jakarta Web Services Metadata Specification defines a single set of annotations that map the implementation object to the SOAP protocol binding. Jakarta Web Services Metadata implementations MAY support additional binding annotations for other protocols. Non-normative examples of such binding annotations can be found in Appendix C.

7.1.6.3. Handler Annotations

Handler annotations allow the developer to extend a Web Service with additional functionality that runs before and after the business methods of the Web Service.

7.2. Server Programming Model

This section describes the server programming model for Jakarta Web Services Metadata. The Jakarta Web Services Metadata server programming model is a simplification of the existing Jakarta Web Services server programming models, as defined in Jakarta XML Web Services and Jakarta Enterprise Web Services. Jakarta Web Services Metadata Specification simplifies these models by allowing the developer to focus on business logic and using annotations to generate related artifacts.

7.2.1. Service Implementation Bean

A developer who implements Web Services with Jakarta Web Services Metadata is responsible for implementing the service implementation bean containing the Web Service’s business logic. A Jakarta Web Services Metadata service implementation bean MUST meet the following requirements:

  • The implementation bean MUST be an outer public class, MUST NOT be final, and MUST NOT be abstract.

  • The implementation bean MUST have a default public constructor.

  • The implementation MUST NOT define a finalize() method.

  • The implementation bean MUST include a @WebService class-level annotation, indicating that it implements a Web Service. More information on the @WebService annotation may be found in section 4.1 Annotation: jakarta.jws.WebService..

  • The implementation bean MAY reference a service endpoint interface by using the @WebService.endpointInterface annotation. If the implementation bean references a service endpoint interface, it MUST implement all the methods on the service endpoint interface. If the implementation bean references a service endpoint interface, that service endpoint interface is used to determine the abstract WSDL contract (portType and bindings). In this case, the service implementation bean MUST NOT include any Jakarta Web Services Metadata annotations other than @WebService and @HandlerChain. In addition, the @WebService annotation MUST NOT include the name annotation element. More information on the @WebService.endpointInterface annotation element may be found in section 4.1 Annotation: jakarta.jws.WebService.

  • If the implementation bean does not reference a service endpoint interface by using the @WebService.endpointInterface annotation, the bean class implicitly defines a service endpoint interface (SEI). The SEI MUST meet the requirements specified in Jakarta XML Web Services Specification [5], section 3.3

7.2.2. Service Endpoint Interface

A Jakarta Web Services Metadata service implementation bean MAY reference a service endpoint interface, thus separating the contract definition from the implementation. A Jakarta Web Services Metadata service endpoint interface MUST meet the requirements specified in Jakarta XML Web Services Specification [5], section 3.4, with the following exceptions:

  • The service endpoint interface MUST be an outer public interface.

  • The service endpoint interface MUST include a @WebService annotation, indicating that it is defining the contract for a Web Service.

  • The service endpoint interface MAY extend java.rmi.Remote either directly or indirectly, but is not REQUIRED to do so.

  • All methods on the service endpoint interface, including methods inherited from super-interfaces, are mapped to WSDL operations regardless of whether they include a @WebMethod annotation. A method MAY include a @WebMethod annotation to customize the mapping to WSDL, but is not REQUIRED to do so.

  • The service endpoint interface MAY include other Jakarta Web Services Metadata annotations to control the mapping from Java to WSDL.

  • The service endpoint interface MUST NOT include the Jakarta Web Services Metadata annotation elements portName, serviceName and endpointInterface of the annotation @WebService.

7.2.3. Web Method

A method will be exposed as a Web Service operation, making it part of the Web Service’s public contract according to rules specified in section 3.1 Service Implementation Bean or in section 3.2 Service Endpoint Interface if the service implementation bean implements a service endpoint interface. An exposed method MUST meet the following requirements.

  • The method MUST be public.

  • The method’s parameters, return value, and exceptions MUST follow the rules defined in Jakarta XML Web Services Specification [5], section 3.6).

  • The method MAY throw java.rmi.RemoteException, but is not REQUIRED to do so.

7.3. Web Services Metadata

This section contains the specifications of each individual Web Service metadata items. Both the annotation type declarations (using JSR-175 syntax) and usage examples are given for each metadata item.

7.3.1. Annotation: jakarta.jws.WebService

7.3.1.1. Description

Marks a Java class as implementing a Web Service, or a Java interface as defining a Web Service interface.

Member-Value Meaning Default

name

The name of the Web Service. Used as the name of the wsdl:portType when mapped to WSDL 1.1

Simple name of the Java class or interface

targetNamespace

If the @WebService.targetNamespace annotation is on a service endpoint interface, the targetNamespace is used for the namespace for the wsdl:portType (and associated XML elements).

If the @WebService.targetNamespace annotation is on a service implementation bean that does NOT reference a service endpoint interface (through the endpointInterface annotation element), the targetNamespace is used for both the wsdl:portType and the wsdl:service (and associated XML elements).

If the @WebService.targetNamespace annotation is on a service implementation bean that does reference a service endpoint interface (through the endpointInterface annotation element), the targetNamespace is used for only the wsdl:service (and associated XML elements).

Implementation-defined, as described in Jakarta XML Web Services Specification [5], section 3.2.

serviceName

The service name of the Web Service. Used as the name of the wsdl:service when mapped to WSDL 1.1.

This member-value is not allowed on endpoint interfaces.

Simple name of the Java class + “Service"

portName

Used as the name of the wsdl:port when mapped to WSDL 1.1.

This member-value is not allowed on endpoint interfaces.

@WebService.name +”Port”

wsdlLocation

The location of a pre-defined WSDL describing the service. The wsdlLocation is a URL (relative or absolute) that refers to a pre-existing WSDL file. The presence of a wsdlLocation value indicates that the service implementation bean is implementing a pre-defined WSDL contract. The Jakarta Web Services Metadata tool MUST provide feedback if the service implementation bean is inconsistent with the portType and bindings declared in this WSDL. Note that a single WSDL file might contain multiple portTypes and multiple bindings. The annotations on the service implementation bean determine the specific portType and bindings that correspond to the Web Service.

None

endpointInterface

The complete name of the service endpoint interface defining the service’s abstract Web Service contract. This annotation allows the developer to separate the interface contract from the implementation. If this annotation is present, the service endpoint interface is used to determine the abstract WSDL contract (portType and bindings). The service endpoint interface MAY include Jakarta Web Services Metadata annotations to customize the mapping from Java to WSDL. The service implementation bean MAY implement the service endpoint interface, but is not REQUIRED to do so.

This member-value is not allowed on endpoint interfaces.

None.

The Web Service contract is generated from annotations on the service implementation bean. If a service endpoint interface is required by the target environment, it will be generated into an implementation-defined package with an implementation-defined name.

7.3.1.2. Annotation Type Definition
@Retention(value=RetentionPolicy.RUNTIME)
@Target({TYPE})
public @interface WebService {
  String name() default "";
  String targetNamespace() default "";
  String serviceName() default "";
  String portName() default "";
  String wsdlLocation() default "";
  String endpointInterface() default "";
};
7.3.1.3. Example

Java source:

/**
* Annotated Implementation Object
*/
@WebService(
  name = "EchoService",
  targetNamespace = "http://www.openuri.org/2004/04/HelloWorld"
)
public class EchoServiceImpl {
   @WebMethod
   public String echo(String input) {
      return input;
   }
}

7.3.2. Annotation: jakarta.jws.WebMethod

7.3.2.1. Description

Customizes a method that is exposed as a Web Service operation. The WebMethod annotation includes the following member-value pairs:

Member-Value Meaning Default

operationName

Name of the wsdl:operation matching this method.

Name of the Java method

action

The action for this operation. For SOAP bindings, this determines the value of the soap action.

""

exclude

Marks a method to NOT be exposed as a web method. Used to stop an inherited method from being exposed as part of this web service.

If this element is specified, other elements MUST NOT be specified for the @WebMethod.

This member-value is not allowed on endpoint interfaces.

False

7.3.2.2. Annotation Type Definition
@Retention(value=RetentionPolicy.RUNTIME)
@Target({METHOD})
public @interface WebMethod {
  String operationName() default "";
  String action() default "" ;
  boolean exclude() default false;
};
7.3.2.3. Example

Java source:

@WebService
public class MyWebService {
   @WebMethod(operationName = "echoString", action="urn:EchoString")
   public String echo(String input) {
      return input;
   }
}

Resulting WSDL:

<definitions>
   <portType name="MyWebService">
      <operation name="echoString"/>
         <input message="echoString"/>
         <output message="echoStringResponse"/>
      </operation>
   </portType>

   <binding name="PingServiceHttpSoap" type="MyWebService">
      <operation name="echoString">
         <soap:operation soapAction="urn:EchoString"/>
      </operation>
   </binding>
</definitions>

7.3.3. Annotation: jakarta.jws.Oneway

7.3.3.1. Description

Indicates that the given web method has only an input message and no output. Typically, a oneway method returns the thread of control to the calling application prior to executing the actual business method. A Jakarta Web Services Metadata processor is REQUIRED to report an error if an operation marked @Oneway has a return value, declares any checked exceptions or has any INOUT or OUT parameters.

7.3.3.2. Annotation Type Definition
@Retention(value=RetentionPolicy.RUNTIME)
@Target({METHOD})
public @interface Oneway {
};
7.3.3.3. Example

Java source:

@WebService
public class PingService {

   @WebMethod
   @Oneway
   public void ping() {
   }
};

Resulting WSDL:

<definitions>
   <message name="ping"/>

   <portType name="PingService">
      <operation name="ping">
         <input message="ping"/>
      </operation>
   </portType>
</definitions>

7.3.4. Annotation: jakarta.jws.WebParam

7.3.4.1. Description

Customizes the mapping of an individual parameter to a Web Service message part and XML element.

Member-Value Meaning Default

name

Name of the parameter.

If the operation is rpc style and @WebParam.partName has not been specified, this is name of the wsdl:part representing the parameter.

If the operation is document style or the parameter maps to a header, this is the local name of the XML element representing the parameter.

A name MUST be specified if the operation is document style, the parameter style is BARE, and the mode is OUT or INOUT.

@WebMethod.operation Name, if the operation is document style and the parameter style is BARE, and the parameter does not map to a header, and the mode is IN or INOUT.

@WebMethod operation Name+”Response”, if the operation is document style and the parameter style is BARE, and the parameter does not map to a header, and the mode is OUT.

Otherwise, the default is argN, where N represents the index of the parameter in the method signature (starting at arg0).

partName

The name of the wsdl:part representing this parameter. This is only used if the operation is rpc style or if the operation is document style and the parameter style is BARE.

@WebParam.name

targetNamespace

The XML namespace for the parameter.

Only used if the operation is document style or the paramater maps to a header.

If the target namespace is set to "", this represents the empty namespace.

The empty namespace, if the operation is document style, the parameter style is WRAPPED, and the parameter does not map to a header.

Otherwise, the default is the targetNamespace for the Web Service.

mode

The direction in which the parameter is flowing. One of IN, OUT, or INOUT. The OUT and INOUT modes may only be specified for parameter types that conform to the definition of Holder types (Jakarta XML Web Services Specification [5], section 2.3.3). Parameters that are Holder Types MUST be OUT or INOUT.

IN if not a Holder type. INOUT if a Holder type.

header

If true, the parameter is pulled from a message header rather then the message body.

False

7.3.4.2. Annotation Type Definition
@Retention(value=RetentionPolicy.RUNTIME)
@Target({PARAMETER})
public @interface WebParam {

   enum Mode {
      IN,
      OUT,
      INOUT
   };

   String name() default "";
   String partName() default "";
   String targetNamespace() default "";
   Mode mode() default Mode.IN;
   boolean header() default false;
};
7.3.4.3. Example

Java Source:

@WebService(targetNamespace="http://www.openuri.org/jwsm/WebParamExample")
@SOAPBinding(style=SOAPBinding.Style.RPC)
public class PingService {

   @WebMethod(operationName = "PingOneWay")
   @Oneway
   public void ping(PingDocument ping) {
   }

   @WebMethod(operationName = "PingTwoWay")
   public void ping(
     @WebParam(mode=WebParam.Mode.INOUT)
        PingDocumentHolder ping) {
   }

   @WebMethod(operationName = "SecurePing")
   @Oneway
   public void ping(
      PingDocument ping,
      @WebParam(header=true)
         SecurityHeader secHeader) {
   }
};

Resulting WSDL:

<definitions
  xmlns="http://schemas.xmlsoap.org/wsdl/"
  xmlns:tns="http://www.openuri.org/jwsm/WebParamExample"
  xmlns:wsdl="http://www.openuri.org/jwsm/WebParamExample"
  xmlns:s="http://www.w3.org/2001/XMLSchema"
  xmlns:soap="http://schemas.xmlsoap.org/wsdl/soap/"
  targetNamespace="http://www.openuri.org/jwsm/WebParamExample">

  <types>
     <s:schema elementFormDefault="qualified"
targetNamespace="http://www.openuri.org/jwsm/WebParamExample">
        <s:complexType name="PingDocument">
           . . .
        </s:complexType>
        <s:complexType name="SecurityHeader">
           . . .
        </s:complexType>
        <s:element name="SecurityHeader" type="SecurityHeader"/>
     </s:schema>
  </types>

  <message name="PingOneWay">
     <part name="arg0" type="tns:PingDocument"/>
  </message>

  <message name="PingTwoWay">
     <part name="arg0" type="tns:PingDocument"/>
  </message>

  <message name="PingTwoWayResponse">
     <part name="arg0" type="tns:PingDocument"/>
  </message>

  <message name="SecurePing">
     <part name="arg0" type="tns:PingDocument"/>
     <part name="arg1" element="tns:SecurityHeader"/>
  </message>

  <portType name="PingService">
     <operation name="PingOneWay">
        <input message="tns:PingOneWay"/>
     </operation>

     <operation name="PingTwoWay">
        <input message="tns:PingTwoWay"/>
        <output message="tns:PingTwoWayResponse"/>
     </operation>

     <operation name="SecurePing">
        <input message="tns:SecurePing"/>
     </operation>
  </portType>

  <binding name="PingServiceHttpSoap" type="tns:PingService">
     <soap:binding style="rpc" transport="http://schemas.xmlsoap.org/soap/http" />
     <operation name="PingOneWay">
        <soap:operation soapAction="http://openuri.org/PingOneWay"/>
        <input>
           <soap:body parts="arg0" use="literal"/>
        </input>
     </operation>

     <operation name="PingTwoWay">
        <soap:operation soapAction="http://openuri.org/PingTwoWay"/>
        <input>
           <soap:body parts="arg0" use="literal"/>
        </input>
        <output>
           <soap:body parts="arg0" use="literal"/>
        </output>
     </operation>

     <operation name="SecurePing">
        <soap:operation soapAction="http://openuri.org/SecurePing"/>
        <input>
           <soap:body parts="arg0" use="literal"/>
           <soap:header message="SecurePing" part="arg1" use="literal"/>
        </input>
     </operation>
  </binding>
</definitions>

7.3.5. Annotation: jakarta.jws.WebResult

7.3.5.1. Description

Customizes the mapping of the return value to a WSDL part and XML element.

Member-Value Meaning Default

name

Name of return value.

If the operation is rpc style and @WebResult.partName has not been specified, this is the name of the wsdl:part representing the return value.

If the operation is document style or the return value maps to a header, this is the local name of the XML element representing the return value.

@WebParam.operation Name+”Response,” if the operation is document style and the parameter style is BARE.

Otherwise, the default is “return.”

partName

The name of the wsdl:part representing this return value. This is only used if the operation is rpc style, or if the operation is document style and the parameter style is BARE.

@WebResult.name

targetNamespace

The XML namespace for the return value.

Only used if the operation is document style or the return value maps to a header.

If the target namespace is set to “ ”, this represents the empty namespace.

The empty namespace, if the operation is document style, the parameter style is WRAPPED, and the return value does not map to a header,

Otherwise, the default is the targetNamespace for the Web Service.

header

If true, the parameter is in the message header rather then the message body.

False

7.3.5.2. Annotation Type Definition
@Retention(value=RetentionPolicy.RUNTIME)
@Target({METHOD})
public @interface WebResult {
  String name() default "";
  String partName() default "";
  String targetNamespace() default "";
  boolean header() default false;
};
7.3.5.3. Example

Java Source:

@WebService
public class CustomerService {

   @WebMethod
   @WebResult(name="CustomerRecord")
   public CustomerRecord locateCustomer(
      @WebParam(name="FirstName") String firstName,
      @WebParam(name="LastName") String lastName,
      @WebParam(name="Address") USAddress addr) {
   }
};

Resulting WSDL:

<definitions>
   <types>
      <complexType name="CustomerRecord">
         ...
      </complexType>

      <complexType name="USAddress">
         ...
      </complexType>

      <element name="locateCustomer">
        <complexType>
          <sequence>
            <element name="FirstName" type="xs:string"/>
            <element name="LastName" type="xs:string"/>
            <element name="Address" type="USAddress"/>
          </sequence>
        </complexType>
     </element>

     <element name="locateCustomerResponse">
       <complexType>
         <sequence>
            <element name="CustomerRecord" type="CustomerRecord"/>
         </sequence>
       </complexType>
     </element>
    </types>

    <message name="locateCustomer">
       <part name="parameters" element="tns:locateCustomer"/>
    </message>

    <message name="locateCustomerResponse">
       <part name="parameters" element="tns:locateCustomerResponse"/>
    </message>

    <portType name="CustomerService">
       <operation name="locateCustomer">
          <input message="tns:locateCustomer"/>
          <output message="tns:locateCustomerResponse"/>
       </operation>
    </portType>
</definitions>

7.3.6. Annotation: jakarta.jws.HandlerChain

7.3.6.1. Description

The @HandlerChain annotation associates the Web Service with an externally defined handler chain (Jakarta XML Web Services Specification [5], Section 9).

It is an error to combine this annotation with the @SOAPMessageHandlers annotation.

The @HandlerChain annotation MAY be present on the endpoint interface and service implementation bean. The service implementation bean’s @HandlerChain is used if @HandlerChain is present on both.

The @HandlerChain annotation MAY be specified on the type only. The annotation target includes METHOD and FIELD for use by Jakarta XML Web Services Specification [5]. A Jakarta Web Services Metadata Processor is REQUIRED to report an error if the @HanderChain annotation is used on a method.

The @HandlerChain annotation contains the following member-values:

Member-Value Meaning Default

File

Location of the handler chain file. The location supports 2 formats.

1. An absolute java.net.URL in externalForm. (ex: http://myhandlers.foo.com/handlerfile1.xml)

2. A relative path from the source file or class file. (ex: bar/handlerfile1.xml)

None

name

Deprecated as of Jakarta Web Services Metadata 2.0 with no replacement.

The name was originally used to associate a Jakarta XML RPC handler in a handler chain with the web service it is declared in. Jakarta XML Web Services handlers are associated to Web Services through elements in the handler chain itself. In this version, the name is ALWAYS ignored.

This member-value will be permanently removed in a future version of Jakarta Web Services Metadata Specification.

””

7.3.6.2. Annotation Type Definition
@Retention(value=RetentionPolicy.RUNTIME)
@Target({TYPE, METHOD, FIELD})
public @interface HandlerChain {
  String file();
  String name() default "";
};
7.3.6.3. Examples

Example 1

Java Source:

Located in /home/mywork/src/com/jwsm/examples/

package com.jwsm.examples;

@WebService
@HandlerChain(file="config/ProjectHandlers.xml")
public class MyWebService {
};

Handler Chain Configuration File

Located in /home/mywork/src/com/jwsm/examples/config/

<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<bindings
  wsdlLocation="http://localhost:8080/fromwsdl_handler/test?wsdl"
  xmlns="https://jakarta.ee/xml/ns/jaxws">

  <bindings node="ns1:definitions" xmlns:ns1="http://schemas.xmlsoap.org/wsdl/">
    <package name="fromwsdl.handler.client"/>
  </bindings>

  <bindings node="ns1:definitions/ns1:types/xs:schema[@targetNamespace='urn:test:types']"
      xmlns:xs="http://www.w3.org/2001/XMLSchema"
      xmlns:ns1="http://schemas.xmlsoap.org/wsdl/">
    <ns2:schemaBindings xmlns:ns2="https://jakarta.ee/xml/ns/jaxb">
       <ns2:package name="fromwsdl.handler.client"/>
    </ns2:schemaBindings>
  </bindings>

  <bindings>
    <handler-chains xmlns="https://jakarta.ee/xml/ns/jakartaee">
      <handler-chain>
        <handler>
          <handler-class>fromwsdl.handler.common.BaseLogicalHandler</handler-class>
          <init-param>
            <param-name>handlerName</param-name>
            <param-value>client0</param-value>
          </init-param>
        </handler>
      </handler-chain>
      <handler-chain>
        <port-name-pattern xmlns:ns2="urn:test">ns2:Report</port-name-pattern>
        <handler>
          <handler-class>fromwsdl.handler.common.BaseLogicalHandler</handler-class>
          <init-param>
            <param-name>handlerName</param-name>
            <param-value>client2</param-value>
          </init-param>
        </handler>
      </handler-chain>
      <handler-chain>
        <port-name-pattern xmlns:ns2="urn:test">ns2:ReportServicePort</port-name-pattern>
        <handler>
          <handler-class>fromwsdl.handler.common.BaseSOAPHandler</handler-class>
          <init-param>
            <param-name>handlerName</param-name>
            <param-value>client6</param-value>
          </init-param>
        </handler>
      </handler-chain>
      <handler-chain>
        <protocol-bindings>##SOAP11_HTTP</protocol-bindings>
        <handler>
          <handler-class>fromwsdl.handler.common.BaseSOAPHandler</handler-class>
          <init-param>
            <param-name>handlerName</param-name>
            <param-value>client7</param-value>
          </init-param>
          <soap-role>http://sun.com/client/role1</soap-role>
          <soap-role>http://sun.com/client/role2</soap-role>
        </handler>
      </handler-chain>
      <handler-chain>
        <protocol-bindings>##SOAP11_HTTP</protocol-bindings>
        <handler>
          <handler-class>fromwsdl.handler.common.BaseLogicalHandler</handler-class>
          <init-param>
            <param-name>handlerName</param-name>
            <param-value>client3</param-value>
          </init-param>
        </handler>
      </handler-chain>
    </handler-chains>
  </bindings>
</bindings

7.3.7. Annotation: jakarta.jws.soap.SOAPBinding

7.3.7.1. Description

Specifies the mapping of the Web Service onto the SOAP message protocol. Section 6 SOAP Binding describes the effects of this annotation on generated Web Services. The SOAPBinding annotation has a target of TYPE and METHOD. The annotation may be placed on a method if and only if the SOAPBinding.style is DOCUMENT. Implementations MUST report an error if the SOAPBinding annotation is placed on a method with a SOAPBinding.style of RPC. Methods that do not have a SOAPBinding annotation accept the SOAPBinding behavior defined on the type.

The @SOAPBinding annotation includes the following member-value pairs.

Member-Value Meaning Default

style

Defines the encoding style for messages send to and from the Web Service. One of DOCUMENT or RPC.

DOCUMENT

use

Defines the formatting style for messages sent to and from the Web Service. One of LITERAL or ENCODED.

LITERAL

parameterStyle

Determines whether method parameters represent the entire message body, or whether the parameters are elements wrapped inside a top-level element named after the operation.

WRAPPED

7.3.7.2. Annotation Type Definition
@Retention(value=RetentionPolicy.RUNTIME)
@Target({TYPE, METHOD})
public @interface SOAPBinding {
   enum Style {
      DOCUMENT,
      RPC
   };

   enum Use {
      LITERAL,
      ENCODED
   };

   enum ParameterStyle {
       BARE,
       WRAPPED
   }

   Style style() default Style.DOCUMENT;
   Use use() default Use.LITERAL;
   ParameterStyle parameterStyle() default ParameterStyle.WRAPPED;
}
7.3.7.3. Examples

Example 1 – RPC/LITERAL

Java source:

@WebService(targetNamespace="http://www.openuri.org/jwsm/SoapBindingExample1")
@SOAPBinding(
    style = SOAPBinding.Style.RPC,
    use = SOAPBinding.Use.LITERAL)
public class ExampleService {
   @WebMethod
   public String concat(String first, String second, String third) {
      return first + second + third;
   }
}

Resulting WSDL:

<definitions
  xmlns="http://schemas.xmlsoap.org/wsdl/"
  xmlns:tns="http://www.openuri.org/jwsm/SoapBindingExample1"
  xmlns:s="http://www.w3.org/2001/XMLSchema"
  xmlns:soap="http://schemas.xmlsoap.org/wsdl/soap/"
  targetNamespace="http://www.openuri.org/jwsm/SoapBindingExample1">

  <message name="concat">
     <part name="first" type="xs:string"/>
     <part name="second" type="xs:string"/>
     <part name="third" type="xs:string"/>
  </message>

  <message name="concatResponse">
     <part name="return" type="xs:string"/>
  </message>

  <portType name="ExampleService">
     <operation name="concat">
       <input message="tns:concat"/>
       <output message="tns:concatResponse"/>
     </operation>
  </portType>

  <binding name="ExampleServiceHttpSoap" type="ExampleService">
    <soap:binding style="rpc" transport="http://schemas.xmlsoap.org/soap/http"/>
    <operation name="concat">
      <soap:operation soapAction="http://www.openuri.org/jwsm/SoapBindingExample1/concat"/>
      <input>
        <soap:body parts="first second third" use="literal"/>
      </input>
      <output>
        <soap:body parts="return" use="literal"/>
      </output>
    </operation>
   </binding>
</definitions>

Example 2 – DOCUMENT/LITERAL/BARE

Java source:

@WebService(targetNamespace="http://www.openuri.org/jwsm/SoapBindingExample2")
@SOAPBinding(parameterStyle=SOAPBinding.ParameterStyle.BARE)
public class DocBareService {

   @WebMethod( operationName="SubmitPO" )
   public SubmitPOResponse submitPO(SubmitPORequest submitPORequest) {
   }
}

Resulting WSDL:

<definitions
  xmlns="http://schemas.xmlsoap.org/wsdl/"
  xmlns:tns="http://www.openuri.org/jwsm/SoapBindingExample2"
  xmlns:s="http://www.w3.org/2001/XMLSchema"
  xmlns:soap="http://schemas.xmlsoap.org/wsdl/soap/"
  targetNamespace="http://www.openuri.org/jwsm/SoapBindingExample2">

  <types>
     <s:schema elementFormDefault="qualified" targetNamespace="http://www.openuri.org/jwsm/SoapBindingExample2">
        <s:element name="SubmitPORequest">
            . . .
        </s:element>
        <s:element name="SubmitPOResponse">
            . . .
        </s:element>
     </s:schema>
  </types>

  <message name="SubmitPO">
     <part name="parameters" element="tns:SubmitPORequest"/>
  </message>

  <message name="SubmitPOResponse">
     <part name="parameters" element="tns:SubmitPOResponse"/>
  </message>

  <portType name="DocBareService">
     <operation name="SubmitPO">
        <input message="tns:SubmitPO"/>
        <output message="tns:SubmitPOResponse"/>
     </operation>
  </portType>

  <binding name="DocBareServiceHttpSoap" type="ExampleService">
     <soap:binding style="document" transport="http://schemas.xmlsoap.org/soap/http"/>
     <operation name="SubmitPO">
        <soap:operation soapAction="http://www.openuri.org/jwsm/SoapBindingExample2/SubmitPO />
        <input>
           <soap:body parts="parameters" use="literal"/>
        </input>
        <output>
           <soap:body parts="parameters" use="literal"/>
        </output>
     </operation>
  </binding>
</definitions>

Example 3 – DOCUMENT/LITERAL/WRAPPED

Java source:

@WebService(targetNamespace="http://www.openuri.org/jwsm/SoapBindingExample3")
@SOAPBinding(
  style = SOAPBinding.Style.DOCUMENT,
  use = SOAPBinding.Use.LITERAL,
  parameterStyle = SOAPBinding.ParameterStyle.WRAPPED)
public class DocWrappedService {

   @WebMethod(operationName = "SubmitPO")
   @WebResult(name="PurchaseOrderAck")
   public PurchaseOrderAck submitPO(
       @WebParam(name="PurchaseOrder") PurchaseOrder purchaseOrder) {
   }
}

Resulting WSDL:

<definitions
  xmlns="http://schemas.xmlsoap.org/wsdl/"
  xmlns:tns="http://www.openuri.org/jwsm/SoapBindingExample3"
  xmlns:s="http://www.w3.org/2001/XMLSchema"
  xmlns:soap="http://schemas.xmlsoap.org/wsdl/soap/"
  targetNamespace="http://www.openuri.org/jwsm/SoapBindingExample3">

  <types>
    <s:schema elementFormDefault="qualified" targetNamespace="http://www.openuri.org/jwsm/SoapBindingExample3">
       <s:element name="SubmitPO">
         <complexType>
           <sequence>
             <element name="PurchaseOrder" type="tns:PurchaseOrder"/>
                . . .
       </s:element>

       <s:element name="SubmitPOResponse">
           . . .
       </s:element>

    </s:schema>
  </types>

  <message name="SubmitPO">
     <part name="parameters" element="tns:SubmitPO"/>
  </message>

  <message name="SubmitPOResponse">
     <part name="parameters" type="tns:SubmitPOResponse"/>
  </message>

  <portType name="DocWrappedService">
     <operation name="SubmitPO">
        <input message="tns:SubmitPO"/>
        <output message="tns:SubmitPOResponse"/>
     </operation
  </portType>

  <binding name="ExampleServiceHttpSoap" type="ExampleService">
    <soap:binding style="document" transport="http://schemas.xmlsoap.org/soap/http"/>
    <operation name="SubmitPO">
      <soap:operation soapAction="http://www.openuri.org/jwsm/SoapBindingExample3/SubmitPO" />
      <input>
        <soap:body parts="parameters" use="literal"/>
      </input>
      <output>
        <soap:body parts="parameters" use="literal"/>
      </output>
    </operation>
  </binding>
</definitions>

7.3.8. Annotation: jakarta.jws.soap.SOAPMessageHandlers

Deprecated as of Jakarta Web Services Metadata 2.0 with no replacement.

This annotation was originally used to create a Jakarta XML RPC handler chain. In this version, the annotation is ALWAYS ignored.

This annotation will be permanently removed in a future version of Jakarta Web Services Metadata Specification.

7.4. Java Mapping To XML/WSDL

A key goal of Jakarta Web Services Metadata is to influence the shape of WSDL generated from a JWS. This section defines the mapping from Java to XML/WSDL. By default, Jakarta Web Services Metadata follows the Java to XML/WSDL mapping defined in Jakarta XML Web Services Specification [5] section 3, except as noted in this section. Implementations MAY extend or supplement this mapping, for example, by adding more complete schema support or supporting alternate binding frameworks such as Jakarta XML Binding or SDO (JSR-235). Annotations for such extensions are out-of-scope for this specification.

7.4.1. Service Endpoint Interface

Jakarta XML Web Services defines a service endpoint interface as the Java representation of an abstract WSDL contract. A service endpoint interface MAY include the following Jakarta Web Services Metadata annotations to customize its mapping to WSDL:

  • @WebService.name, @WebService.targetNamespace, and @WebService.wsdlLocation

  • @WebMethod (all annotation elements)

  • @Oneway

  • @WebParam (all annotation elements)

  • @WebResult (all annotation elements)

  • @SOAPBinding (all annotation elements)

A service endpoint interface maps to a wsdl:portType element within the wsdl:definitions for the containing package. The local name and namespace of the wsdl:portType map to the values of the service endpoint interface’s @WebService.name and @WebService.targetNamespace annotation elements, respectively.

7.4.2. Web Service Class Mapping

A service implementation bean maps to its own WSDL document, wsdl:portType, and wsdl:service. If the service implementation bean references a service endpoint interface through the @WebService.endpointInterface annotation, the wsdl:portType and wsdl:binding sections are mapped according to that service endpoint interface. Otherwise, the following rules apply:

  • The wsdl:definitions targetNamespace maps to the value of the @WebService.targetNamespace member-value.

  • The local name of the wsdl:portType maps to the value of the @WebService.name member-value.

  • The local name of the wsdl:service maps to the value of the @WebService.serviceName member-value.

  • The wsdl:service MUST contain a distinct wsdl:port for every transport endpoint supported by the service.

  • Each wsdl:port MUST be of the same wsdl:portType, but MAY have different bindings.

  • The local name of the wsdl:port maps to the value of the @WebService.portName member-value.

  • The name wsdl:binding sections is not significant and are left implementation-defined.

7.4.3. Web Method Mapping

Each exposed web method in a Jakarta Web Services Metadata annotated class or interface is mapped to a wsdl:operation on the class/interface WSDL portType. The wsdl:operation local name maps to the value of the @WebMethod.operationName member-value, if @WebMethod.operationName is present. If @WebMethod.operationName is not present, the wsdl:operation local name is mapped from the name of the Java method according to the rules defined in Jakarta XML Web Services Specification [5], section 3.5.

The mapped wsdl:operation contains both wsdl:input and wsdl:output elements, unless the method is annotated as @Oneway. @Oneway methods have only a wsdl:input element.

Java types used as method parameters, return values, and exceptions are mapped according to the rules defined in Jakarta XML Web Services [5], section 3.6.

7.5. SOAP Binding

This section defines a standard mapping from a service endpoint interface or service implementation bean to the SOAP 1.1 binding. Implementers MAY also support other bindings, but these bindings are non-standard. If Jakarta Web Services Metadata implementation supports bindings other than SOAP 1.1, it MUST include a mechanism to selectively enable or disable these bindings.

By default Jakarta Web Services Metadata Specification follows the SOAP binding defined in Jakarta XML Web Services Specification [5], section 10.

7.5.1. Operation Modes

Jakarta Web Services Metadata implementations are REQUIRED to support the following WS-I compliant operation modes:

  • Operations with the rpc style and literal use (rpc/literal)

  • Operations with the document style and literal use (document/literal).

Implementations MAY optionally support operation modes with the encoded use (document or rpc style). The developer MAY indicate which operation mode is in effect by specifying the appropriate @SOAPBinding.style and @SOAPBinding.use annotations at the class or interface level.

7.5.1.1. RPC Operation Style

In the RPC operation style, the parameters and return values map to separate parts on the WSDL input and output messages. The @WebParam.mode annotation determines the messages in which a particular parameter appears. IN parameters appear as parts in the input message, OUT parameters appear as parts in the output message, and INOUT parameters appear as parts in both messages. The order of parameters in the method signature determines the order of the parts in the input and output message. The return value is the first part in the output message.

In the rpc/literal operation mode, each message part refers to a concrete schema type. The schema type is derived from the Java type for the parameter, as described in section 5 Java Mapping To XML/WSDL.

7.5.1.2. Document Operation Style

In the document operation style, the input and output WSDL messages have a single part referencing a schema element that defines the entire body. Jakarta Web Services Metadata implementations MUST support both the “wrapped” and “bare” styles of document / literal operation. The developer may specify which of these styles is in effect for a particular operation by using the @SOAPBinding.parameterStyle annotation.

7.5.1.3. Document “Wrapped” Style

In the “wrapped” operation style, the input and output messages contain a single part which refers (through the element attribute) to a global element declaration (the wrapper) of complexType defined using the xsd:sequence compositor. The global element declaration for the input message has a local name equal to @WebMethod.operationName. The global element declaration for the output message (if it exists) has a local name equal to @WebMethod.operationName + “Response”. Both global element declarations appear in the @WebService.targetNamespace.

Non-header method parameters and return values map to child elements of the global element declarations defined for the method. The order of parameters in the parameter list determines the order in which the equivalent child elements appear in the operation’s global element declarations.

The @WebParam.name and @WebParam.targetNamespace annotation elements determine the QName of a parameter’s child element, while the @WebResult.name and @WebResult.targetNamespace annotations determines the QName of the return value’s child element. The schema type for each child element is derived from the type of the Java parameter or return value, as described in section 5 Java Mapping To XML/WSDL.

7.5.1.4. Document “Bare” Style

In the “bare” operation style, the input and output messages contain a single part which refers (through the element attribute) to an element that is mapped from the method parameter and return value. The QName of the input body element is determined by the values of the @WebParam.name and @WebParam.targetNamespace annotations on the method parameter, and the QName of the output body element is determined by the values of the @WebResult.name and @WebResult.targetNamespace annotations. The schema types for the input and output body elements are derived from the types of the Java parameter or return values, as described in section 5 Java Mapping To XML/WSDL.

Web Services that use the document “bare” style MUST adhere to the following restrictions:

  • If the operation is marked @Oneway, it MUST have a void return value, a single non-header parameter marked as IN, and zero or more header parameters.

  • If the operation is not marked @Oneway, it may have one of the following forms:

  • A non-header parameter marked as IN, a non-header parameter marked as OUT, a void return value, and zero or more header parameters.

  • A single non-header parameters marked as IN_OUT, a void return value, and zero or more header parameters.

  • A single non-header parameter marked as IN, non-void return value and zero or more header parameters.

  • The XML elements for the input and output messages MUST be unique across all operations on the Web Service. Consequently, either every document “bare” operation on the Web Service MUST take and return Java types that map to distinct elements, or the developer MUST use the @WebParam and @WebResult annotations to explicitly specify the QNames of the input and output XML elements for each operation.

7.5.2. Headers

Parameters annotated with the @WebParam.header annotation element map to SOAP headers instead of elements in the SOAP body. Header parameters appear as parts in the operation’s input message, output message, or both depending on the value of the @WebParam.mode annotation element. Header parameters are included as soap:header elements in the appropriate wsdl:input and wsdl:output sections of the binding operation. Headers are always literal. The @WebParam.name and @WebParam.targetNamespace annotations determine the QName of the XML element representing the header.

Results annotated with the @WebResult.header annotation element map to SOAP headers instead of elements in the SOAP body. Header results appear as parts in the operation’s output message. Header results are included as soap:header elements in the appropriate wsdl:output sections of the binding operation. Headers are always literal. The @WebResult.name and @WebResult.targetNamespace annotations determine the QName of the XML element representing the header. This QName MUST be unique within all headers of the method.

7.6. Using Jakarta Web Services Metadata Annotations to Affect the Shape of the WSDL

7.6.1. RPC Literal Style

Below is a complete example of a java source file with annotations followed by the resulting WSDL:

Java source:

import jakarta.jws.*;
import jakarta.jws.soap.*;

@WebService(
  name="ExampleWebService",
  targetNamespace="http://openuri.org/11/2003/ExampleWebService")
@SOAPBinding(style=SOAPBinding.Style.RPC, use=SOAPBinding.Use.LITERAL)
public class ExampleWebServiceImpl {

   @WebMethod(action="urn:login")
   @WebResult(name="Token")
   public LoginToken login(
      @WebParam(name="UserName") String username,
      @WebParam(name="Password") String password) {
     // ...
   }

   @WebMethod (action="urn:createCustomer")
   @WebResult(name="CustomerId")
   public String createCustomer(
      @WebParam(name="Customer") Customer customer,
      @WebParam(name="Token", header=true) LoginToken token) {
      // ...
   }

   @WebMethod(action="urn:notifyTransfer")
   @Oneway
   public void notifyTransfer(
      @WebParam(name="CustomerId") String customerId,
      @WebParam(name="TransferData") TransferDocument transferData,
      @WebParam(name="Token", header=true) LoginToken token) {
   }
};

Resulting WSDL:

<definitions
  name="ExampleWebServiceImplServiceDefinitions"
  targetNamespace="http://openuri.org/11/2003/ExampleWebService"
  xmlns="http://schemas.xmlsoap.org/wsdl/"
  xmlns:tns="http://openuri.org/11/2003/ExampleWebService"
  xmlns:xs="http://www.w3.org/2001/XMLSchema"
  xmlns:soap="http://schemas.xmlsoap.org/wsdl/soap/">

  <types>
    <xs:schema elementFormDefault="qualified"
       targetNamespace="http://openuri.org/11/2003/ExampleWebService">

      <xs:complexType name="LoginToken">
         ...
      </xs:complexType>

      <xs:complexType name="Customer">
         ...
      </xs:complexType>

      <xs:complexType name="TransferDocument">
         ...
      </xs:complexType>

      <xs:element name="Token" type="LoginToken"/>

    </xs:schema>
  </types>

  <message name="createCustomer">
    <part name="Customer" type="tns:Customer"/>
    <part element="tns:Token" name="token"/>
  </message>

  <message name="createCustomerResponse">
    <part name="CustomerId" type="xs:string"/>
  </message>

  <message name="notifyTransfer">
    <part name="CustomerId" type="xs:string"/>
    <part name="TransferData" type="tns:TransferDocument"/>
    <part name="token" element="tns:Token"/>
  </message>

  <message name="login">
    <part name="UserName" type="xs:string"/>
    <part name="Password" type="xs:string"/>
  </message>

  <message name="loginResponse">
    <part name="Token" type="tns:LoginToken"/>
  </message>

  <portType name="ExampleWebService">
    <operation name="createCustomer" parameterOrder="Customer token">
      <input message="tns:createCustomer"/>
      <output message="tns:createCustomerResponse"/>
    </operation>

    <operation name="notifyTransfer" parameterOrder="CustomerId TransferData token">
      <input message="tns:notifyTransfer"/>
    </operation>

    <operation name="login" parameterOrder="UserName Password">
      <input message="tns:login"/>
      <output message="tns:loginResponse"/>
    </operation>

  </portType>

  <binding name="ExampleWebServiceImplServiceSoapBinding"
      type="tns:ExampleWebService">
    <soap:binding style="rpc"
      transport="http://schemas.xmlsoap.org/soap/http"/>

    <operation name="createCustomer">
      <soap:operation soapAction="urn:createCustomer" style="rpc"/>
      <input>
        <soap:body
          namespace="http://openuri.org/11/2003/ExampleWebService"
          parts="Customer"
          use="literal"/>
        <soap:header
          message="tns:createCustomer"
          part="token"
          use="literal"/>
      </input>
      <output>
        <soap:body
          namespace="http://openuri.org/11/2003/ExampleWebService"
          parts="CustomerId"
          use="literal"/>
      </output>
    </operation>

    <operation name="notifyTransfer">
      <soap:operation soapAction="urn:notifyTransfer" style="rpc"/>
      <input>
        <soap:body
           namespace="http://openuri.org/11/2003/ExampleWebService"
           parts="CustomerId TransferData"
           use="literal"/>
        <soap:header
           message="tns:notifyTransfer"
           part="token"
           use="literal"/>
      </input>
    </operation>

    <operation name="login">
      <soap:operation soapAction="urn:login" style="rpc"/>
      <input>
        <soap:body
           namespace="http://openuri.org/11/2003/ExampleWebService"
           parts="UserName Password"
           use="literal"/>
      </input>
      <output>
        <soap:body
           namespace="http://openuri.org/11/2003/ExampleWebService"
           parts="Token"
           use="literal"/>
      </output>
    </operation>
  </binding>

  <service name="ExampleWebServiceImplService">
    <port
      binding="s1:ExampleWebServiceImplServiceSoapBinding"
      name="ExampleWebServiceSoapPort">
      <soap:address
        location="http://localhost:7001/ExampleWebServiceImpl/ExampleWebServiceImpl"/>
    </port>
  </service>
</definitions>

7.6.2. Document Literal Style

Below is a complete example of a java source file with annotations followed by the resulting WSDL:

Java source:

import jakarta.jws.*;
import jakarta.jws.soap.*;

@WebService(
  name="ExampleWebService",
  targetNamespace="http://openuri.org/11/2003/ExampleWebService")
@SOAPBinding(style=SOAPBinding.Style.DOCUMENT,
  use=SOAPBinding.Use.LITERAL)
public class ExampleWebServiceImpl {

   @WebMethod(action="urn:login")
   @WebResult(name="Token")
   public LoginToken login(
      @WebParam(name="UserName") String username,
      @WebParam(name="Password") String password) {
     // ...
   }

   @WebMethod (action="urn:createCustomer")
   @WebResult(name="CustomerId")
   public String createCustomer(
      @WebParam(name="Customer") Customer customer,
      @WebParam(name="Token", header=true) LoginToken token) {
      // ...
   }

   @WebMethod(action="urn:notifyTransfer")
   @Oneway
   public void notifyTransfer(
      @WebParam(name="CustomerId") String customerId,
      @WebParam(name="TransferData") TransferDocument transferData,
      @WebParam(name="Token", header=true) LoginToken token) {
   }

};

Resulting WSDL:

<?xml version='1.0' encoding='UTF-8'?>
<definitions
  name="ExampleWebServiceImplServiceDefinitions"
  targetNamespace="http://openuri.org/11/2003/ExampleWebService"
  xmlns="http://schemas.xmlsoap.org/wsdl/"
  xmlns:tns="http://openuri.org/11/2003/ExampleWebService"
  xmlns:xs="http://www.w3.org/2001/XMLSchema"
  xmlns:soap="http://schemas.xmlsoap.org/wsdl/soap/">

  <types>
    <xs:schema attributeFormDefault="unqualified"
        targetNamespace="http://openuri.org/11/2003/ExampleWebService">

      <xs:complexType name="LoginToken">
          ...
      </xs:complexType>

      <xs:complexType name="Customer">
          ...
      </xs:complexType>

      <xs:complexType name="TransferDocument">
          ...
      </xs:complexType>

      <xs:element name="Token" type="tns:LoginToken"/>

      <xs:element name="createCustomer">
        <xs:complexType>
          <xs:sequence>
            <xs:element name="Customer" type="tns:Customer"/>
          </xs:sequence>
        </xs:complexType>
      </xs:element>

      <xs:element name="createCustomerResponse">
        <xs:complexType>
          <xs:sequence>
            <xs:element name="CustomerId" type="xs:string"/>
          </xs:sequence>
        </xs:complexType>
      </xs:element>

      <xs:element name="notifyTransfer">
        <xs:complexType>
          <xs:sequence>
            <xs:element name="CustomerId" type="xs:string"/>
            <xs:element name="TransferData" type="tns:TransferDocument"/>
          </xs:sequence>
        </xs:complexType>
      </xs:element>

      <xs:element name="login">
        <xs:complexType>
          <xs:sequence>
            <xs:element name="UserName" type="xs:string"/>
            <xs:element name="Password" type="xs:string"/>
          </xs:sequence>
        </xs:complexType>
      </xs:element>

      <xs:element name="loginResponse">
        <xs:complexType>
          <xs:sequence>
            <xs:element name="Token" type="tns:LoginToken"/>
          </xs:sequence>
        </xs:complexType>
      </xs:element>
    </xs:schema>
  </types>

  <message name="createCustomer">
    <part element="tns:createCustomer" name="parameters"/>
    <part element="tns:Token" name="token"/>
  </message>

  <message name="createCustomerResponse">
    <part element="tns:createCustomerResponse" name="parameters"/>
  </message>

  <message name="notifyTransfer">
    <part element="tns:notifyTransfer" name="parameters"/>
    <part element="tns:Token" name="token"/>
   </message>

  <message name="login">
    <part element="tns:login" name="parameters"/>
  </message>

  <message name="loginResponse">
    <part element="tns:loginResponse" name="parameters"/>
  </message>

  <portType name="ExampleWebService">
    <operation name="createCustomer" parameterOrder="parameters token">
      <input message="tns:createCustomer"/>
      <output message="tns:createCustomerResponse"/>
    </operation>

    <operation name="notifyTransfer" parameterOrder="token">
      <input message="tns:notifyTransfer"/>
    </operation>

    <operation name="login" parameterOrder="parameters">
      <input message="tns:login"/>
      <output message="tns:loginResponse"/>
    </operation>
  </portType>

  <binding name="ExampleWebServiceImplServiceSoapBinding" type="tns:ExampleWebService">
    <soap:binding style="document" transport="http://schemas.xmlsoap.org/soap/http"/>
    <operation name="createCustomer">
      <soap:operation soapAction="urn:createCustomer" style="document"/>
      <input>
        <soap:body parts="parameters" use="literal"/>
        <soap:header message="tns:createCustomer" part="token" use="literal"/>
      </input>
      <output>
        <soap:body parts="parameters" use="literal"/>
      </output>
    </operation>

    <operation name="notifyTransfer">
      <soap:operation soapAction="urn:notifyTransfer" style="document"/>
      <input>
        <soap:body parts="parameters" use="literal"/>
        <soap:header message="tns:notifyTransfer" part="token" use="literal"/>
      </input>
    </operation>

    <operation name="login">
      <soap:operation soapAction="urn:login" style="document"/>
      <input>
        <soap:body parts="parameters" use="literal"/>
      </input>
      <output>
        <soap:body parts="parameters" use="literal"/>
      </output>
    </operation>
  </binding>

  <service name="ExampleWebServiceImplService">
    <port binding="tns:ExampleWebServiceImplServiceSoapBinding" name="ExampleWebServiceSoapPort">
      <soap:address
           location="http://localhost:7001/ExampleWebServiceImpl/ExampleWebServiceImpl"/>
    </port>
</service>
</definitions>

8. Annotations

This chapter describes the annotations used by Jakarta XML Web Services.

For simplicity, when describing an annotation we use the term "property" in lieu of the more correct "annotation elements". Also, for each property we list the default value, which is the default as it appears in the declaration of the annotation type. Often properties have logical defaults which are computed based on contextual information and, for this reason, cannot be captured using the annotation element default facility built into the language. In this case, the text describes what the logical default is and how it is computed.

Jakarta XML Web Services uses annotations extensively. For an annotation to be correct, besides being syntactically correct, e.g. placed on a program element of the appropriate type, it must obey a set of constraints detailed in this specification. For annotations defined by Jakarta XML Web Services Metadata, the annotation in question must also obey the constraints in the relevant specification (see [16]).

Conformance (Correctness of annotations): An implementation MUST check at runtime that the annotations pertaining to a method being invoked, either on the client or on the server, as well as any containing program elements (i.e. classes, 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, an implementation MUST NOT invoke the remote operation being invoked, if any. Instead, it MUST throw a WebServiceException, setting its cause to an exception approximating the cause of the error (e.g. an IllegalArgumentException or a ClassNotFoundException).

  • In a server setting, annotation, an implementation MUST NOT dispatch to an endpoint implementation object. Rather, it MUST generate a fault appropriate to the binding in use.

Conformance (Unsupported WebServiceFeatureAnnotation): If an unrecongnized or unsupported annotation annotated with the WebServiceFeatureAnnotation meta-annotation:

  • In a client setting, an implementation MUST NOT invoke the remote operation being invoked, if any. Instead, it MUST throw a WebServiceException, setting its cause to an exception approximating the cause of the error (e.g. an IllegalArgumentException or a ClassNotFoundException).

  • In a server setting, annotation, an implementation MUST NOT dispatch to an endpoint implementation object. Rather, it MUST generate a fault appropriate to the binding in use.

An implementation may check for correctness in a lazy way, at the time a method is invoked or a request is about to be dispatched to an endpoint, or more aggressively, e.g. when creating a proxy. In a container environment, an implementation may perform any correctness checks at deployment time.

8.1. jakarta.xml.ws.ServiceMode

The ServiceMode annotation is used to specify the mode for a provider class, i.e. whether a provider wants to have access to protocol message payloads (e.g. a SOAP body) or the entire protocol messages (e.g. a SOAP envelope).

Table 4. ServiceMode properties.
Property Description Default

value

The service mode, one of jakarta.xml.ws.Service.Mode. MESSAGE or jakarta.xml.ws.Service.Mode.PAYLOAD. MESSAGE means that the whole protocol message will be handed to the provider instance, PAYLOAD that only the payload of the protocol message will be handed to the provider instance.

jakarta.xml.ws.Service.Mode.PAYLOAD

The ServiceMode annotation type is marked @Inherited, so the annotation will be inherited from the superclass.

8.2. jakarta.xml.ws.WebFault

The WebFault annotation is used when mapping WSDL faults to Java exceptions, see Section 2.5, “Fault”. It is used to capture the name of the fault element used when marshalling the Jakarta XML Binding type generated from the global element referenced by the WSDL fault message. It can also be used to customize the mapping of service specific exceptions to WSDL faults.

Table 5. WebFault properties.
Property Description Default

name

The local name of the element

””

targetNamespace

The namespace name of the element

””

faultBean

The fully qualified name of the fault bean class

””

messageName

The name of the wsdl:message

””

8.3. jakarta.xml.ws.RequestWrapper

The RequestWrapper annotation is applied to the methods of an SEI. It is used to capture the Jakarta XML Binding generated request wrapper bean and the element name and namespace for marshalling / unmarshalling the bean. 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. When starting from Java, this annotation is used to resolve overloading conflicts in document literal mode. Only the className element is required in this case.

Table 6. RequestWrapper properties.
Property Description Default

localName

The local name of the element

””

targetNamespace

The namespace name of the element

””

className

The name of the wrapper class

””

partName

The name of the wsdl:part

””

8.4. jakarta.xml.ws.ResponseWrapper

The ResponseWrapper annotation is applied to the methods of an SEI. It is used to capture the Jakarta XML Binding generated response wrapper bean and the element name and namespace for marshalling / unmarshalling the bean. 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. When starting from Java, this annotation is used to resolve overloading conflicts in document literal mode. Only the className element is required in this case.

Table 7. ResponseWrapper properties.
Property Description Default

localName

The local name of the element

””

targetNamespace

The namespace name of the element

””

className

The name of the wrapper class

””

partName

The name of the wsdl:part

””

8.5. jakarta.xml.ws.WebServiceClient

The WebServiceClient annotation is specified on a generated service class (see Section 2.7, “Service and Port”). It is used to associate a class with a specific Web service, identify by a URL to a WSDL document and the qualified name of a wsdl:service element.

Table 8. WebServiceClient properties.
Property Description Default

name

The local name of the service

””

targetNamespace

The namespace name of the service

””

wsdlLocation

The URL for the WSDL description of the service

””

When resolving the URI specified as the wsdlLocation element or any document it may transitively reference, a Jakarta XML Web Services implementation MUST use the catalog facility defined in Section 4.4, “Catalog Facility”.

8.6. jakarta.xml.ws.WebEndpoint

The WebEndpoint annotation is specified on the getPortName() methods of a generated service class (see Section 2.7, “Service and Port”). It is used to associate a get method with a specific wsdl:port, identified by its local name (a NCName).

Table 9. WebEndpoint properties.
Property Description Default

name

The local name of the port

””

8.6.1. Example

The following shows a WSDL extract and the resulting generated service class.

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
<!-- 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",
                  targetNamespace="...",
                  wsdlLocation="...")
public class StockQuoteService extends jakarta.xml.ws.Service {
    public StockQuoteService() {
        super(wsdlLocation_fromAnnotation, serviceName_fromAnnotation);
    }

    public StockQuoteService(String wsdlLocation, QName serviceName) {
        super(wsdlLocation, serviceName);
    }

    // Other StockQuoteService constructors
    ...

    @WebEndpoint(name="StockQuoteHTTPPort")
    public StockQuoteProvider getStockQuoteHTTPPort() {
        return super.gePort(portName, StockQuoteProvider.class);
    }

    @WebEndpoint(name="StockQuoteHTTPPort")
    public StockQuoteProvider getStockQuoteHTTPPort(WebServiceFeature... f) {
        return super.gePort(portName, StockQuoteProvider.class, f);
    }

    @WebEndpoint(name="StockQuoteSMTPPort")
    public StockQuoteProvider getStockQuoteSMTPPort() {
        return super.getPort(portName, StockQuoteProvider.class);
    }

    @WebEndpoint(name="StockQuoteSMTPPort")
    public StockQuoteProvider getStockQuoteSMTPPort(WebServiceFeature... f) {
        return super.getPort(portName, StockQuoteProvider.class, f);
    }
}

8.7. jakarta.xml.ws.WebServiceProvider

The WebServiceProvider annotation is specified on classes that implement a strongly typed jakarta.xml.ws.Provider. It is used to declare that a class that satisfies the requirements for a provider (see Section 5.1, “jakarta.xml.ws.Provider”) does indeed define a Web service endpoint, much like the WebService annotation does for SEI-based endpoints.

The WebServiceProvider and WebService annotations are mutually exclusive.

Conformance (WebServiceProvider and WebService): A class annotated with the WebServiceProvider annotation MUST NOT carry a WebService annotation.

Table 10. WebServiceProvider properties.
Property Description Default

wsdlLocation

The URL for the WSDL description

””

serviceName

The name of the service

””

portName

The name of the port

””

targetNamespace

The target namespace for the service

””

When resolving the URL specified as the wsdlLocation element or any document it may transitively reference, a Jakarta XML Web Services implementation MUST use the catalog facility defined in Section 4.4, “Catalog Facility”.

8.8. jakarta.xml.ws.BindingType

The BindingType annotation is applied to an endpoint implementation class. It specifies the binding to use when publishing an endpoint of this type.

Table 11. BindingType properties.
Property Description Default

value

The binding ID (a URI)

””

The default binding for an endpoint is the SOAP 1.1/HTTP one (see Chapter 11, SOAP Binding).

8.9. jakarta.xml.ws.WebServiceRef

The WebServiceRef annotation is used to declare a reference to a Web service. It follows the resource pattern exemplified by the jakarta.annotation.Resource annotation in Jakarta Annotations [35].

The injected references of WebServiceRef annotation are not guaranteed to be thread safe. If the references are accessed by multiple threads, usual synchronization techinques can be used to support multiple threads.

The WebServiceRef annotation is required to be honored when running on the Jakarta EE platform, where it is subject to the common resource injection rules described by the platform specification [36].

The injected references of WebServiceRef annotation can be configured with the corresponding features of annotations annotated with WebServiceFeatureAnnotation annotations. For example, a SEI reference can be configured with the MTOM web service feature using @MTOM. Similarly, a generated service reference can be configured with web service features using the corresponding WebServiceFeatureAnnotation annotations. Jakarta XML Web Services specification defines three standard features AddressingFeature, MTOMFeature and RespectBindingFeature that can be used while creating proxy instances. However, there are no standard features that can be used while creating service instances in the current specification. A Jakarta XML Web Services implementation may define its own features but they will be non-portable across all Jakarta XML Web Services implementations.

If a Jakarta XML Web Services implementation encounters an unsupported or unrecognized annotation annotated with the WebServiceFeatureAnnotation that is specified with @WebServiceRef, an error MUST be given.

Table 12. WebServiceRef properties.
Property Description Default

name

The name identifying the Web service reference.

””

wsdlLocation

A URL pointing to the location of the WSDL document for the service being referred to.

””

type

The resource type as a Java class object

Object.class

value

The service type as a Java class object

Service.class

mappedName

A product specific name that this resource should be mapped to.

””

lookup

A portable JNDI lookup name that resolves to the target web service reference.

””

The name of the resource, as defined by the name element (or defaulted) is a name that is local to the application component using the resource. The name can be absolute JNDI name(with a logical namespace) or relative to the JNDI java:comp/env namespace. Many application servers provide a way to map these local names to names of resources known to the application server. This mappedName is often a global JNDI name, but may be a name of any form. Application servers are not required to support any particular form or type of mapped name, nor the ability to use mapped names. A mapped name is product-dependent and often installation-dependent. No use of a mapped name is portable. A defined reference can be resolved using a portable JNDI name provided by lookup element. In this case, it is an error if there are any circular dependencies between entries of references. Similarly, it is an error if looking up the specified JNDI name results in a resource whose type is not compatible with the reference being created. Since this "lookup" functionality is just resolving to an already defined reference, only name can be specified with lookup (doesn’t require any other metadata like wsdlLocation etc.).

There are two uses to the WebServiceRef annotation:

  1. To define a reference whose type is a generated service class. In this case, the type and value element will both refer to the generated service class type. Moreover, if the reference type can be inferred by the field/method declaration the annotation is applied to, the type and value elements MAY have the default value (Object.class, that is). If the type cannot be inferred, then at least the type element MUST be present with a non-default value.

  2. To define a reference whose type is a SEI. In this case, 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, but the value element MUST always be present and refer to a generated service class type (a subtype of jakarta.xml.ws.Service).

The wsdlLocation element, if present, overrides the WSDL location information specified in the WebService annotation of the referenced generated service class.

When resolving the URI specified as the wsdlLocation element or any document it may transitively reference, a Jakarta XML Web Services implementation MUST use the catalog facility defined in Section 4.4, “Catalog Facility”.

8.9.1. Example

The following shows both uses of the WebServiceRef annotation.

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
// Generated Service Class

@WebServiceClient(name="StockQuoteService",
                  targetNamespace="...",
                  wsdlLocation="...")
public class StockQuoteService extends jakarta.xml.ws.Service {
    ...

    @WebEndpoint(name="StockQuoteHTTPPort")
    StockQuoteProvider getStockQuoteHTTPPort() { ... };

    @WebEndpoint(name="StockQuoteHTTPPort")
    StockQuoteProvider getStockQuoteHTTPPort(WebServiceFeature ... f) { ... };

    @WebEndpoint(name="StockQuoteSMTPPort")
    StockQuoteProvider getStockQuoteSMTPPort() { ... };

    @WebEndpoint(name="StockQuoteSMTPPort")
    StockQuoteProvider getStockQuoteSMTPPort(WebServiceFeature ... f) { ... };
}

// Generated SEI

@WebService(name="StockQuoteProvider",
            targetNamespace="...")
public interface StockQuoteProvider {
    Double getStockQuote(String ticker);
}

// Sample client code

@Stateless
public class ClientComponent {

    // WebServiceRef using the generated service interface type
    @WebServiceRef
    public StockQuoteService stockQuoteService;

    // WebServiceRef using the SEI type
    // stockQuoteProvider proxy is configured with MTOM feature
    @MTOM
    @WebServiceRef(StockQuoteService.class)
    private StockQuoteProvider stockQuoteProvider;


    // other methods go here...
}

8.10. jakarta.xml.ws.WebServiceRefs

The WebServiceRefs annotation is used to declare multiple references to Web services on a single class. It is necessary to work around the limition against specifying repeated annotations of the same type on any given class, which prevents listing multiple javax.ws.WebServiceRef annotations one after the other. This annotation follows the resource pattern exemplified by the jakarta.annotation.Resources annotation in Jakarta Annotations [35].

Since no name and type can be inferred in this case, each WebServiceRef annotation inside a WebServiceRefs MUST contain name and type elements with non-default values.

The WebServiceRef annotation is required to be honored when running on the Jakarta EE platform, where it is subject to the common resource injection rules described by the platform specification [36].

Table 13. WebServiceRefs properties.
Property Description Default

value

An array of WebServiceRef annotations, each defining a web service reference.

{}

There is no way to associate web service features with the injected instances of this annotation. If an instance needs to be configured with the web service features, use @WebServiceRef to inject the resource along with its features.

8.10.1. Example

The following shows how to use the WebServiceRefs annotation to declare at the class level two web service references. The first one uses the SEI type, while the second one uses a generated service class type.

1
2
3
4
5
6
7
8
9
10
@WebServiceRefs({@WebServiceRef(name="accounting"
                                type=AccountingPortType.class,
                                value=AccountingService.class),
                 @WebServiceRef(name="payroll",
                                type=PayrollService.class)})
@Stateless
public MyComponent {

    // methods using the declared resources go here...
}

8.11. Annotations Defined by Jakarta XML Web Services Metadata

In addition to the annotations defined in the preceding sections, Jakarta XML Web Services uses several annotations defined by Jakarta XML Web Services Metadata.

Conformance (Jakarta XML Web Services Metadata conformance): A Jakarta XML Web Services 3.0 implementation MUST be conformant to the Jakarta XML Web Services profile of Jakarta XML Web Services Metadata 2.0[16].

As a convenience to the reader, the following sections reproduce the definition of the Jakarta XML Web Services Metadata annotations applicable to Jakarta XML Web Services.

8.11.1. jakarta.jws.WebService

1
2
3
4
5
6
7
8
9
@Target({TYPE})
public @interface WebService {
    String name() default "";
    String targetNamespace() default "";
    String serviceName() default "";
    String wsdlLocation() default "";
    String endpointInterface() default "";
    String portName() default "";
};

Consistently with the URI resolution process in Jakarta XML Web Services, when resolving the URI specified as the wsdlLocation element or any document it may transitively reference, a Jakarta XML Web Services implementation MUST use the catalog facility defined in Section 4.4, “Catalog Facility”.

8.11.2. jakarta.jws.WebMethod

1
2
3
4
5
6
@Target({METHOD})
public @interface WebMethod {
    String operationName() default "";
    String action() default "" ;
    boolean exclude() default false;
};

8.11.3. jakarta.jws.OneWay

1
2
3
@Target({METHOD})
public @interface Oneway {
};

8.11.4. jakarta.jws.WebParam

1
2
3
4
5
6
7
8
9
10
@Target({PARAMETER})
public @interface WebParam {
    enum Mode { IN, OUT, INOUT };

    String name() default "";
    String targetNamespace() default "";
    Mode mode() default Mode.IN;
    boolean header() default false;
    String partName() default "";
};

8.11.5. jakarta.jws.WebResult

1
2
3
4
5
6
7
@Target({METHOD})
public @interface WebResult {
    String name() default "return";
    String targetNamespace() default "";
    boolean header() default false;
    String partName() default "";
};

8.11.6. jakarta.jws.SOAPBinding

1
2
3
4
5
6
7
8
9
10
11
12
@Target({TYPE, METHOD})
public @interface SOAPBinding {
    enum Style { DOCUMENT, RPC }

    enum Use { LITERAL, ENCODED }

    enum ParameterStyle { BARE, WRAPPED }

    Style style() default Style.DOCUMENT;
    Use use() default Use.LITERAL;
    ParameterStyle parameterStyle() default ParameterStyle.WRAPPED;
}

8.11.7. jakarta.jws.HandlerChain

1
2
3
4
5
@Target({TYPE})
public @interface HandlerChain {
    String file();
    String name() default "";
}

8.12. jakarta.xml.ws.Action

The Action annotation is applied to the methods of a SEI. It is used to specify the input, output, fault WS-Addressing Action values associated with the annotated method.

For such a method, the mapped operation in the generated WSDL’s wsam:Action attribute on the WSDL input, output and fault messages of the WSDL operation is based upon which attributes of the Action annotation have been specified. The wsam:Action computation algorithm is specified in Section 3.5.2, “wsam:Action Computation Algorithm”

Table 14. Action properties.
Property Description Default

fault

Array of FaultAction for the wsdl:fault s of the operation

””

input

Action for the wsdl:input of the operation

””

output

Action for the wsdl:output of the operation

””

8.13. jakarta.xml.ws.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, “Service Specific Exception”.

The wsam:Action attribute value in the fault message in the generated WSDL operation mapped for an exception class is equal to the corresponding value in the FaultAction. The wsam:Action computation algorithm is specified in Section 3.5.2, “wsam:Action Computation Algorithm”

Table 15. FaultAction properties.
Property Description Default

value

Action for the wsdl:fault of the operation

””

output

Name of the exception class

no defaults required property

8.14. jakarta.xml.ws.spi.WebServiceFeatureAnnotation

The WebServiceFeatureAnnotation is a meta-annotation used by a Jakarta XML Web Services implementation to identify other annotations as WebServiceFeatures. Jakarta XML Web Services provides the following annotations as WebServiceFeatures: jakarta.xml.ws.soap.Addressing, jakarta.xml.ws.soap.MTOM, and jakarta.xml.ws.RespectBinding. If a Jakarta XML Web Services implementation encounters an annotation annotated with the WebServiceFeatureAnnotation that it does not support or recognize an ERROR MUST be given.

Table 16. WebServiceFeatureAnnotation properties.
Property Description Default

id

Unique identifier for the WebServiceFeature represented by the annotated annotation.

No defaults required property

bean

The class name of a derived WebServiceFeature class associated with the annotated annotation.

No defaults required property

The following shows how the Addressing annotation uses the WebServiceFeatureAnnotation meta-annotation.

1
2
3
4
5
6
7
8
9
10
11
12
13
14
@WebServiceFeatureAnnotation(id=AddressingFeature.ID,
                             bean=AddressingFeature.class)
public @interface Addressing {
    /**
     * Specifies if this feature is enabled or disabled.
     */
    boolean enabled() default true;

    /**
     * Property to determine whether WS-Addressing
     * headers MUST be present on incoming messages.
     */
    boolean required() default false;
}

8.14.1. jakarta.xml.ws.soap.Addressing

The Addressing annotation is applied to an endpoint implementation class and to an injected web service proxy reference. It is used to control the use of WS-Addressing[26][37][27]. It corresponds with the AddressingFeature described in Section 6.5.1, “jakarta.xml.ws.soap.AddressingFeature”.

Table 17. Addressing properties.
Property Description Default

enabled

Specifies if WS-Addressing is enabled or not.

true

required

Specifies Adddressing headers MUST be present on incoming messages.

false

responses

If addressing is enabled, this property determines if endpoint requires the use of anonymous responses, or non-anonymous responses, or all.

Responses.ALL

The generated WSDL must indicate the use of addressing as specified in the Section 3.11, “Service and Ports”. The runtime requirements of enabling addressing for SOAP binding are specified in Section 11.4.1.5, “Addressing”.

8.14.2. jakarta.xml.ws.soap.MTOM

The MTOM annotation is applied to an endpoint implementation class and to an injected web service proxy reference. It is used to control the use of MTOM. It corresponds to the MTOMFeature described in Section 6.5.2, “jakarta.xml.ws.soap.MTOMFeature”.

Table 18. MTOM properties.
Property Description Default

enabled

Specifies if MTOM is enabled or not.

true

threshold

Specifies the size in bytes that binary data SHOULD be before being sent as an attachment.

0

8.14.3. jakarta.xml.ws.RespectBinding

The RespectBinding annotation is applied to an endpoint implementation class and to an injected web service proxy reference. It is used to control whether a Jakarta XML Web Services implementation MUST respect/honor the contents of the wsdl:binding associated with an endpoint. It has a corresponding RespectBindingFeature described in Section 6.5.3, “jakarta.xml.ws.RespectBindingFeature”.

RespectBinding properties.

Property Description Default

enabled

Specifies whether the wsdl:binding must be respected or not.

true

9. Customizations

This chapter describes a standard customization facility that can be used to customize the WSDL 1.1 to Java binding defined in section Chapter 2, WSDL 1.1 to Java Mapping.

9.1. Binding Language

Jakarta XML Web Services defines an XML-based language that can be used to specify customizations to the WSDL 1.1 to Java binding. In order to maintain consistency with Jakarta XML Binding, we call it a binding language. Similarly, customizations will hereafter be referred to as binding declarations.

All XML elements defined in this section belong to the https://jakarta.ee/xml/ns/jaxws namespace. For clarity, the rest of this section uses qualified element names exclusively. Wherever it appears, the jaxws prefix is assumed to be bound to the https://jakarta.ee/xml/ns/jaxws namespace name.

The binding language is extensible. Extensions are expressed using elements and/or attributes whose namespace name is different from the one used by this specification.

Conformance (Standard binding declarations): The https://jakarta.ee/xml/ns/jaxws namespace is reserved for standard Jakarta XML Web Services binding declarations. Implementations MUST support all standard Jakarta XML Web Services binding declarations. Implementation-specific binding declaration extensions MUST NOT use the https://jakarta.ee/xml/ns/jaxws namespace.

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, i.e. https://jakarta.ee/xml/ns/jaxws.

9.2. Binding Declaration Container

There are two ways to specify binding declarations. In the first approach, all binding declarations pertaining to a given WSDL document are grouped together in a standalone document, called an external binding file (see Section 9.4, “External Binding File”). The second approach consists in embeddeding binding declarations directly inside a WSDL document (see Section 9.3, “Embedded Binding Declarations”).

In either case, the jaxws:bindings element is used as a container for Jakarta XML Web Services binding declarations. It contains a (possibly empty) list of binding declarations, in any order.

19. Syntax of the binding declaration container
1
2
3
4
5
<jaxws:bindings wsdlLocation="xs:anyURI"?
                node="xs:string"?
                version="string"?>
  ...binding declarations...
</jaxws:bindings>

Semantics

@wsdlLocation

A URI pointing to a WSDL file establishing the scope of the contents of this binding declaration. 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.

@node

An XPath expression pointing to the element in the WSDL file in scope that this binding declaration is attached to. It MUST NOT be present if the jaxws:bindings appears inside a WSDL document.

@version

A version identifier. It MUST NOT appear on jaxws:bindings elements which have any jaxws:bindings ancestors (i.e. on non top-level binding declarations).

For the Jakarta XML Web Services specification, the version identifier, if present, MUST be 3.0. If the @version attribute is absent, it will implicitly be assumed to be 3.0.

9.3. Embedded Binding Declarations

An embedded binding declaration is specified by using the jaxws:bindings element as a WSDL extension. Embedded binding declarations MAY appear on any of the elements in the WSDL 1.1 namespace that accept extension elements, per the schema for the WSDL 1.1 namespace as amended by the WS-I Basic Profile 1.1[20].

A binding declaration embedded in a WSDL document can only affect the WSDL element it extends. When a jaxws:bindings element is used as a WSDL extension, it MUST NOT have a node attribute. Moreover, it MUST NOT have an element whose qualified name is jaxws:bindings amongs its children.

9.3.1. Example

Figure 20, “Sample WSDL document with embedded binding declarations” shows a WSDL document containing binding declaration extensions. For Jakarta XML Binding annotations, it assumes that the prefix jaxb is bound to the namespace name https://jakarta.ee/xml/ns/jaxb.

20. Sample WSDL document with embedded 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
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
<wsdl:definitions targetNamespace="..." xmlns:tns=..." xmlns:stns="...">
  <wsdl:types>
    <xs:schema targetNamespace="http://example.org/bar">
      <xs:annotation>
        <xs:appinfo>
          <jaxb:bindings>
            ...some Jakarta XML Binding binding declarations...
          </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.acme.foo"/>
      ...additional binding declarations...
  </jaxws:bindings>
</wsdl:definitions>

9.4. External Binding File

The jaxws:bindings element MAY appear as the root element of a XML document. Such a document is called an external binding file.

An external binding file specifies bindings for a given WSDL document. The WSDL document in question is identified via the mandatory wsdlLocation attribute on the root jaxws:bindings element in the document.

In an external binding file, jaxws:bindings elements MAY appear as non-root elements, e.g. as a child or descendant of the root jaxws:bindings element. In this case, they MUST carry a node attribute identifying the element in the WSDL document they annotate. The root jaxws:bindings element implicitly contains a node attribute whose value is //, i.e. selecting the root element in the document. 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 Section 9.3, “Embedded Binding Declarations”). When a Jakarta XML Web Services implementation processes a WSDL document for which there is an external binding file, 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. It is an error if, upon embedding the binding declarations defined in one or more external binding files, the resulting WSDL document contains conflicting binding declarations.

Conformance (Multiple binding files): Implementations MUST support specifying any number of external Jakarta XML Web Services and Jakarta XML Binding binding files for processing in conjunction with at least one WSDL document.

Please refer to Section 9.5, “Using Jakarta XML Binding Binding Declarations” for more information on processing Jakarta XML Binding binding declarations.

9.4.1. Example

Figures 21, “Sample external binding file for WSDL” and 22, “WSDL document referred to by external binding file” show an example external binding file and WSDL document respectively that express the same set of binding declarations as the WSDL document in Section 9.3.1, “Example”.

21. Sample external binding file for WSDL
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
<jaxws:bindings wsdlLocation="http://example.org/foo.wsdl">
  <jaxws:package name="com.acme.foo"/>
  <jaxws:bindings
      node="wsdl:types/xs:schema[targetNamespace=’http://example.org/bar’]">
    <jaxb:bindings>
        ...some Jakarta XML Binding 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>
  ...additional binding declarations....
</jaxws:bindings>
22. WSDL document referred to by 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
<wsdl:definitions targetNamespace="..." xmlns:tns="..." xmlns:stns="...">
  <wsdl:types>
    <xs:schema targetNamespace="http://example.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>

9.5. Using Jakarta XML Binding Binding Declarations

It is possible to use Jakarta XML Binding binding declarations in conjunction with Jakarta XML Web Services.

The Jakarta XML Binding bindings element, henceforth referred to as jaxb:bindings, MAY appear as an annotation inside a schema document embedded in a WSDL document, i.e. as a descendant of a xs:schema element whose parent is the wsdl:types element. It affects the data binding as specified by Jakarta XML Binding.

Additionally, jaxb:bindings MAY appear inside a Jakarta XML Web Services external binding file as a child of a jaxws:bindings element whose node attribute points to a xs:schema element inside a WSDL document. When the schema is processed, the outcome MUST be as if the jaxb:bindings element was inlined inside the schema document as an annotation on the schema component.

While processing a Jakarta XML Binding binding declaration (i.e. a jaxb:bindings element) for a schema document embedded inside a WSDL document, 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.

Editors Note

This last requirement ensures that Jakarta XML Binding processors don’t have to be extended to incorporate knowledge of WSDL. In particular, it becomes possible to take a Jakarta XML Binding binding file and embed it in a Jakarta XML Web Services binding file as-is, without fixing up all its XPath expressions, even in the case that the XML Schema the Jakarta XML Binding binding file refers to was embedded in a WSDL.

9.6. Scoping of Bindings

Binding declarations are scoped according to the parent-child hierarchy in the WSDL document. For instance, when determining the value of the jaxws:enableWrapperStyle customization parameter for a portType operation, binding declarations MUST be processed in the following order, according to the element they pertain to: (1) the portType operation in question, (2) its parent portType, (3) the definitions element.

Tools MUST NOT ignore binding declarations. It is an error if upon applying all the customizations in effect for a given WSDL document, any of the generated Java source code artifacts does not contain legal Java syntax. In particular, it is an error to use any reserved keywords as the name of a Java field, method, type or package.

9.7. Standard Binding Declarations

The following sections detail the predefined binding declarations, classified according to the WSDL element they’re allowed on. All these declarations reside in the https://jakarta.ee/xml/ns/jaxws namespace.

9.7.1. Definitions

The following binding declarations MAY appear in the context of a WSDL document, 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.

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
<jaxws:package name="xs:string">?
  <jaxws:javadoc>xs:string</jaxws:javadoc>?
</jaxws:package>

<jaxws:enableWrapperStyle>?
  xs:boolean
</jaxws:enableWrapperStyle>

<jaxws:enableAsyncMapping>?
  xs:boolean
</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.

package/javadoc/text()

Package-level javadoc string.

enableWrapperStyle

If present with a boolean value of true (resp. false), wrapper style is enabled (resp. disabled) by default for all operations.

enableAsyncMapping

If present with a boolean value of true (resp. false), asynchronous mappings are enabled (resp. disbled) by default for all operations.

enableMIMEContent

If present with a boolean value of true (resp. false), use of the mime:content information is enabled (resp. disabled) by default for all operations.

The enableWrapperStyle declaration only affects operations that qualify for the wrapper style per the Jakarta XML Web Services specification. By default, this declaration is true, i.e. wrapper style processing is turned on by default for all qualified operations, and must be disabled by using a jaxws:enableWrapperStyle declaration with a value of false in the appropriate scope.

9.7.2. PortType

The following binding declarations MAY appear in the context of a WSDL portType, either as an extension to the wsdl:portType element or with a node attribute pointing at one.

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.

class/javadoc/text()

Class-level javadoc string.

enableWrapperStyle

If present with a boolean value of true (resp. false), wrapper style is enabled (resp. disabled) by default for all operations in this wsdl:portType.

enableAsyncMapping

If present with a boolean value of true (resp. false), asynchronous mappings are enabled (resp. disabled) by default for all operations in this wsdl:portType.

9.7.3. PortType Operation

The following binding declarations MAY appear in the context of a WSDL portType operation, either as an extension to the wsdl:portType/wsdl:operation element or with a node attribute pointing at one.

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.

method/javadoc/text()

Method-level javadoc string.

enableWrapperStyle

If present with a boolean value of true (resp. false), wrapper style is enabled (resp. disabled) by default for this wsdl:operation.

enableAsyncMapping

If present with a boolean value of true, asynchronous mappings are enabled by default for this wsdl: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.

It is an error if two parameters that do not correspond to the same Java formal parameter are assigned the same name, or if a part/element that corresponds to the Java method return value is assigned a name.

9.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

Fully qualified 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.

9.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.

9.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
11
12
13
<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">?
    <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.

9.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

Fully qualified name of the generated service class.

class/javadoc/text()

Class-level javadoc string.

9.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.

method/javadoc/text()

Method-level javadoc string.

provider

This binding declaration specifies that the annotated port will be used with the jakarta.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 jakarta.xml.ws.Provider interface. Additionally, the port getter method on the generated service interface will be omitted.

Editors Note

Omitting a getXYZPort() method is necessary for consistency, because if it existed it would specify the non-existing SEI type as its return type.

10. Handler Framework

Jakarta XML Web Services provides a flexible plug-in framework for message processing modules, known as handlers, that may be used to extend the capabilities of a Jakarta XML Web Services runtime system. This chapter describes the handler framework in detail.

Conformance (Handler framework support): An implementation MUST support the handler framework.

10.1. Architecture

The handler framework is implemented by a Jakarta XML Web Services protocol binding in both client and server side runtimes. Proxies, and Dispatch instances, known collectively as binding providers, each use protocol bindings to bind their abstract functionality to specific protocols (see Figure 2, “Handler architecture”). Protocol bindings can extend the handler framework to provide protocol specific functionality; Chapter 11, SOAP Binding describes the Jakarta XML Web Services SOAP binding that extends the handler framework with SOAP specific functionality.

Client and server-side handlers are organized into an ordered list known as a handler chain. The handlers within a handler chain are invoked each time a message is sent or received. Inbound messages are processed by handlers prior to binding provider processing. Outbound messages are processed by handlers after any binding provider processing.

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. Message context properties may be used to facilitate communication between individual handlers and between handlers and client and service implementations. Different types of handlers are invoked with different types of message context.

handarch
Figure 2. Handler architecture

10.1.1. Types of Handler

Jakarta XML Web Services defines two types of handler:

Logical

Handlers that only operate on message context properties and message payloads. Logical handlers are protocol agnostic and are unable to affect protocol specific parts of a message. Logical handlers are handlers that implement jakarta.xml.ws.handler.LogicalHandler.

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 message. Protocol handlers are handlers that implement any interface derived from jakarta.xml.ws.handler.Handler except jakarta.xml.ws.handler.LogicalHandler.

Figure Figure 3, “Handler class hierarchy” shows the class hierarchy for handlers.

Handlers for protocols other than SOAP are expected to implement a protocol-specific interface that extends jakarta.xml.ws.handler.Handler.

handlers
Figure 3. Handler class hierarchy

10.1.2. Binding Responsibilities

The following subsections describe the responsibilities of the protocol binding when hosting a handler chain.

10.1.2.1. Handler and Message Context Management

The binding is responsible for instantiation, invocation, and destruction of handlers according to the rules specified in section Section 10.3, “Processing Model”. The binding is responsible for instantiation and management of message contexts according to the rules specified in Section 10.4, “Message Context”

Conformance (Logical handler support): All binding implementations MUST support logical handlers (see Section 10.1.1, “Types of Handler”) being deployed in their handler chains.

Conformance (Other handler support): Binding implementations MAY support other handler types (see Section 10.1.1, “Types of Handler”) being deployed in their handler chains.

Conformance (Incompatible handlers): An implementation MUST throw WebServiceException when, at the time a binding provider is created, the handler chain returned by the configured HandlerResolver contains an incompatible handler.

Conformance (Incompatible handlers): Implementations MUST throw a WebServiceException when attempting to configure an incompatible handler using the Binding.setHandlerChain method.

10.1.2.2. Message Dispatch

The binding is responsible for dispatch of both outbound and inbound messages after handler processing. Outbound messages are dispatched using whatever means the protocol binding uses for communication. Inbound messages are dispatched to the binding provider. Jakarta XML Web Services defines no standard interface between binding providers and their binding.

10.1.2.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 10.3.2, “Handler Execution”.

Outbound exceptions[8] are converted to protocol fault messages and dispatched using whatever means the protocol binding uses for communication. Specific protocol bindings describe the mechanism for their particular protocol, Section 11.2.2, “Exception Handling” describes the mechanism for the SOAP 1.1 binding. Inbound exceptions are passed to the binding provider.

10.2. Configuration

Handler chains may be configured either programmatically or using deployment metadata. The following subsections describe each form of configuration.

10.2.1. Programmatic Configuration

Jakarta XML Web Services only defines APIs for programmatic configuration of client side handler chains – server side handler chains are expected to be configured using deployment metadata.

10.2.1.1. jakarta.xml.ws.handler.HandlerResolver

A Service instance maintains a handler resolver that is used when creating proxies or Dispatch instances, known collectively as binding providers. During the creation of a binding provider, the handler resolver currently registered with a service is used to create a handler chain, which in turn is then used to configure the binding provider. A Service instance provides access to a handlerResolver property, via the Service.getHandlerResolver and Service.setHandlerResolver methods. A HandlerResolver implements a single method, getHandlerChain, which has one argument, a PortInfo object. The Jakarta XML Web Services runtime uses the PortInfo argument to pass the HandlerResolver of the service, port and binding in use. The HandlerResolver may use any of this information to decide which handlers to use in constructing the requested handler chain.

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.

Conformance (Handler chain snapshot): Changing the handler resolver configured for a Service instance MUST NOT affect the handlers on previously created proxies, or Dispatch instances.

10.2.1.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. In performing this operation, the order of handlers of any given type (logical or protocol) in the original chain is maintained. Figure 4, “Handler ordering, Ln and Pn represent logical and protocol handlers respectively.” illustrates this.

Section 10.3.2, “Handler Execution” describes how the handler order relates to the order of handler execution for inbound and outbound messages.

handord
Figure 4. Handler ordering, Ln and Pn represent logical and protocol handlers respectively.
10.2.1.3. jakarta.jws.HandlerChain annotation

The jakarta.jws.HandlerChain annotation defined by Jakarta XML Web Services Metadata [16] may be used to specify in a declarative way the handler chain to use for a service.

When used in conunction with Jakarta XML Web Services, the name element of the HandlerChain annotation, if present, MUST have the default value (the empty string).

In addition to appearing on a endpoint implementation class or a SEI, as specified by Jakarta XML Web Services Metadata, the handlerChain annotation MAY appear on a generated service class. In this case, it affects all the proxies and Dispatch instances created using any of the ports on the service.

Conformance (HandlerChain annotation): An implementation MUST support using the HandlerChain annotation on an endpoint implementation class, including a provider, on an endpoint interface and on a generated service class.

On the client, the HandlerChain annotation can be seen as a shorthand way of defining and installing a handler resolver (see Section 4.1.3, “Handler Resolver”).

Conformance (Handler resolver for a HandlerChain annotation): For a generated service class (see Section 2.7, “Service and Port”) which is annotated with a HandlerChain annotation, the default handler resolver MUST return handler chains consistent with the contents of the handler chain descriptor referenced by the HandlerChain annotation.

Figure 23, “Use of the HandlerChain annotation” shows an endpoint implementation class annotated with a HandlerChain annotation.

23. Use of the HandlerChain annotation
1
2
3
4
5
@WebService
@HandlerChain(file="sample_chain.xml")
public class MyService {
    ...
}
10.2.1.4. jakarta.xml.ws.Binding

The Binding interface is an abstraction of a Jakarta XML Web Services protocol binding (see Section 6.1, “jakarta.xml.ws.Binding” for more details). As described above, the handler chain initially configured on an instance is a snapshot of the applicable handlers configured on the Service instance at the time of creation. Binding provides methods to manipulate the initially configured handler chain for a specific instance.

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.

10.2.2. Deployment Model

Jakarta XML Web Services defines no standard deployment model for handlers. Such a model is provided by Jakarta Enterprise Web Services[17].

10.3. Processing Model

This section describes the processing model for handlers within the handler framework.

10.3.1. Handler Lifecycle

In some cases, a Jakarta XML Web Services implementation must instantiate handler classes directly, e.g. in a container environment or when using the HandlerChain annotation. When doing so, an implementation must invoke the handler lifecycle methods as prescribed in this section.

If an application does its own instantiation of handlers, e.g. using a handler resolver, then the burden of calling any handler lifecycle methods falls on the application itself. This should not be seen as inconsistent, because handlers are logically part of the application, so their contract will be known to the application developer.

The Jakarta XML Web Services 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.

The Jakarta XML Web Services 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.

The lifecycle of a handler instance begins when the Jakarta XML Web Services runtime system creates a new instance of the handler class.

The runtime MUST then carry out any injections requested by the handler, typically via the jakarta.annotation.Resource annotation. After all the injections have been carried out, including in the case where no injections were requested, the runtime MUST invoke the method carrying a jakarta.annotation.PostConstruct annotation, if present. Such a method MUST satisfy the requirements in Jakarta Annotations [35] for lifecycle methods (i.e. it has a void return type and takes zero arguments). The handler instance is then ready for use.

Conformance (Handler initialization): After injection has been completed, an implementation MUST call the lifecycle method annotated with PostConstruct, if present, prior to invoking any other method on a handler instance.

Once the handler instance is created and initialized it is placed into the Ready state. While in the Ready state the Jakarta XML Web Services runtime system may invoke other handler methods as required.

The lifecycle of a handler instance ends when the Jakarta XML Web Services runtime system stops using the handler for processing inbound or outbound messages. After taking the handler offline, a Jakarta XML Web Services implementation SHOULD invoke the lifecycle method which carries a jakarta.annotation.PreDestroy annotation, if present, so as to permit the handler to clean up its resources. Such a method MUST satisfy the requirements in Jakarta Annotations [35] for lifecycle methods

An implementation can only release handlers after the instance they are attached to, be it a proxy, a Dispatch object, an endpoint or some other component, e.g. a EJB object, is released. Consequently, in non-container environments, it is impossible to call the PreDestroy method in a reliable way, and handler instance cleanup must be left to finalizer methods and regular garbage collection.

Conformance (Handler destruction): In a managed environment, prior to releasing a handler instance, an implementation MUST call the lifecycle method annotated with PreDestroy method, if present, on any Handler instances which it instantiated.

The handler instance must release its resources and perform cleanup in the implementation of the PreDestroy lifecycle method. After invocation of the PreDestroy method(s), the handler instance will be made available for garbage collection.

10.3.2. Handler Execution

As described in Section 10.2.1.2, “Handler Ordering”, a set of handlers is managed by a binding as an ordered list called a handler chain. Unless modified by the actions of a handler (see below) normal processing involves each handler in the chain being invoked in turn. Each handler is passed a message context (see Section 10.4, “Message Context”) whose contents may be manipulated by the handler.

For outbound messages handler processing starts with the first handler in the chain and proceeds in the same order as the handler chain. 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. E.g., consider a handler chain that consists of six handlers H1…​H6 in that order: for outbound messages handler H1 would be invoked first followed by H2, H3, …, and finally handler H6; for inbound messages H6 would be invoked first followed by H5, H4, …, and finally H1.

In the following discussion the terms next handler and previous handler are used. These terms are relative to the direction of the message, Table 19, “Next and previous handlers for handler Hi.” summarizes their meaning.

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 following subsections describe each handler method and the changes to handler chain processing they may cause.

Table 19. Next and previous handlers for handler Hi.
Message Direction Term Handler

Inbound

Next

Hi-1

Previous

Hi+1

Outbound

Next

Hi+1

Previous

Hi-1

10.3.2.1. handleMessage

This method is called for normal message processing. Following completion of its work the handleMessage implementation can do one of the following:

Return true

This indicates that normal message processing should continue. The runtime invokes handleMessage on the next handler or dispatches the message (see Section 10.1.2.2, “Message Dispatch”) if there are no further handlers.

Return false

This indicates that normal message processing should cease. Subsequent actions depend on whether the message exchange pattern (MEP) in use requires a response to the message currently being processed[9] or not:

Response

The message direction is reversed, the runtime invokes handleMessage on the next[10] handler or dispatches the message (see Section 10.1.2.2, “Message Dispatch”) if there are no further handlers.

No response

Normal message processing stops, close is called on each previously invoked handler in the chain, the message is dispatched (see Section 10.1.2.2, “Message Dispatch”).

Throw ProtocolException or a subclass

This indicates that normal message processing should cease. 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, fault message processing starts. The message direction is reversed, if the message is not already a fault message then it is replaced with a fault message[11], and the runtime invokes handleFault on the nexthandler or dispatches the message (see Section 10.1.2.2, “Message Dispatch”) if there are no further handlers.

No response

Normal message processing stops, close is called on each previously invoked handler in the chain, the exception is dispatched (see Section 10.1.2.3, “Exception Handling”).

Throw any other runtime exception

This indicates that normal message processing should cease. 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, close is called on each previously invoked handler in the chain, the message direction is reversed, and the exception is dispatched (see section Section 10.1.2.3, “Exception Handling”).

No response

Normal message processing stops, close is called on each previously invoked handler in the chain, the exception is dispatched (see Section 10.1.2.3, “Exception Handling”).

10.3.2.2. handleFault

Called for fault message processing, following completion of its work the handleFault implementation can do one of the following:

Return true

This indicates that fault message processing should continue. The runtime invokes handleFault on the next handler or dispatches the fault message (see Section 10.1.2.2, “Message Dispatch”) if there are no further handlers.

Return false

This indicates that fault message processing should cease. Fault message processing stops, close is called on each previously invoked handler in the chain, the fault message is dispatched (see section Section 10.1.2.2, “Message Dispatch”).

Throw ProtocolException or a subclass

This indicates that fault message processing should cease. Fault message processing stops, close is called on each previously invoked handler in the chain, the exception is dispatched (see section Section 10.1.2.3, “Exception Handling”).

Throw any other runtime exception

This indicates that fault message processing should cease. Fault message processing stops, close is called on each previously invoked handler in the chain, the exception is dispatched (see section Section 10.1.2.3, “Exception Handling”).

10.3.2.3. close

A handler’s close method is called at the conclusion of a message exchange pattern (MEP). It is called just prior to the binding dispatching the final message, fault or exception of the MEP and may be used to clean up per-MEP resources allocated by a handler. 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, an implementation MUST call the close method of each handler that was previously invoked during that MEP via either handleMessage or handleFault.

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 Section 10.3.2, “Handler Execution”).

10.3.3. Handler Implementation Considerations

Handler instances may be pooled by a Jakarta XML Web Services runtime system. All instances of a specific handler are considered equivalent by a Jakarta XML Web Services runtime system and any instance may be chosen to handle a particular message. Different handler instances may be used to handle each message of an MEP. Different threads may be used for each handler in a handler chain, for each message in an MEP or any combination of the two. Handlers should not rely on thread local state to share information. Handlers should instead use the message context, see section Section 10.4, “Message Context”.

10.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.

Different types of handler are invoked with different types of message context. Section 10.4.1, “jakarta.xml.ws.handler.MessageContext” and Section 10.4.2, “jakarta.xml.ws.handler.LogicalMessageContext” describe MessageContext and LogicalMessageContext respectively. In addition, Jakarta XML Web Services bindings may define a message context subtype for their particular protocol binding that provides access to protocol specific features. Section 11.3, “SOAP Message Context” describes the message context subtype for the Jakarta XML Web Services SOAP binding.

10.4.1. jakarta.xml.ws.handler.MessageContext

MessageContext is the super interface for all Jakarta XML Web Services message contexts. It extends Map<String,Object> with additional methods and constants to manage a set of properties that enable handlers in a handler chain to share processing related state. For example, 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.

Properties are scoped as either APPLICATION or HANDLER. All properties are available to all handlers for an instance of an MEP on a particular endpoint. E.g., if a logical handler puts a property in the message context, that property will also be available to any protocol handlers in the chain during the execution of an MEP instance. APPLICATION scoped properties are also made available to client applications (see Section 4.2.1, “Configuration”) and service endpoint implementations. The defaultscope for a property is HANDLER.

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.

10.4.1.1. Standard Message Context Properties

Table 20, “Standard MessageContext properties.” lists the set of standard MessageContext properties.

The standard properties form a set of metadata that describes the context of a particular message. The property values may be manipulated by client applications, service endpoint implementations, the Jakarta XML Web Services runtime or handlers deployed in a protocol binding. A Jakarta XML Web Services runtime is expected to implement support for those properties shown as mandatory and may implement support for those properties shown as optional.

Table 21, “Standard HTTP MessageContext properties.” lists the standard MessageContext properties specific to the HTTP protocol. These properties are only required to be present when using an HTTP-based binding.

Table 22, “Standard Servlet Container-Specific MessageContext properties.” lists those properties that are specific to endpoints running inside a servlet container. 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.

Table 20. Standard MessageContext properties.
Name Type Mandatory Description

jakarta.xml.ws.handler.message

.outbound

Boolean

Y

Specifies the message direction: true for outbound messages, false for inbound messages.

jakarta.xml.ws.binding.attachments

.inbound

Map<String,DataHandler>

Y

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.

.outbound

Map<String,DataHandler>

Y

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.

jakarta.xml.ws.reference

.parameters

List<Element>

Y

A list of WS Addressing reference parameters. The list MUST include all SOAP headers marked with the wsa:IsReferenceParameter="true" attribute.

jakarta.xml.ws.wsdl

.description

URI

N

A resolvable URI that may be used to obtain access to the WSDL for the endpoint.

.service

QName

N

The name of the service being invoked in the WSDL.

.port

QName

N

The name of the port over which the current message was received in the WSDL.

.interface

QName

N

The name of the port type to which the current message belongs.

.operation

QName

N

The name of the WSDL operation to which the current message belongs. The namespace is the target namespace of the WSDL definitions element.

Table 21. Standard HTTP MessageContext properties.
Name Type Mandatory Description

jakarta.xml.ws.http.request

.headers

Map<String,List<String>>

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.

.method

String

Y

The HTTP method for the request message.

.querystring

String

Y

The HTTP query string for the request message, or null if the request does not have any. If the address specified using the jakarta.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 jakarta.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.

.pathinfo

String

Y

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.

jakarta.xml.ws.http.response

.headers

Map<String,List<String>>

Y

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.

.code

Integer

Y

The HTTP response status code.

Table 22. Standard Servlet Container-Specific MessageContext properties.
Name Type Mandatory Description

jakarta.xml.ws.servlet

.context

`jakarta.servlet.ServletContex`t

Y

The ServletContext object belonging to the web application that contains the endpoint.

.request

jakarta.servlet.http.HttpServletRequest

Y

The HttpServletRequest object associated with the request currently being served.

.response

jakarta.servlet.http.HttpServletResponse

Y

The HttpServletResponse object associated with the request currently being served.

10.4.2. jakarta.xml.ws.handler.LogicalMessageContext

Logical handlers (see Section 10.1.1, “Types of Handler”) are passed a message context of type LogicalMessageContext when invoked. LogicalMessageContext extends MessageContext with methods to obtain and modify the message payload, it does not provide access to the protocol specific aspects of a message. A protocol binding defines what component of a message are available via a logical message context. E.g., the SOAP binding, see Section 11.1.1.2, “SOAP Handlers”, 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 12, HTTP Binding defines that a logical handler can access the entire XML payload of a message.

The getSource() method of LogicalMessageContext MUST return null whenever the message doesn’t contain an actual payload. A case in which this might happen is when, on the server, the endpoint implementation 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 12, HTTP Binding).

10.4.3. Relationship to Application Contexts

Client side binding providers have methods to access contexts for outbound and inbound messages. As described in section Section 4.2.1, “Configuration” 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 APIs, 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 application-scoped 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.

11. SOAP Binding

This chapter describes the Jakarta XML Web Services SOAP binding and its extensions to the handler framework (described in Chapter 10, Handler Framework) for SOAP message processing.

11.1. Configuration

A SOAP binding instance requires SOAP specific configuration in addition to that described in Section 10.2, “Configuration”. The additional information can be configured either programmatically or using deployment metadata. The following subsections describe each form of configuration.

11.1.1. Programmatic Configuration

Jakarta XML Web Services defines APIs for programmatic configuration of client-side SOAP bindings. Server side bindings can be configured programmatically when using the Endpoint API (see Section 5.2, “jakarta.xml.ws.Endpoint”), but are otherwise expected to be configured using annotations or deployment metadata.

11.1.1.1. SOAP Roles

SOAP 1.1[2] and SOAP 1.2[3][4] use different terminology for the same concept: a SOAP 1.1 actor is equivalent to a SOAP 1.2 role. This specification uses the SOAP 1.2 terminology.

An ultimate SOAP receiver always plays the following roles:

Next

In SOAP 1.1, the next role is identified by the URI http://schemas.xmlsoap.org/soap/actor/next. In SOAP 1.2, the next role is identified by the URI http://www.w3.org/2003/05/soap-envelope/role/next.

Ultimate receiver

In SOAP 1.1 the ultimate receiver role is identified by omission of the actor attribute from a SOAP header. In SOAP 1.2 the ultimate receiver role is identified by the URI http://www.w3.org/2003/05/soap-envelope/role/ultimateReceiver or by omission of the role attribute from a SOAP header.

Conformance (SOAP required roles): An implementation of the SOAP binding MUST act in the following roles: next and ultimate receiver.

A SOAP 1.2 endpoint never plays the following role:

None

In SOAP 1.2, the none role is identified by the URI http://www.w3.org/2003/05/soap-envelope/role/none.

Conformance (SOAP required roles): An implementation of the SOAP binding MUST NOT act in the none role.

The jakarta.xml.ws.SOAPBinding interface is an abstraction of the Jakarta XML Web Services SOAP binding. It extends jakarta.xml.ws.Binding with methods to configure additional SOAP roles played by the endpoint.

Conformance (Default role visibility): An implementation MUST include the required next and ultimate receiver roles in the Set returned from SOAPBinding.getRoles.

Conformance (Default role persistence): An implementation MUST add the required next and ultimate receiver roles to the roles configured with SOAPBinding.setRoles.

Conformance (None role error): An implementation MUST throw WebServiceException if a client attempts to configure the binding to play the none role via SOAPBinding.setRoles.

11.1.1.2. SOAP Handlers

The handler chain for a SOAP binding is configured as described in Section 10.2.1, “Programmatic Configuration”. The handler chain may contain handlers of the following types:

Logical

Logical handlers are handlers that implement jakarta.xml.ws.handler.LogicalHandler either directly or indirectly. Logical handlers have access to the content of the SOAP body via the logical message context.

SOAP

SOAP handlers are handlers that implement jakarta.xml.ws.handler.soap.SOAPHandler.

Mime attachments specified by the jakarta.xml.ws.binding.attachments.inbound and jakarta.xml.ws.binding.attachments.outbound properties defined in the Table 20, “Standard MessageContext properties.” can be modified in logical handlers. A SOAP message with the attachments specified using the properties is generated before invoking the first SOAPHandler. Any changes to the two properites in consideration above in the MessageContext after invoking the first SOAPHandler are ignored. The SOAPHandler however may change the properties in the MessageContext

Use of jakarta.xml.ws.binding.attachments.outbound property in Dispatch

  • When using Dispatch in SOAP / HTTP binding in payload mode, attachments specified using the jakarta.xml.ws.binding.attachments.outbound property will be included as mime attachments in the message.

  • When using Dispatch in SOAP / HTTP binding in message mode, the jakarta.xml.ws.binding.attachments.outbound property will be ignored as the message type already provides a way to specify attachments.

Conformance (Incompatible handlers): An implementation MUST throw WebServiceException when, at the time a binding provider is created, the handler chain returned by the configured HandlerResolver contains an incompatible handler.

Conformance (Incompatible handlers): Implementations MUST throw a WebServiceException when attempting to configure an incompatible handler using Binding.setHandlerChain.

Conformance (Logical handler access): An implementation MUST allow access to the contents of the SOAP body via a logical message context.

11.1.1.3. SOAP Headers

The SOAP headers understood by a handler are obtained using the getHeaders method of SOAPHandler.

11.1.2. Deployment Model

Jakarta XML Web Services defines no standard deployment model for handlers. Such a model is provided by Jakarta Enterprise Web Services[17].

11.2. Processing Model

The SOAP binding implements the general handler framework processing model described in Section 10.3, “Processing Model” but extends it to include SOAP specific processing as described in the following subsections.

11.2.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 10.3.2, “Handler Execution”). Refer to the SOAP specification[2][3][4] for a normative description of the SOAP processing model. This section is not intended to supercede any requirement stated within the SOAP specification, but rather to outline how the configuration information described above is combined to satisfy the SOAP requirements:

  1. Obtain the set of SOAP roles for the current binding instance. This is returned by SOAPBinding.getRoles.

  2. Obtain the set of Handlers deployed on the current binding instance. This is obtained via Binding.getHandlerChain.

  3. Identify the set of header qualified names (QNames) that the binding instance understands. This is the set of all header QNames that satisfy at least one of the following conditions:

    1. that are mapped to method parameters in the service endpoint interface;

    2. are members of SOAPHandler.getHeaders() for each SOAPHandler in the set obtained in Step 2;

    3. are directly supported by the binding instance.

  4. Identify the set of must understand headers in the inbound message that are targeted at this node. 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.

  5. For each header in the set obtained in Step 4, the header is understood if its QName is in the set identified in Step 3.

  6. If every header in the set obtained in Step 4 is understood, then the node understands how to process the message. Otherwise the node does not understand how to process the message.

  7. If the node does not understand how to process the message, then neither handlers nor the endpoint are invoked and instead the binding generates a SOAP must understand exception. Subsequent actions depend on whether the message exchange pattern (MEP) in use requires a response to the message currently being processed or not:

    Response

    The message direction is reversed and the binding dispatches the SOAP must understand exception (see Section 11.2.2, “Exception Handling”).

    No response

    The binding dispatches the SOAP must understand exception (see Section 11.2.2, “Exception Handling”).

11.2.2. Exception Handling

The following subsections describe SOAP specific requirements for handling exceptions thrown by handlers and service endpoint implementations.

11.2.2.1. Handler Exceptions

A binding is responsible for catching runtime exceptions thrown by handlers and following the processing model described in Section 10.3.2, “Handler Execution”. 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. The MEP in use includes a response to the message being processed

  3. The current message is not already a fault message (the handler might have undertaken the work prior to throwing the exception).

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 Jakarta SOAP with Attachments' SOAPFault are serialized to a new SOAP fault message, see Section 11.2.2.3, “Mapping Exceptions to SOAP Faults”. The current message is replaced by the new SOAP fault message.

  • 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.1[2] or a receiver class of error for SOAP 1.2[3].

  • Handler processing is resumed as described in Section 10.3.2, “Handler Execution”.

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.1[2] or a receiver class of error for SOAP 1.2[3] and the message is dispatched.

Inbound

The exception is passed to the binding provider.

11.2.2.2. Service Endpoint Exceptions

Service endpoints can throw service specific exceptions or runtime exceptions. In both cases they can provide protocol specific information using the cause mechanism, see Section 6.4.1, “Protocol Specific Exception Handling”.

A server side implementation of the SOAP binding is responsible for catching exceptions thrown by a service endpoint implementation and, if the message exchange pattern in use includes a response to the message that caused the exception, converting such exceptions to SOAP fault messages and invoking the handleFault method on handlers for the fault message as described in Section 10.3.2, “Handler Execution”.

Section 11.2.2.3, “Mapping Exceptions to SOAP Faults” describes the rules for mapping an exception to a SOAP fault.

11.2.2.3. Mapping Exceptions to SOAP Faults

When mapping an exception to a SOAP fault, the fields of the fault message are populated according to the following rules of precedence:

  • faultcode (Subcode in SOAP 1.2, Code set to env:Receiver)

    1. SOAPFaultException.getFault().getFaultCodeAsQName()[12]

    2. env:Server (Subcode omitted for SOAP 1.2).

  • faultstring (Reason/Text)

    1. SOAPFaultException.getFault().getFaultString()[12]

    2. Exception.getMessage()

    3. Exception.toString()

  • faultactor (Role in SOAP 1.2)

    1. SOAPFaultException.getFault().getFaultActor()[12]

    2. Empty

  • detail (Detail in SOAP 1.2)

    1. Serialized service specific exception (see WrapperException.getFaultInfo() in Section 2.5, “Fault”)

    2. SOAPFaultException.getFault().getDetail()[12]

11.3. SOAP Message Context

SOAP handlers are passed a SOAPMessageContext when invoked. SOAPMessageContext extends MessageContext with methods to obtain and modify the SOAP message payload.

11.4. SOAP Transport and Transfer Bindings

SOAP[2][4] can be bound to multiple transport or transfer protocols. This section describes requirements pertaining to the supported protocols for use with SOAP.

11.4.1. HTTP

The SOAP 1.1 HTTP binding is identified by the URL http://schemas.xmlsoap.org/wsdl/soap/http, which is also the value of the constant jakarta.xml.ws.soap.SOAPBinding.SOAP11HTTP_BINDING.

Conformance (SOAP 1.1 HTTP Binding Support): An implementation MUST support the HTTP binding of SOAP 1.1[2] and SOAP With Attachments[38] as clarified by the WS-I Basic Profile[20], WS-I Simple SOAP Binding Profile[32] and WS-I Attachment Profile[33].

The SOAP 1.2 HTTP binding is identified by the URL http://www.w3.org/2003/05/soap/bindings/HTTP/, which is also the value of the constant jakarta.xml.ws.soap.SOAPBinding.SOAP12HTTP_BINDING.

Conformance (SOAP 1.2 HTTP Binding Support): An implementation MUST support the HTTP binding of SOAP 1.2[4].

11.4.1.1. MTOM

Conformance (SOAP MTOM Support): An implementation MUST support MTOM[30] [13].

SOAPBinding defines a property (in the JavaBeans sense) called MTOMEnabled that can be used to control the use of MTOM. The getMTOMEnabled method is used to query the current value of the property. The setMTOMEnabled method is used to change the value of the property so as to enable or disable the use of MTOM.

Conformance (Semantics of MTOM enabled): When MTOM is enabled, a receiver MUST accept both non-optimized and optimized messages, and a sender MAY send an optimized message, non-optimized messages being also acceptable.

The heuristics used by a sender to determine whether to use optimization or not are implementation-specific.

Conformance (MTOM support): Predefined SOAPBinding instances MUST support enabling/disabling MTOM support using the setMTOMenabled method.

Conformance (SOAP bindings with MTOM disabled): The bindings corresponding to the following IDs:

  • jakarta.xml.ws.soap.SOAPBinding.SOAP11HTTP_BINDING

  • jakarta.xml.ws.soap.SOAPBinding.SOAP12HTTP_BINDING

MUST have MTOM disabled by default.

For convenience, this specification defines two additional binding identifiers for SOAP 1.1 and SOAP 1.2 over HTTP with MTOM enabled.

The URL of the former is http://schemas.xmlsoap.org/wsdl/soap/http?mtom=true and its predefined constant jakarta.xml.ws.soap.SOAPBinding.SOAP11HTTP_MTOM_BINDING.

The URL of the latter is http://www.w3.org/2003/05/soap/bindings/HTTP/?mtom=true and its predefined constant jakarta.xml.ws.soap.SOAPBinding.SOAP12HTTP_MTOM_BINDING.

Conformance (SOAP bindings with MTOM enabled): The bindings corresponding to the following IDs:

  • jakarta.xml.ws.soap.SOAPBinding.SOAP11HTTP_MTOM_BINDING

  • jakarta.xml.ws.soap.SOAPBinding.SOAP12HTTP_MTOM_BINDING

MUST have MTOM enabled by default.

Conformance (MTOM on Other SOAP Bindings): Other bindings that extend SOAPBinding MAY NOT support changing the value of the MTOMEnabled property. In this case, if an application attempts to change its value, an implementation MUST throw a WebServiceException.

11.4.1.2. One-way Operations

HTTP interactions are request-response in nature. When using HTTP as the transfer protocol for a one-way SOAP message, implementations wait for the HTTP response even though there is no SOAP message in the HTTP response entity body.

Conformance (One-way operations): When invoking one-way operations, an implementation of the SOAP/HTTP binding MUST block until the HTTP response is received or an error occurs.

Note that completion of the HTTP request simply means that the transmission of the request is complete, not that the request was accepted or processed.

11.4.1.3. Security

Section 4.2.1.1, “Standard Properties” defines two standard context properties (jakarta.xml.ws.security.auth.username and jakarta.xml.ws.security.auth.password) that may be used to configure authentication information.

Conformance (HTTP basic authentication support): An implementation of the SOAP/HTTP binding MUST support HTTP basic authentication.

Conformance (Authentication properties): A client side implementation MUST support use of the the standard properties jakarta.xml.ws.security.auth.username and jakarta.xml.ws.security.auth.password to configure HTTP basic authentication.

11.4.1.4. Session Management

Section 4.2.1.1, “Standard Properties” defines a standard context property (jakarta.xml.ws.session.maintain) that may be used to control whether a client side runtime will join a session initiated by a service.

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. The client stores the cookie and returns it in subsequest messages to the service.

URL rewriting

To initiate a session a service directs a client to a new URL for subsequent interactions. The new URL contains an encoded session identifier.

SSL

The SSL session ID is used to track a session.

R1120 in WS-I Basic Profile 1.1[20] allows a service to use HTTP cookies. However, R1121 recommends that a service should not rely on use of cookies for state management.

Conformance (URL rewriting support): An implementation MUST support use of HTTP URL rewriting for state management.

Conformance (Cookie support): An implementation SHOULD support use of HTTP cookies for state management.

Conformance (SSL session support): An implementation MAY support use of SSL session based state management.

11.4.1.5. Addressing

If addressing is enabled, implementations are required to follow WS-Addressing[26][37][27] protocols.

Conformance (SOAP Addressing Support): An implementation MUST support WS-Addressing 1.0 - SOAP Binding[37].

Conformance (wsa:Action value): wsa:Action value MUST be got from @Action annotation elements in SEI, if present. But if a client sets a BindingProvider.SOAPACTION_URI_PROPERTY property then that MUST be used for wsa:Action header.

If a receiver receives messages with the WS-Addressing headers that are non-conformant as per WS-Addressing 1.0- SOAP Binding[37], then appropriate addressing pre-defined faults must be generated.

A Jakarta XML Web Services application may send wsa:replyTo or wsa:FaultTo addressing header to receive non-anonymous responses at a different address other than the transport back channel. When the application receives a response at a different address, there is no standard way to communicate the response with the Jakarta XML Web Services client runtime. Hence, there are no requirements on a Jakarta XML Web Services client runtime to bind non-anonymous responses. A Jakarta XML Web Services client runtime may start an endpoint to receive a non-anonymous response and may use the response to bind to the java parameters and return type. However, it is not required to do so.

12. HTTP Binding

This chapter describes the Jakarta XML Web Services XML/HTTP binding. The Jakarta XML Web Services XML/HTTP binding provides raw XML over HTTP messaging capabilities as used in many Web services today.

12.1. Configuration

The XML/HTTP binding is identified by the URL http://www.w3.org/2004/08/wsdl/http, which is also the value of the constant jakarta.xml.ws.http.HTTPBinding.HTTP_BINDING.

Conformance (XML/HTTP Binding Support): An implementation MUST support the XML/HTTP binding.

An XML/HTTP binding instance allows HTTP-specific configuration in addition to that described in Section 10.2, “Configuration”. The additional information can be configured either programmatically or using deployment metadata. The following subsections describe each form of configuration.

12.1.1. Programmatic Configuration

Jakarta XML Web Services only defines APIs for programmatic configuration of client side XML/HTTP bindings – server side bindings are expected to be configured using deployment metadata.

12.1.1.1. HTTP Handlers

The handler chain for an XML/HTTP binding is configured as described in Section 10.2.1, “Programmatic Configuration”. The handler chain may contain handlers of the following types:

Logical

Logical handlers are handlers that implement jakarta.xml.ws.handler.LogicalHandler either directly or indirectly. Logical handlers have access to the entire XML message via the logical message context.

Use of jakarta.xml.ws.binding.attachments.outbound property in Dispatch

  • When using Dispatch in XML / HTTP binding in payload mode, attachments specified using the jakarta.xml.ws.binding.attachments.outbound property will be included as mime attachments to the message.

  • When using Dispatch in XML / HTTP binding in message mode, the jakarta.xml.ws.binding.attachments.outbound property will be ignored. Dispatch of type DataSource should be used to send mime attachments for the XML / HTTP binding in message mode.

Conformance (Incompatible handlers): An implementation MUST throw WebServiceException when, at the time a binding provider is created, the handler chain returned by the configured HandlerResolver contains an incompatible handler.

Conformance (Incompatible handlers): Implementations MUST throw a WebServiceException when attempting to configure an incompatible handler using Binding.setHandlerChain.

Conformance (Logical handler access): An implementation MUST allow access to the entire XML message via a logical message context.

12.1.2. Deployment Model

Jakarta XML Web Services defines no standard deployment model for handlers. Such a model is provided by Jakarta Enterprise Web Services[17].

12.2. Processing Model

The XML/HTTP binding implements the general handler framework processing model described in Section 10.3, “Processing Model”.

12.2.1. Exception Handling

The following subsections describe HTTP specific requirements for handling exceptions thrown by handlers and service endpoint implementations.

12.2.1.1. Handler Exceptions

A binding is responsible for catching runtime exceptions thrown by handlers and following the processing model described in section Section 10.3.2, “Handler Execution”. 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. The MEP in use includes a response to the message being processed

  3. The current message is not already a fault message (the handler might have undertaken the work prior to throwing the exception).

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. Any current XML message content is removed.

  • 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.

  • Handler processing is resumed as described in section Section 10.3.2, “Handler Execution”.

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, any current XML message content is removed and the message is dispatched.

Inbound

The exception is passed to the binding provider.

12.2.1.2. Service Endpoint Exceptions

Service endpoints can throw service specific exceptions or runtime exceptions. In both cases they can provide protocol specific information using the cause mechanism, see Section 6.4.1, “Protocol Specific Exception Handling”.

A server side implementation of the XML/HTTP binding is responsible for catching exceptions thrown by a service endpoint implementation and, if the message exchange pattern in use includes a response to the message that caused the exception, converting such exceptions to HTTP response messages and invoking the handleFault method on handlers for the response message as described in Section 10.3.2, “Handler Execution”.

Section 12.2.1.3, “Mapping Exceptions to a HTTP Status Code” describes the rules for mapping an exception to a HTTP status code.

12.2.1.3. Mapping Exceptions to a HTTP Status Code

When mapping an exception to a HTTP status code, the status code of the HTTP fault message is populated according to the following rules of precedence:

  1. HTTPException.getStatusCode()[14]

  2. 500.

12.3. HTTP Support

12.3.1. One-way Operations

HTTP interactions are request-response in nature. When used for one-way messages, implementations wait for the HTTP response even though there is no XML message in the HTTP response entity body.

Conformance (One-way operations): When invoking one-way operations, an implementation of the XML/HTTP binding MUST block until the HTTP response is received or an error occurs.

Note that completion of the HTTP request simply means that the transmission of the request is complete, not that the request was accepted or processed.

12.3.2. Security

Section 4.2.1.1, “Standard Properties” defines two standard context properties (jakarta.xml.ws.security.auth.username and jakarta.xml.ws.security.auth.password) that may be used to configure authentication information.

Conformance (HTTP basic authentication support): An implementation of the XML/HTTP binding MUST support HTTP basic authentication.

Conformance (Authentication properties): A client side implementation MUST support use of the the standard properties jakarta.xml.ws.security.auth.username and jakarta.xml.ws.security.auth.password to configure HTTP basic authentication.

12.3.3. Session Management

Section 4.2.1.1, “Standard Properties” defines a standard context property (jakarta.xml.ws.session.maintain) that may be used to control whether a client side runtime will join a session initiated by a service.

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. The client stores the cokkie and returns it in subsequest messages to the service.

URL rewriting

To initiate a session a service directs a client to a new URL for subsequent interactions. The new URL contains an encoded session identifier.

SSL

The SSL session ID is used to track a session.

Conformance (URL rewriting support) An implementation MUST support use of HTTP URL rewriting for state management.

Conformance (Cookie support): An implementation SHOULD support use of HTTP cookies for state management.

Conformance (SSL session support): An implementation MAY support use of SSL session based state management.

Appendix A: Change Log

A.1. 4.0 Changes

  • Merged Jakarta Web Services Metadata specification into Jakarta Web Services specification.

  • Annotated jakarta.xml.ws.AsyncHandler with @FunctionalInterface.

  • Extended the API of jakarta.xml.ws.wsaddressing.W3CEndpointReference with getters.

  • Updated the definition of the discovery process of javax.xml.ws.spi.Provider implementation (Section 6.2.1, “Configuration”)

A.2. 3.0 Changes

  • Changed specification version and license.

  • Package namespace changed to jakarta.xml.ws.*.

  • Alignment with Jakarta XML Binding 3.0

  • Drop requirements related to JAX-WS inclusion in Java SE

  • Updated namespace of customization schema to https://jakarta.ee/xml/ns/jaxws and bumped schema version to 3.0

A.3. 2.3 Changes

  • Changed the definition of the discovery process of javax.xml.ws.spi.Provider implementation (Section 6.2.1, “Configuration”)

  • Added @Repeateble to @WebServiceClientRef

  • Added missing javadoc

  • Added @since to javadoc

  • Updated references from J2SE to Java SE

A.4. 2.2 Changes

A.5. 2.1 Changes

  • Added JAXB 2.1 requirement (sections 1.1, 2.4, 3.6.2).

  • Added wsa namespace definition (section 1.5).

  • Added conformance requirement for @XmlSeeAlso annotation (section 2.2).

  • Added conformance requirement for use of JAXB annotations (section 2.3.1).

  • Added clarification that not both input and output messages must be present for wrapper style (section 2.3.1.2).

  • Added section 2.4.1 W3CEndpointReference.

  • Added getPortName(WebServiceFeature…​) method to generated Service (section 2.7).

  • Added text describing the need to use customizations to resolve some conflicts (section 3.4).

  • Added conformance requirement to honor JAXB annotations (section 3.6).

  • Added conformance requirement for Exceptions that are NOT service specific exceptions (section 3.7).

  • Added conformance requirement for BindingProvider.getEndpointReference (section 4.2).

  • Added new getPort methods on Service that take WebServiceFeatures and EndpointReference (section 4.2.3).

  • Added text stating that Dispatch and Provider based applications MUST honor WebServiceFeatures (section 4.3 and 5.1).

  • Added sections Section 4.5, “jakarta.xml.ws.EndpointReference”, Section 5.2.8, “jakarta.xml.ws.EndpointReference” and Section 6.5.1.1, “jakarta.xml.ws.EndpointReference” javax.xml.ws.EndpointReference.

  • Added section 5.4 on javax.xml.ws.wsaddressing.W3CEndpointReferenceBuilder.

  • Modified description of createEndpoint method to state to cover case when no binding is specified (Section 6.2.2, “Creating Endpoint Objects”).

  • Added Section 6.2.4, “EndpointReferences” EndpointReferences.

  • Added Section 6.2.5, “Getting Port Objects” Getting Port Objects.

  • Added Section 6.5, “jakarta.xml.ws.WebServiceFeature” javax.xml.ws.WebServiceFeature.

  • Added conformance rquirement for unsupported WebServiceFeatureAnnotations (section 7).

  • Added Action, FaultAction and WebServiceFeatureAnnotation annotations (sections 7.12, 7.13 and 7.14).

  • Added javax.xml.ws.reference.parameters standard message context property (table 9.2).

  • Added Section 11.4.1.5, “Addressing” Addressing.

A.6. Changes since Proposed Final Draft

  • Added clarification for usage of javax.xml.ws.binding.attachments.outbound in Dispatch

  • Added clarification for usage of null in Dispatch (section 4.3).

  • Removed requirement that the ``name'' element of the WebFault annotation be always present, since this conflicts with 3.7 (section 7.2).

  • Clarified usage of generics in document wrapped case.

  • Added inner class mapping requirements.

  • Rephrased rules on using WebServiceContext so that the limitations that apply in the Java SE environment are marked as such (section 5.3).

  • Added conformance requirements for RequestWrapper and ResponseWrapper annotations (section 2.3.1.2).

  • Clarified order of invocation of Handler.close methods (section 9.3.2.3).

  • Clarified requirement on additional context properties and reserved the java.* and javax.* namespaces for Java specifications (section 4.2.1.2).

  • Added new binding identifiers for SOAP/HTTP bindings with MTOM enabled (section 10.4.1.1).

  • Added requirement detailing the semantics of ``MTOM enabled'' (section 10.4.1.1).

  • Renamed section 5.2.5 and added new requirements around generation of the contract for an endpoint (section 5.2.5).

  • Fixed example in figure 3.4 and added requirement on XmlType annotation on a generated fault bean (section 3.7).

  • Removed references to WSDL 2.0 and updated goals to reflect WSDL 2.0 support will be added a future revision of the specification.

  • Clarified the nillability status of various elements in the Java to WSDL binding (sections 3.6.2.1, 3.6.2.2); this included adding a new conformance requirement (section 3.6.2.3).

  • Added a requirement that a class annotated with WebServiceProvider must not be annotated with WebService (section 7.7).

  • Added a conformance requirement for support of the XML/HTTP binding, in analogy with the existing requirements for SOAP (section 11.1).

  • Added explicit mention of the predefined binding identifiers (sections 10.4.1 and 11.1).

  • Added requirements around binding identifiers for implementation-specific bindings (section 6.1).

  • Adding a requirement on dealing with exceptions thrown during handler processing (section 4.2.4).

  • Removed the javax.xml.ws.servlet.session message context property (section 9.4.1.1).

  • Fixed erroneous reference to a generated service interface'' in section 7.9 (the correct terminology is generated service class'').

  • Added javax.xml.ws.WebServiceRefs annotation (section 7.10).

  • Added clarifications for XML / HTTP binding.

  • Corrected signature for Endpoint.create to use String for bindingId.

A.7. Changes since Public Draft

  • Changed endpoint publishing so that endpoints cannot be stopped and published again multiple times (section 5.2.2).

  • Clarified that request and response beans do not contain properties corresponding to header parameters (section 3.6.2.1).

  • Clarified that criteria for bare style take only parts bound to the body into account (section 3.6.2.2).

  • Add a create(Object implementor) to Endpoint to create an Endpoint.

  • Clarified the use of INOUT param with two different MIME bindings in the input and output messages.

  • Use of WebParam and WebResult partName.

  • Replaced the init/destroy methods of handlers with the PostConstruct and PreDestroy annotations from JSR-250 (section 9.3.1).

  • Replaced the BeginService/EndService annotations with PostConstruct and PreDestroy from JSR-250 in endpoint implementors (section 5.2.1).

  • Added WebParam.header WebResult.header usage (section 3.6) and updated WSDL SOAP HTTP Binding section (3.9.2).

  • Removed requirements to support additional SOAP headers mapping.

  • Added support for DataSource as a message format for Provider and clarified the requirement for the other supported types (section 5.1). Same thing for Dispatch (section 4.3).

  • Clarified that LogicalMessageContext.getSource() may return null when there is no payload associated with the message (section 9.4.2).

  • Clarified that parts bound to mime:content are treated as unlisted from the point of view of applying the wrapper style rules (section 2.6.3).

  • Removed the ParameterIndex annotation (chapters 3 and 7).

  • Clarified naming rules for generated wrapper elements and their type (section 3.6.2.1).

  • Clarified that holders should never be used for the return type of a method (section 2.3.3).

  • Added effect of the BindingType annotation on the generated WSDL service (sections 3.8 and 3.10).

  • Added condition that the wrapper elements be non-nillable to wrapper style (section 2.3.1.2).

  • Clarified use of targetNamespace from WebService in an implementation class and an SEI based on 181 changes.

  • Updated the usage of WebMethod exclude element from Java to WSDL mapping.

  • Changed the algorithm for the default target namespace from java to WSDL (section 3.2).

  • Added requirement that a provider’s constructor be public (section 5.1).

  • Fixed some inconsistencies caused by the removal of RemoteException (e.g. in section 4.2.4).

  • Added service delegate requirements to chapter 4.

  • Added zero-argument public constructor requirement to the implementation-specific Provider SPI class (section 6.2).

  • 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.3.1 and 3.6.2) .

  • Added portName element to @WebServiceProvider annotation.

  • Added requirement on correctness of annotation to the beginning of chapter 7.

  • Added requirement for conformance to the JAX-WS profile in JSR-181 (section 7.11).

  • Clarified invocation of Handler.destroy (section 9.3.1).

  • Added use of HandlerChain annotation (section 9.2.1.3).

  • Updated 181 annotations (section 7.11).

  • Added catalog facility (section 4.2.5) and clarified that it is required to be used when processing endpoint metadata at publishing time (section 5.2.5) and annotations (chapter 7).

  • Added WebServiceRef annotation (section 7.10).

  • Added restrictions on metadata at the time an endpoint is published (section 5.2.7).

  • Replaced HandlerRegistry with HandlerResolver (sections 4.2.1, 9.2.1.1, 10.1.1.2, 11.1.1.1). Fixed handler ordering section accordingly (section 9.2.1.2).

  • Clarified that endpoint properties override the values defined using the WebServiceProvider annotation (section 5.2.8).

  • Removed mapping of headerfaults (sections 2.6.2.2 and 8.7.6).

  • Split standard message context properties into multiple tables and added servlet-specific properties (section 9.4.1.1).

  • Added WebServiceContext (section 5.3); refactored message context section in chapter 5 so that it applies to all kinds of endpoints.

  • Added WebServicePermission (section 5.2.5).

  • Added conformance requirement for one-way operations (section 6.2.2).

  • Added BindingType annotation (section 7.9).

  • Added requirement the provider endpoint implementation class carry a WebServiceProvider annotation (section 5.1).

  • Fixed RequestWrapper and ResponseWrapper description to use that they can be applied to the methods of an SEI (sections 7.4 and 7.5).

  • Fixed package name for javax.xml.ws.Provider and updated section with WebServiceProvider annotation (section 5.1).

  • Added WebServiceProvider annotation in javax.xml.ws package (section 7.8).

  • Changed Factory pattern to use javax.xml.ws.spi.Provider

  • Removed javax.xml.ws.EndpointFactory (section 5.2).

  • Removed javax.xml.ws.Servicefactory (section 4.1).

  • Removed definition of message-level security annotations (section 7.1), their use (sections 4.2.2 and 6.1.1) and the corresponding message context property (in section 9.4).

  • Removed WSDL 2.0 mapping (appendices A and B).

A.8. Changes Since Early Draft 3

  • Added requirements on mapping @WebService-annotated Java classes to WSDL.

  • Removed references to the RMI classes that JAX-RPC 1.1 used to denote remoteness, since their role is now taken by annotations: java.rmi.Remote and java.rmi.RemoteException.

  • Added Section 5.2, “jakarta.xml.ws.Endpoint” on the new Endpoint API.

  • Added the following new annotation types: @RequestWrapper, @ResponseWrapper, @WebServiceClient, @WebEndpoint.

  • Added the createService(Class serviceInterface) method to ServiceFactory.

  • Renamed the Service.createPort method to Service.addPort.

  • Added MTOMEnabled property to SOAPBinding.

  • Removed the HTTP method getter/setter from HTTPBinding and replaced them with a new message context property called javax.xml.ws.http.request.method.

  • In Section 11.2.1, “SOAP mustUnderstand Processing” clarified that SOAP headers directly supported by a binding must be treated as understood when processing mustUnderstand attributes.

  • Added getStackTrace to the list of getters defined on java.lang.Throwable with must not be mapped to fault bean properties.

  • In Section 4.2.1.1, “Standard Properties”, removed the requirement that an exception be thrown if the application attempts to set an unknown or unsupported property on a binding provider, since there are no stub-specific properties any more, only those in the request context.

  • Changed the client API chapter to reflect the annotation-based runtime. In particular, the distinction between generated stubs and dynamic proxies disappeared, and the spec now simply talks about proxies.

  • Changed JAX-RPC to JAX-WS, javax.xml.rpc.xxx to javax.xml.ws.xxx. Reflected resulting changes made to APIs.

  • Added new context properties to provide access to HTTP headers and status code.

  • Added new XML/HTTP Binding, see chapter Chapter 12, HTTP Binding.

A.9. Changes Since Early Draft 2

A.10. Changes Since Early Draft 1

Appendix B: JWS Metadata

B.1. JWS Metadata Relationship to Other Standards

Jakarta Web Services Metadata relies on Java standards, Web Services standards, XML standards and Internet standards.

Java Language standards: J2SE 5.0 is needed for the JSR-175 defined Metadata Facility.

Java runtime and container standards: Jakarta Web Services Metadata does not define a container or runtime environment – implementers provide tools to map the Java classes to specific runtime environments. The functionality of the Jakarta containers is assumed. The features provided by Jakarta XML Web Services 2.3 are needed for the Web Services runtime as well as the mapping conventions; Java to XML/WSDL and WSDL/XML to Java. An optional mapping to Jakarta Enterprise Web Services deployment descriptors is provided in Jakarta Web Services Metadata.

Web Services standards: SOAP 1.1 and WSDL 1.1 are used to describe the Web Service and define the XML messages.

XML standards: The XML language and the XML Schema 1.0 are an integral part of Jakarta Web Services Metadata.

Internet standards: HTTP and HTTP/S provide basic protocols for Web Services.

B.2. Handler Chain Configuration File Schema

The XML Schema for the handler chain configuration file is described at https://jakarta.ee/xml/ns/jakartaee/jakartaee_web_services_metadata_handler_3_0.xsd

B.3. Non-Normative Examples of Alternate Binding Annotations

This section defines non-normative examples of annotations for bindings to non-standard protocols and transports.

B.3.1. Annotation Name: HttpGetBinding

B.3.1.1. Description

Non-normative example of an alternate binding – in this case a raw HTTP binding as specified in WSDL 1.1 [7] section 4.

Member-Value Meaning Default

location

The location of the HTTP GET endpoint. When defined at the class level, defines as the base URI for all operations on the service. When defined at the method level, defines the URI for a particular operation relative to the base URI for the service.

Implementation-defined

B.3.1.2. Annotation Type Definition
@Target({TYPE, METHOD})
public @interface HttpGetBinding {
   String location() default "";
}
B.3.1.3. Example
@WebService
@HttpGetBinding(location="MyWebServices")
public class MyWebServiceImpl {
   @WebMethod
   @HttpGetBinding(location="ExampleOperation")
   public void myOperation() {
   }
};

B.4. JWS Specification Change Log

Version 3.0

  • Changed specification version and license.

  • Changed package name to jakarta.jws.

  • Updated Handler Chain Configuration File Schema in Appendix B to accommodate changed namespace.

Version 2.1

  • Changed specification version and license information.

  • Updated Handler Chain Configuration File Schema in Appendix B to fix errors, add missing elements, and make it valid.

  • Updated Section 3.1 to clarify the explanation of when an SEI is implicitly defined by an implementation bean. The revised text refers to the appropriate section 3.3 in the Jakarta XML Web Services 2.0 specification for the actual SEI rules.

  • Updated the table in Section 4.4.1 describing the default "name" member value of the jakarta.jws.WebParam annotation to resolve the issue reported. The requirement to specify a name for "document" style, parameter style "BARE", and mode "OUT" or "INOUT" is lifted and default rules are defined. This change is consistent with section 3.6.2.2 of the Jakarta XML Web Services 2.0 specification.

Version 2.0

  • Added @WebResult.header.

  • A document "bare" style operation can have a void return type and a Holder as a parameter. The Holder of course would have to be INOUT. It could also have 2 parameters one IN and one OUT.

  • Changed @SOAPBinding to be configurable on a per operation basis rather than on the entire interface.

  • Made @HandlerChain.name and @SOAPMessageHandlers deprecated.

  • Added support for Jakarta XML Web Services.

  • Updated section 3.1 Service Implementation Bean, Item 6 to state that exposing all public methods if not @WebMethod annotations are declared to include consideration of annotation inheritence.

  • Changed default of @WebResult.name to @WebMethod.operationName + "Response" for Doc/lit/bare operations.

  • Clarified @WebService.targetNamespace usage

  • Clarified @WebParam.mode usage.

  • Added @WebMethod.exclude.

  • Explicitly stated that if an implementation bean references an endpoint interface, it must implement all the methods in the service endpoint interface.

  • Changed @WebParam.name to default to arg0, arg1, etc (based on position in the method signature).

  • Added @WebParam.partName and @WebResult.partName to specify part name used in the binding.

  • Added requirement that the name for headers must be unique with an operation.

  • Clairified that a target namespace of "" maps to the empty namespace, not the web service namespace.

  • For doc/lit bare, require that any INOUT or OUT parameters must have a @WebParam.name specified to avoid name clashes with the input parameter.

  • Added @WebService.portName for the wsdl:port

  • Updated Handler schema

  • Added document/literal example to Using Jakarta Web Services Metadata annotation to affect the shape of the WSDL

  • Included various editorial changes.

Version 0.9.4

  • Allowing @HandlerChain and @SOAPMessageHandler on implementation when an endpointInterface is used.

Version 0.9.3

  • Using RFC 2119 Keyword convention.

  • Added Retention annotation to spec annotation definitions.

  • Fixed various Java and XML syntax errors.

  • Changed Implementation Bean to expose all public method by default.

  • WSDL generation is REQUIRED.

  • Clarified support for Start with WSDL, and Start with WSDL and Java development modes as OPTIONAL.

  • Clarified @HandlerChain.file attribute syntax and processing requirements.

Version 0.9.2

  • Removed security annotations as these will be defined by JSR-250 – Common Annotations.

Version 0.9.1

  • Changed default name of @WebResult to be "return" instead of "result".

  • Fixed various Java and XML syntax errors.

B.5. References

  1. JSR-175 A Metadata Facility for the Java™ Programming Language https://jcp.org/en/jsr/detail?id=175

  2. Jakarta Deployment 1.7 https://jakarta.ee/specifications/deployment/1.7/

  3. XML Schema 1.0 https://www.w3.org/TR/xmlschema-1/

  4. Jakarta EE 9 https://jakarta.ee/specifications/platform/9/

  5. Jakarta XML Web Services 3.0 https://jakarta.ee/specifications/xml-web-services/3.0/

  6. Jakarta Enterprise Web Services 2.0 https://jakarta.ee/specifications/enterprise-ws/2.0/

  7. Jakarta Annotations 2.0 https://jakarta.ee/specifications/annotations/2.0/

  8. Web Services Definition Language (WSDL) 1.1 https://www.w3.org/TR/wsdl/

  9. Simple Object Access Protocol (SOAP) 1.1 https://www.w3.org/TR/2000/NOTE-SOAP-20000508/

  10. Apache AXIS "JWS" drop-in deployment of Web Services

  11. BEA WebLogic Workshop "JWS" annotated Java Web Services

  12. RFC 2119: Keywords for use in RFCs to Indicate Requirement Levels https://www.ietf.org/rfc/rfc2119.txt

Bibliography


1. Errors that occur during the invocation are reported when the client attempts to retrieve the results of the operation, see Section 2.3.4.5, “Faults”.
2. Jakarta XML Binding maps an element declaration to a Java instance that implements JAXBElement.
3. WS-I Basic Profile R2205 requires parts to refer to elements rather than types.
4. Multiple mime:content elements for the same part indicate a set of permissible alternate types.
5. The jakarta.jws.WebParam and jakarta.jws.WebResult annotations can introduce additional parts into messages when the header element is true.
6. Use of RPC style requires use of WRAPPED parameter style. Deviations from this is an error
7. The invocation is logically non-blocking so detection of errors during operation invocation is dependent on the underlying protocol in use. For SOAP/HTTP it is possible that certain HTTP level errors may be detected.
8. Outbound exceptions are exceptions thrown by a handler that result in the message direction being set to outbound according to the rules in Section 10.3.2, “Handler Execution”.
9. For a request-response MEP, if the message direction is reversed during processing of a request message then the message becomes a response message. Subsequent handler processing takes this change into account.
10. Next in this context means the next handler taking into account the message direction reversal
11. The handler may have already converted the message to a fault message, in which case no change is made.
12. If the exception is a SOAPFaultException or has a cause that is a SOAPFaultException.
13. Jakarta XML Web Services inherits the Jakarta XML Binding support for the SOAP MTOM/XOP mechanism for optimizing transmission of binary data types, see Section 2.4, “Types”.
14. If the exception is a HTTPException or has a cause that is a HTTPException.