Jakarta XML Web Services_link管理

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.

package com.example.hello;
public class Hello {
    public static void main(String args[]) {
        System.out.println("Hello World");
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.
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.
http://www.w3.org/2001/XMLSchema
The namespace of the XML
schema[24][25] specification
http://schemas.xmlsoap.org/wsdl/
The namespace of the WSDL
schema[5]
http://schemas.xmlsoap.org/wsdl/soap/
The namespace of the WSDL
SOAP binding schema[24][25]
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
http://www.w3.org/2005/08/addressing
The namespace of the
WS-Addressing 1.0[26] schema
http://www.w3.org/2007/05/addressing/metadata
namespace of the WS-Addressing 1.0 - Metadata[27] schema
http://www.w3.org/ns/ws-policy
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.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.
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 8.3, “Embedded Binding Declarations”) or an external
binding file (see Section 8.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 8, 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 7.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 8.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.
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 8.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

  // 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 8.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
  <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:
The message part is present only in the operation’s input message.
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:
The message part is mapped to a method parameter.
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 8.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:
The input message part refers to a global element declaration whose
localname is equal to the operation name
The output message (if present) part refers to a global element
declaration
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
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 8.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:
The wrapper child is only present in the input message part’s wrapper
element.
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:
The wrapper child is mapped to a method parameter.
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 8.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

  <!-- 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.
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.
Parameters mapped from in and in/out parts appear in the same
order the corresponding parts appear in the input message.
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.
Parameters mapped from out parts appear in the same order the
corresponding parts appear in the output message.
Parameters mapped from out wrapper children (wrapper style mapping
only) appear in the same order as the corresponding wrapper children
appear in the wrapper.
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 8.7.3, “PortType Operation” to enable and disable the asynchronous
mapping.
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.
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 8.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:
The part or wrapper child is mapped to a method parameter as described
in Section 2.3.1, “Message and Part”.
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.
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

  <!-- 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>);
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();
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 8.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.
◊ 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 8.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 7.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

  <!-- 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() {...}
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 8.7.5, “Binding”).
◊ Conformance (Use of MIME type information): An implementation MUST support using the
jaxws:enableMIMEContent binding declaration defined in
Section 8.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
  <!-- 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.
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 8.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 8.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.
  <!-- 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);
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);
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.
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 7, Annotations.
◊ Conformance (Standard annotations): An implementation MUST
support the use of annotations defined in Chapter 7, 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.
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:
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 7.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:
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).
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:
It MUST carry a jakarta.jws.WebService annotation (see
Section 7.11.1, “jakarta.jws.WebService”).
Any of its methods MAY carry a jakarta.jws.WebMethod annotation (see
Section 7.11.2, “jakarta.jws.WebMethod”).
jakarta.jws.WebMethod if used, MUST NOT have the exclude element set
to true.
All method parameters and return types are compatible with the Jakarta
XML Binding[39] Java to XML Schema mapping definition
◊ Conformance (portType naming): The jakarta.jws.WebService annotation (see section
Section 7.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 7.2, “jakarta.xml.ws.WebFault”, Section 7.3, “jakarta.xml.ws.RequestWrapper” and Section 7.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.
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 7.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

  // 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>
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 7.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:
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.
A non-default @Action(output=…) value on a SEI method MUST
result into wsdl:output[@wsam:Action attribute in the corresponding
wsdl:operation.
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.
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.
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.
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.
  @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:
The value is transmitted by copy from a service client to the SEI but
is not returned from the service endpoint to the client.
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 7.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 7.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 7.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 7.3, “jakarta.xml.ws.RequestWrapper” and Section 7.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 7.3, “jakarta.xml.ws.RequestWrapper” and
Section 7.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).
Figure  10, “Wrapper mode bean representation of an operation” illustrates this conversion.
 10. Wrapper mode bean representation of an operation

  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:
The parameter is mapped to a child element of the global element
declaration for the request bean.
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.
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:
If it has a return type other than void it must have no in/out
or out non-header parameters.
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:
The parameter is mapped to a part of the input message.
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:
In the absence of customizations, the name of the bean is the same
as the name of the Exception suffixed with "Bean".
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.
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.
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).
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.
Figure  11, “Mapping of an exception to a bean for use with Jakarta XML Binding.” illustrates this mapping.
 11. Mapping of an exception to a bean for use with Jakarta XML Binding.
  @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 7.8, “jakarta.xml.ws.BindingType”), if present, otherwise the default is
the SOAP 1.1/HTTP binding (see Chapter 10, 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

  <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:
  public <T extends Shape> T setColor(T shape, Color color) {
    shape.setColor(color);
    return shape;
  @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;
  @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;
  @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;
  public List<? extends Shape> setArea(List<? extends Shape> list) {
    Iterator iterator = list.iterator();
    while(iterator.haNext()) {
        iterator.next().setArea(...);
    return list;
  @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
  <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>
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
  <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>
  <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
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.
  URL wsdlLocation = new URL("http://example.org/my.wsdl");
QName serviceName = new QName("http://example.org/sample", "MyService");
Service s = Service.create(wsdlLocation, serviceName);
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:
  // 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:
    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 9, 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.
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 9.4.1, “jakarta.xml.ws.handler.MessageContext”) prior to invoking any handlers
(see Chapter 9, 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 9, Handler Framework) are responsible for annotating outbound protocol
data units and extracting metadata from inbound protocol data units.
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
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
Username for HTTP basic
authentication.
.password
String
Password for HTTP basic
authentication.
jakarta.xml.ws.session
.maintain
Boolean
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
Boolean
Controls whether the SOAPAction
HTTP header is used in SOAP/HTTP
requests. Default value is false.
String
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.
  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");
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 11, 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 11, 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 10, 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 11, 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 10.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

  Source reqMsg = ...;
Service service = ...;
Dispatch<Source> disp = service.createDispatch(portName,
    Source.class, PAYLOAD);
Source resMsg = disp.invoke(reqMsg);
  SOAPMessage soapReqMsg = ...;
Service service = ...;
Dispatch<SOAPMessage> disp = service.createDispatch(portName,
    SOAPMessage.class, MESSAGE);
SOAPMessage soapResMsg = disp.invoke(soapReqMsg);
  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);
  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();
  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.
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 7.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

  @WebServiceProvider
@ServiceMode(value=Service.Mode.MESSAGE)
public class MyService implements Provider<SOAPMessage> {
    public MyService() {
    public SOAPMessage invoke(SOAPMessage request) {
        return request;
  @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;
  @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:
  // 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 10, 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 10, SOAP Binding) or HTTP (see Chapter 11, 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 10, 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.
  // 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 7, 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.
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.
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 7, 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
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.
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.
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 7.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:
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”.
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.
The message context made available to endpoint instances via the
WebServiceContext acts as a restricted window on to the
MessageContext of the inbound message following handler execution (see Chapter 9, 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].
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 10, SOAP Binding describes the Jakarta XML Web Services SOAP binding;
Chapter 11, 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 10, SOAP Binding and
Chapter 11, 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 9.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.
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 .
Use the configuration file jaxws.properties. The file is in
standard java.util.Properties format and typically located in the conf
directory of the Java installation. It contains the fully qualified name
of the implementation class with the key jakarta.xml.ws.spi.Provider.
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.
Finally, a platform implementation is used.
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 instance of a SEI-based endpoint class, i.e. 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 provider class, i.e. a class implementing the
Provider interface and annotated with the @WebServiceProvider
annotation according to the rules in Section 5.1, “jakarta.xml.ws.Provider”.
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.
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.
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.
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

  try {
    response = dispatch.invoke(request);
} catch (SOAPFaultException e) {
    QName soapFaultCode = e.getFault().getFaultCodeAsQName();
    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 7.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 7.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 7.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.
Container creates Endpoint objects for an application. The necessary
information to create Endpoint objects may be got from web service
deployment descriptor files.
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.
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()
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.
7.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.
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
7.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.
7.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.
7.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.
7.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.
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”.
7.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.
  <!-- 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);
7.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.
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”.
7.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.
7.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.
wsdlLocation
A URL pointing to the location of the WSDL
document for the service being referred to.
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:
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.
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”.
7.9.1. Example

The following shows both uses of the WebServiceRef annotation.
@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...
7.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.
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.
7.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.
  @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...
7.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.
7.11.1. jakarta.jws.WebService

  @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”.
7.11.2. jakarta.jws.WebMethod

  @Target({METHOD})
public @interface WebMethod {
    String operationName() default "";
    String action() default "" ;
    boolean exclude() default false;
    String name() default "";
    String targetNamespace() default "";
    Mode mode() default Mode.IN;
    boolean header() default false;
    String partName() default "";
public @interface WebResult {
    String name() default "return";
    String targetNamespace() default "";
    boolean header() default false;
    String partName() default "";
  @Target({TYPE, METHOD})
public @interface SOAPBinding {
    public enum Style { DOCUMENT, RPC }
    public enum Use { LITERAL, ENCODED }
    public enum ParameterStyle { BARE, WRAPPED }
    Style style() default Style.DOCUMENT;
    Use use() default Use.LITERAL;
    ParameterStyle parameterStyle() default ParameterStyle.WRAPPED;
7.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.
7.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.
7.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.
The class name of a derived
WebServiceFeature class associated with
the annotated annotation.
No defaults required property
  @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;
7.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.
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 10.4.1.5, “Addressing”.
7.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.
threshold
Specifies the size in bytes that binary data SHOULD be before
being sent as an attachment.
7.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.
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.
8.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.
8.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 8.4, “External Binding File”). The second approach consists
in embeddeding binding declarations directly inside a WSDL document (see
Section 8.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

  <jaxws:bindings wsdlLocation="xs:anyURI"?
                node="xs:string"?
                version="string"?>
  ...binding declarations...
</jaxws:bindings>
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.
8.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.
8.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
  <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>
8.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 8.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 8.5, “Using Jakarta XML Binding Binding Declarations” for more information
on processing Jakarta XML Binding binding declarations.
8.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 8.3.1, “Example”.
 21. Sample external binding file for WSDL
  <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>
  <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>
8.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.
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.
8.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.
8.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.

8.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.
  <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>
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.
8.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.
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.
8.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.
  <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"/>*
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.
8.7.4. PortType Fault Message

The following binding declarations MAY appear in the context of a WSDL
portType operation’s fault message, either as an extension to the
wsdl:portType/wsdl:operation/wsdl:fault element or with a node
attribute pointing at one.
Fully qualified name of the generated exception class for this fault.
class/javadoc/text()
Class-level javadoc string.
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.
If present with a boolean value of true (resp. false), use of the
mime:content information is enabled (resp. disabled) for all
operations in this binding.
8.7.6. Binding Operation

The following binding declarations MAY appear in the context of a WSDL
binding operation, either as an extension to the
wsdl:binding/wsdl:operation element or with a node attribute
pointing at one.
<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>

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.
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.
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.
  <jaxws:method name="xs:string">?
  <jaxws:javadoc>xs:string</jaxws:javadoc>?
</jaxws:method>
<jaxws:provider/>?
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.
Omitting a getXYZPort() method is necessary for consistency, because if
it existed it would specify the non-existing SEI type as its return
type.
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.
9.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 10, 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.
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.
9.1.2. Binding Responsibilities

The following subsections describe the responsibilities of the protocol
binding when hosting a handler chain.
9.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 9.3, “Processing Model”. The binding is responsible for instantiation and
management of message contexts according to the rules specified in
Section 9.4, “Message Context”
◊ Conformance (Logical handler support): All binding implementations MUST support
logical handlers (see Section 9.1.1, “Types of Handler”) being deployed in their
handler chains.
◊ Conformance (Other handler support): Binding implementations MAY support other
handler types (see Section 9.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.
9.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.
9.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 9.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 10.2.2, “Exception Handling”
describes the mechanism for the SOAP 1.1 binding. Inbound exceptions are
passed to the binding provider.
Handler chains may be configured either programmatically or using
deployment metadata. The following subsections describe each form of
configuration.
9.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.
9.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.
9.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 9.3.2, “Handler Execution” describes how the handler order relates to
the order of handler execution for inbound and outbound messages.
9.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

  @WebService
@HandlerChain(file="sample_chain.xml")
public class MyService {
9.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.
9.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].
9.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.
9.3.2. Handler Execution

As described in Section 9.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 9.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 H₁…H₆ in that order: for outbound
messages handler H₁ would be invoked first followed by
H₂, H₃, …, and finally handler
H₆; for inbound messages H₆ would be
invoked first followed by H₅, H₄, …,
and finally H₁.
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 H_i.” 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 H_i.
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 9.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 9.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 9.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 9.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 9.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 9.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 9.1.2.3, “Exception Handling”).
9.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 9.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 9.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 9.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 9.1.2.3, “Exception Handling”).
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 9.3.2, “Handler Execution”).
9.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 9.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 9.4.1, “jakarta.xml.ws.handler.MessageContext” and Section 9.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 10.3, “SOAP Message Context” describes the message context
subtype for the Jakarta XML Web Services SOAP binding.
9.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.
9.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.
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>
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>
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
A resolvable URI that may be used to obtain
access to the WSDL for the endpoint.
.service
QName
The name
of the service being invoked in the WSDL.
.port
QName
The name
of the port over which the current message was received in the WSDL.
.interface
QName
The name of the port type to which the
current message belongs.
.operation
QName
The name of the WSDL
operation to which the current message belongs. The namespace is the
target namespace of the WSDL definitions element.
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
The HTTP method for the request message.
.querystring
String
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
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>>
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
The HTTP response status code.
9.4.2. jakarta.xml.ws.handler.LogicalMessageContext

Logical handlers (see Section 9.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 10.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 11, 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 11, HTTP Binding).
9.4.3. Relationship to Application Contexts

Client side binding providers have methods to access contexts for
outbound and inbound messages. As described in section
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.
This chapter describes the Jakarta XML Web Services SOAP binding and its extensions to the
handler framework (described in Chapter 9, Handler Framework) for SOAP message
processing.
10.1. Configuration

A SOAP binding instance requires SOAP specific configuration in addition
to that described in Section 9.2, “Configuration”. The additional information
can be configured either programmatically or using deployment metadata.
The following subsections describe each form of configuration.
10.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.
10.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:
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:
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.
10.1.1.2. SOAP Handlers

The handler chain for a SOAP binding is configured as described in
Section 9.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 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.
10.1.1.3. SOAP Headers

The SOAP headers understood by a handler are obtained using the
getHeaders method of SOAPHandler.
10.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].
10.2. Processing Model

The SOAP binding implements the general handler framework processing
model described in Section 9.3, “Processing Model” but extends it to include
SOAP specific processing as described in the following subsections.
10.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 9.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:
Obtain the set of SOAP roles for the current binding
instance. This is returned by SOAPBinding.getRoles.

Obtain the set of Handlers deployed on the current
binding instance. This is obtained via Binding.getHandlerChain.

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:

that are mapped to method parameters in the service endpoint
interface;
are members of SOAPHandler.getHeaders() for each SOAPHandler in
the set obtained in Step 2;
are directly supported by the binding instance.
 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.
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.
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.
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 10.2.2, “Exception Handling”).
No response
The binding dispatches the SOAP must understand exception (see
Section 10.2.2, “Exception Handling”).
10.2.2. Exception Handling

The following subsections describe SOAP specific requirements for
handling exceptions thrown by handlers and service endpoint
implementations.
10.2.2.1. Handler Exceptions

A binding is responsible for catching runtime exceptions thrown by
handlers and following the processing model described in
Section 9.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:
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 10.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 9.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.
10.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 9.3.2, “Handler Execution”.
Section 10.2.2.3, “Mapping Exceptions to SOAP Faults” describes the rules for mapping an exception
to a SOAP fault.
10.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:
Serialized service specific exception (see
WrapperException.getFaultInfo() in Section 2.5, “Fault”)
SOAPFaultException.getFault().getDetail()^[12]
SOAP handlers are passed a SOAPMessageContext when invoked.
SOAPMessageContext extends MessageContext with methods to obtain and
modify the SOAP message payload.
10.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.
10.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].
10.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:
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:
◊ 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.
10.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.
10.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.
10.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.
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.
10.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.
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.
11.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 9.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 only defines APIs for programmatic configuration of client side
XML/HTTP bindings – server side bindings are expected to be configured
using deployment metadata.
11.1.1.1. HTTP Handlers

The handler chain for an XML/HTTP binding is configured as described in
Section 9.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.
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.
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 XML/HTTP binding implements the general handler framework processing
model described in Section 9.3, “Processing Model”.
11.2.1. Exception Handling

The following subsections describe HTTP specific requirements for
handling exceptions thrown by handlers and service endpoint
implementations.
11.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 9.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:
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 9.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.
11.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 9.3.2, “Handler Execution”.
Section 11.2.1.3, “Mapping Exceptions to a HTTP Status Code” describes the rules for mapping an exception
to a HTTP status code.
11.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:
11.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.
11.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.
11.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.
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.
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
Updated that the use of metadata in mime:content is disabled by
default (Section 2.6.3.1, “mime:content”)
Updated generated service constructor requirements (section
Section 2.7, “Service and Port”,Section 4.1.1.2, “Static case”)
Updated that static or final methods cannot be web methods (section
Section 3.3, “Class”)
Added wsam:Action algorithm and requirements (Section 3.5, “Method”,
Section 3.5.2, “wsam:Action Computation Algorithm”)
Clarified the namespace of the generated JAXB beans (section
Section 3.6, “Method Parameters and Return Type”)
Added that packaging wrapper beans optional (section
Section 3.6.2.1, “Document Wrapped”)
Added requirements for wsdl:part names in doc/lit wrapper case
(Section 3.6.2.1, “Document Wrapped”)
Added that @XmlElement can be specified on doc/lit wrapper method
parameters (Section 3.6.2.1, “Document Wrapped”)
Added wsdl:message naming requirements (Section 3.7, “Service Specific Exception”)
Added @XmlType requirements on exception classes (section
Section 3.7, “Service Specific Exception”)
Clarified the fault bean’s @XmlType requirements (section
Section 3.7, “Service Specific Exception”)
Added that packaging exception beans optional (Section 3.7, “Service Specific Exception”)
Added Use of Addressing requirements in WSDL (Section 3.11, “Service and Ports”)
Added service creation with web service features (section
Section 4.1.1.1, “Dynamic case”)
Added W3CEndpointReference requirements (Section 4.2, “jakarta.xml.ws.BindingProvider”,
Section 5.2.8, “jakarta.xml.ws.EndpointReference”, Section 5.3, “jakarta.xml.ws.WebServiceContext”, Section 5.4, “jakarta.xml.ws.wsaddressing.W3CEndpointReferenceBuilder”)
Added Use of Addressing requirements in proxies (Section 4.2.3, “Proxies”)
Clarified the empty payload Source for Provider (section
Section 5.1, “jakarta.xml.ws.Provider”)
Clarified oneway invocation for Provider endpoints (section
Section 5.1.1, “Invocation”)
Added features usage with Endpoint API (Section 5.2.1, “Endpoint Usage”,
Section 6.2.2, “Creating Endpoint Objects”)
Added HTTP SPI (Section 6.6, “jakarta.xml.ws.spi.http (HTTP SPI)”)
Clarified that fully qualified class name can be specified for
generated exception, service classes customizations (section
Section 8.7.4, “PortType Fault Message”, Section 8.7.7, “Service”)
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 10.4.1.5, “Addressing” Addressing.
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.
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).
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 10.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 11, HTTP Binding.
Renamed element'' attribute of the jaxws:parameter annotation to
childParameterName'' for clarity, see sections
Section 8.7.3, “PortType Operation” and Section 8.7.6, “Binding Operation”.
Added javax.xml.ws.ServiceMode annotation type, see section
Section 7.1, “jakarta.xml.ws.ServiceMode”.
Fixed example of external binding file to use a schema annotation, see
Section 8.4, “External Binding File”.
Modified Dispatch so it can be used with multiple message types and
either message payloads or entire messages, see Section 4.3, “jakarta.xml.ws.Dispatch”.
Modified Provider so it can be used with multiple message types and
either message payloads or entire messages, see section
Section 5.1, “jakarta.xml.ws.Provider”.
Added new annotation for generated exceptions, see section
Section 7.2, “jakarta.xml.ws.WebFault”.
Added default Java package name to WSDL targetNamespace mapping
algorithm, see Section 3.2, “Package”.
Added ordering to properties in request and response beans for
doc/lit/wrapped, see Section 3.6.2.1, “Document Wrapped”.
Clarified that SEI method should throw JAX-RPC exception with a cause
of any runtime exception thrown during local processing, see section
Section 4.2.4, “Exceptions”.
Removed requirement that SEIs MUST NOT have constants, see section
Section 3.4, “Interface”.
Updated document bare mapping to clarify that @WebParam and
@WebResult can be used to customize the generated global element
names, see Section 3.6.2.2, “Document Bare”.
Added mapping from Java to wsdl:service and wsdl:port, see
sections Section 3.8.1, “Interface”, Section 3.10.1, “Interface” and Section 3.11, “Service and Ports”.
Fixed Section 2.4, “Types” to allow use of JAXB interface based
mapping.
Added support for document/literal/bare mapping in Java to WSDL
mapping, see Section 3.6, “Method Parameters and Return Type”.
Added conformance requirement to describe the expected behaviour when
two or more faults refer to the same global element, see section
Section 2.5, “Fault”.
Added resolution to issue regarding binding of duplicate headers, see
Section 2.6.2.1, “Header Binding Extension”.
Added use of JAXB ns URI to Java package name mapping, see section
Section 2.1, “Definitions”.
Added use of JAXB package name to ns URI mapping, see section
Section 3.2, “Package”.
Introduced new typographic convention to clearly mark non-normative
notes.
Removed references to J2EE and JNDI usage from ServiceFactory
description, see [svcfactusage].
Clarified relationship between TypeMappingRegistry and JAXB.
Emphasized control nature of context properties, added lifecycle
subsection.
Clarified fixed binding requirement for proxies.
Added section for SOAP proocol bindings Section 10.4, “SOAP Transport and Transfer Bindings”. The HTTP
subsection of this now contains much of the mterial from the JAX-RPC 1.1
Runtime Services chapter.
Clarified that async methods are added to the regular sync SEI when
async mapping is enabled rather than to a separate async-only SEI, see
Section 2.3.4, “Asynchrony”.
Added support for WSDL MIME binding, see section
Section 2.6.3, “MIME Binding”.
Clarified that fault mapping should only generate a single exception
for each equivalent set of faults, see Section 2.5, “Fault”.
Added property for message attachments.
Removed element references to anonymous type as valid for wrapper
style mapping (this doesn’t prevent substitution as orignally thought),
see Section 2.3.1.2, “Wrapper Style”.
Removed implementation specific methods from generated service
interfaces, see Section 2.7, “Service and Port”.
Clarified behaviour under fault condition for asynchronous operation
mapping, see Section 2.3.4.5, “Faults”.
Clarified that additional parts mapped using soapbind:header cannot be
mapped to a method return type, see Section 2.3.2, “Parameter Order and Return Type”.
Added new section to clarify mapping from exception to SOAP fault, see
Section 10.2.2.3, “Mapping Exceptions to SOAP Faults”.
Clarified meaning of other in the handler processing section, see
Section 9.3.2, “Handler Execution”.
Added a section to clarify Stub use of RemoteException and
JAXRPCException, see Section 4.2.4, “Exceptions”.
Added new Core API chapter and rearranged sections into Core, Client
and Server API chapters.
Changes for context refactoring, removed message context properties
that previously held request/response contexts on client side, added
description of rules for moving between jaxws context and message
context boundaries.
Removed requirement for Response.get to throw JAXRPCException, now
throws standard java.util.concurrent.ExecutionException instead.
Added security API information, see sections [servicesecurityconfig]
and [bindingmsgsec].
Clarrified SOAP mustUnderstand processing, see section
Section 10.2.1, “SOAP mustUnderstand Processing”. Made it clear that the handler rather than the
HandlerInfo is authoritative wrt which protocol elements (e.g. SOAP
headers) it processes.
Updated exception mapping for Java to WSDL since JAXB does not
envision mapping exception classes directly, see Section 3.7, “Service Specific Exception”.
[1] Tim Bray, Jean Paoli, C. M. Sperberg-McQueen, and Eve Maler. Extensible Markup Language
(XML) 1.0 (Second Edition). Recommendation, W3C, October 2000. See
http://www.w3.org/TR/2000/REC-xml-20001006.
[2] Don Box, David Ehnebuske, Gopal Kakivaya, Andrew Layman, Noah Mendelsohn, Henrik Nielsen,
Satish Thatte, and Dave Winer. Simple Object Access Protocol (SOAP) 1.1. Note, W3C, May 2000.
See http://www.w3.org/TR/SOAP/.
[3] Martin Gudgin, Marc Hadley, Noah Mendelsohn, Jean-Jacques Moreau, and Henrik Frystyk Nielsen.
SOAP Version 1.2 Part 1: Messaging Framework. Recommendation, W3C, June 2003. See
http://www.w3.org/TR/2003/REC-soap12-part1-20030624.
[4] Martin Gudgin, Marc Hadley, Noah Mendelsohn, Jean-Jacques Moreau, and Henrik Frystyk Nielsen.
SOAP Version 1.2 Part 2: Adjuncts. Recommendation, W3C, June 2003. See
http://www.w3.org/TR/2003/REC-soap12-part2-20030624.
[5] Erik Christensen, Francisco Curbera, Greg Meredith, and Sanjiva Weerawarana. Web Services
Description Language (WSDL) 1.1. Note, W3C, March 2001. See
http://www.w3.org/TR/2001/NOTE-wsdl-20010315.
[6] Rahul Sharma. The Java API for XML Based RPC (JAX-RPC) 1.0. JSR, JCP, June 2002. See
http://jcp.org/en/jsr/detail?id=101.
[7] Jakarta XML RPC Specification 1.1. Eclipse Foundation, September 2019. See
https://jakarta.ee/specifications/xml-rpc/.
[8] Keith Ballinger, David Ehnebuske, Martin Gudgin, Mark Nottingham, and Prasad Yendluri. Basic
Profile Version 1.0. Final Material, WS-I, April 2004. See
http://www.ws-i.org/Profiles/BasicProfile-1.0-2004-04-16.html.
[9] Joseph Fialli and Sekhar Vajjhala. The Java Architecture for XML Binding (JAXB). JSR, JCP,
January 2003. See http://jcp.org/en/jsr/detail?id=31.
[10] Joseph Fialli and Sekhar Vajjhala. The Java Architecture for XML Binding (JAXB) 2.0. JSR, JCP,
August 2003. See http://jcp.org/en/jsr/detail?id=222.
[11] Kohsuke Kawaguchi. The Java Architecture for XML Binding (JAXB) 2.1. JSR, JCP, August 2003.
See http://jcp.org/en/jsr/detail?id=222.
[12] Kohsuke Kawaguchi. The Java Architecture for XML Binding (JAXB) 2.2. JSR, JCP, August 2009.
See http://jcp.org/en/jsr/detail?id=222.
[13] Kohsuke Kawaguchi. The Java Architecture for XML Binding (JAXB) 2.3. JSR, JCP, July 2017. See
http://jcp.org/en/jsr/detail?id=222.
[14] Roberto Chinnici, Martin Gudgin, Jean-Jacques Moreau, Jeffrey Schlimmer, and Sanjiva
Weerawarana. Web Services Description Language (WSDL) Version 2.0 Part 1: Core Language.
Working Draft, W3C, August 2004. See http://www.w3.org/TR/2004/WD-wsdl20-20040803.
[15] Joshua Bloch. A Metadata Facility for the Java Programming Language. JSR, JCP, August 2003. See
http://jcp.org/en/jsr/detail?id=175.
[16] Jakarta XML Web Services Metadata Specification 3.0. Eclipse Foundation, November 2020. See
https://jakarta.ee/specifications/web-services-metadata.
[17] Jakarta Enterprise. Web Services Specification. Eclipse Foundation, November 2020. See
http://jcp.org/en/jsr/detail?id=109.
[18] Nataraj Nagaratnam. Web Services Message Security APIs. JSR, JCP, April 2002. See
http://jcp.org/en/jsr/detail?id=183.
[19] Jakarta XML Registries Specification 1.0. Eclipse Foundation, September 2019. See
https://jakarta.ee/specifications/xml-registries.
[20] Keith Ballinger, David Ehnebuske, Chris Ferris, Martin Gudgin, Canyang Kevin Liu, Mark
Nottingham, Jorgen Thelin, and Prasad Yendluri. Basic Profile Version 1.1. Final Material, WS-I,
August 2004. See http://www.ws-i.org/Profiles/BasicProfile-1.1-2004-08-24.html.
[21] T. Berners-Lee, R. Fielding, and L. Masinter. RFC 2396: Uniform Resource Identifiers (URI):
Generic Syntax. RFC, IETF, March 1997. See http://www.ietf.org/rfc/rfc2396.txt.
[22] S. Bradner. RFC 2119: Keywords for use in RFCs to Indicate Requirement Levels. RFC, IETF,
March 1997. See http://www.ietf.org/rfc/rfc2119.txt.
[23] John Cowan and Richard Tobin. XML Information Set. Recommendation, W3C, October 2001. See
http://www.w3.org/TR/2001/REC-xml-infoset-20011024/.
[24] Henry S. Thompson, David Beech, Murray Maloney, and Noah Mendelsohn. XML Schema Part 1:
Structures. Recommendation, W3C, May 2001. See
http://www.w3.org/TR/2001/REC-xmlschema-1-20010502/.
[25] Paul V. Biron and Ashok Malhotra. XML Schema Part 2: Datatypes. Recommendation, W3C, May
+2001. See http://www.w3.org/TR/2001/REC-xmlschema-2-20010502/.
[26] Tony Rogers Marting Gudgin, Marc Hadley. Web services addressing 1.0 - core. Recommendation,
W3C, May 2006. See http://www.w3.org/TR/2006/REC-ws-addr-core-20060509/.
[27] Marting Gudgin, Marc Hadley, Tony Rogers, and Umit Yalcinalp. Web Services Addressing 1.0 -
Metadata. Recommendation, W3C, September 2007. See
http://www.w3.org/TR/2007/REC-ws-addr-metadata-20070904.
[28] Asir S Vedamuthu, David Orchard, Frederick Hirsch, Maryann Hondo, Prasad Yendluri, Toufic
Boubez, and Umit Yalcinalp. Web Services Services Policy 1.5 - Framework. Recommendation,
W3C, September 2007. See http://www.w3.org/TR/2007/REC-ws-policy-20070904.
[29] James Gosling, Bill Joy, Guy Steele, and Gilad Bracha. The Java Language Specification - second
edition. Book, Sun Microsystems, Inc, 2000.
http://java.sun.com/docs/books/jls/second edition/html/j.title.doc.html.
[30] Martin Gudgin, Noah Mendelsohn, Mark Nottingham, and Herve Ruellan. SOAP Message
Transmission Optimization Mechanism. Recommendation, W3C, January 2005.
http://www.w3.org/TR/soap12-mtom/.
[31] Martin Gudgin, Noah Mendelsohn, Mark Nottingham, and Herve Ruellan. XML-binary Optimized
Packaging. Recommendation, W3C, January 2005. http://www.w3.org/TR/xop10/.
[32] Mark Nottingham. Simple SOAP Binding Profile Version 1.0. Working Group Draft, WS-I, August
+2004. See http://www.ws-i.org/Profiles/SimpleSoapBindingProfile-1.0-2004-08-24.html.
[33] Chris Ferris, Anish Karmarkar, and Canyang Kevin Liu. Attachments Profile Version 1.0. Final
Material, WS-I, August 2004. See
http://www.ws-i.org/Profiles/AttachmentsProfile-1.0-2004-08-24.html.
[34] Norm Walsh. XML Catalogs 1.1. OASIS Committee Specification, OASIS, July 2005. See
http://www.oasis-open.org/committees/download.php/14041/xml-catalogs.html.
[35] Rajiv Mordani. Common Annotations for the Java Platform. JSR, JCP, July 2005. See
http://jcp.org/en/jsr/detail?id=250.
[36] Jakarta EE Platform 9 Specification. Eclipse Foundation, November 2020. See
https://jakarta.ee/specifications/platform.
[37] Tony Rogers Marting Gudgin, Marc Hadley. Web services addressing 1.0 - soap binding.
Recommendation, W3C, May 2006. See http://www.w3.org/TR/2006/REC-ws-addr-soap-20060509/.
[38] John Barton, Satish Thatte, and Henrik Frystyk Nielsen. SOAP Messages With Attachments. Note,
W3C, December 2000. http://www.w3.org/TR/SOAP-attachments.
[39] Jakarta XML Binding Specification 3.0. Eclipse Foundation, November 2020. See
https://jakarta.ee/specifications/xml-binding.
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 9.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.