Find JSRs
Submit this Search


Ad Banner
 
 
 
 

 Change Log for JSR-000181 Web Services Metadata for the Java Platform

Change Log for JSR-000181 Web Services Metadata for the Java Platform

This page details the proposed, accepted and deferred changes to JSR 181 documenting the changes that will go into the next revision, per Section 4.2 of the JCP 2.6 document.

Last updated: 24 March 2006

Description

Maintenance revision of Web Services Metadata for the Java Platform

Maintenance Lead

Stuart Edmondston, BEA Systems
Brian Zotter, BEA Systems

Feedback

Comments should be sent to jsr-181-comments@jcp.org .

PROPOSED CHANGES
Request Summary Specification
1Change version to 2.0 Title page

Replace:

Version 1.0

With:

Version 2.0
 
2WebResult - WebParam has a header="true" annotation element. WebResult does not have any such annotation element. Without that we cannot bind a return type(WebResult) to a header. Section 4.5.1 - Description

Add:

header If true, the parameter is in the message header rather then the message body. false

Section 4.5.2 - Annotation Type Definition

Add:

boolean header() default false;

Section 6.2 - Headers

Add:

Results annotated with the @WebResult.header annotation element map to SOAP headers instead of elements in the SOAP body. Header results appear as parts in the operation's output message. Header results are included as soap:header elements in the appropriate wsdl:output sections of the binding operation. Headers are always literal. The @WebResult.name and @WebResult.targetNamespace annotations determine the QName of the XML element representing the header.
 
3A document "bare" style operation can have a void return type and a Holder as a parameter. The Holder of course would have to be INOUT. It could also have 2 parameters one IN and one OUT. Section 6.1.2.2 - Document 'Bare' Style

Replace:

Web Services that use the document "bare" style MUST adhere to several restrictions. Each document "bare" operation MUST have only a single non-header parameter. If the operation is not marked @Oneway, it MUST also have a non-void return value.

With:

Web Services that use the document "bare" style MUST adhere to the following restrictions:

o If the operation is marked @Oneway, it MUST have a void return value, a single non-header parameter marked as IN and zero or more header parameters.
o If the operation is not marked @Oneway, it may have one of the following forms:
o A non-header parameter marked as IN, a non-header parameter marked as OUT, a void return value and zero or more header parameters.
o A single non-header parameters marked as IN_OUT, a void return value and zero or more header parameters.
o A single non-header parameter marked as IN, non-void return value and zero or more header parameters.
 
7SOAPBinding - support for unwrapped (bare) vs wrapped to be configurable on a per operation basis rather than on the entire interface. Section 4.7.1 - Description

Add:

The SOAPBinding annotation has a target of TYPE and METHOD. The annotation may be placed on a method if and only if the SOAPBinding.style is DOCUMENT. Implementations MUST report an error if the SOAPBinding annotation is placed on a method with a SOAPBinding.style of RPC. Methods which do not have a SOAPBinding annotation accept the SOAPBinding behavior defined on the type.

Section 4.7.2 - Annotation Type Definition

Replace:

@Target({TYPE})

With:

@Target({TYPE, METHOD})
 
12For HandlerChains in the JAX-WS, the name is not required. Section 4.6.1 - Description

Replace:

name Name of the handler chain in the configuration file. None

With:

name Deprecated. As of Web Services Metadata 2.0 with no replacement.

The name was originally used to associate a JAX-RPC handler in a handler chain with the web service it is declared in. JAX-WS handlers are associated to web services via elements in the handler chain itself. In this version, the name is ALWAYS ignored.

This member-value will be permanently removed in a future version of Web Services Metadata. ""

Section 4.6.2 - Annotation Type Definition

Replace:

String name();

With:

String name() default "";
 
14@SOAPMessageHandlers are not supported in JAX-WS. Section 3.1 - Service Implementation Bean

Replace:

, @HandlerChain and @SOAPMessageHandlers

With:

and @HandlerChain

Section 4.8 - Annotation: javax.jws.soap.SOAPMessageHandlers

Replace:

4.8.1 Description
Specifies a list of SOAP protocol handlers that run before and after business methods on the Web Service. These handlers are called in response to SOAP messages targeting the service. The handler API and processing rules are described in JAX-RPC 1.1 [5], section 12.

The @SOAPMessageHandlers annotation is an array of SOAPMessageHandler types. The handlers are run in the order in which they appear in the annotation, starting with the first handler in the array. Each SOAPMessageHandler has the following member-values:

It is an error to combine this annotation with the @HandlerChain annotation.

The @SOAPMessageHandlers annotation MAY be present on the endpoint interface and service implementation bean. The service implementation bean's @SOAPMessageHandlers is used if @SOAPMessageHandlers is present on both.


Member-Value Meaning Default
name Name of the handler. Name of the handler class
className Name of the handler class None
initParams Array of name/value pairs that will be passed to the handler during initialization No init params
roles List of SOAP roles implemented by the handler No roles
headers List of SOAP headers processed by the handler. Each element in this array contains a QName which defines the header element processed by the handler. The QNames are specified using the string notation described in the documentation for javax.xml.namespace.QName.valueOf(String qNameAsString). No headers
4.8.2 Annotation Type Definition
public @interface InitParam {
String name();
String value();
};

public @interface SOAPMessageHandler {
String name() default "";
String className();
InitParam[] initParams() default {};
String[] roles() default {};
String[] headers() default {};
};

@Retention(value=RetentionPolicy.RUNTIME)
Target({TYPE})
public @interface SOAPMessageHandlers {
SOAPMessageHandler[] value();
};
4.8.3 Example:

Java source (simple scenario):

@WebService
@SOAPMessageHandlers({
@SOAPMessageHandler(
className = "com.fabrikam.handlers.LogHandler"),
@SOAPMessageHandler(
className = "com.fabrikam.handlers.AuthorizationHandler"),
@SOAPMessageHandler(
className = "com.fabrikam.handlers.RoutingHandler")
})
public class MyWebService {

@WebMethod
public String echo(String input) {
return input;
}
};

Java source (complex scenario):

@SOAPMessageHandlers({
@SOAPMessageHandler(
className = "com.fabrikam.handlers.LogHandler",
initParams = {@InitParam(name="logCategory", value="MyService")}
),
@SOAPMessageHandler(
className = "com.fabrikam.handlers.AuthorizationHandler",
roles = {"SecurityProvider"},
headers = {"{http://openuri.org/examples/security}/SecurityHeader"}
),
@SOAPMessageHandler(
className = "com.fabrikam.handlers.RoutingHandler"
)
})
public class MyWebService {

@WebMethod
public String echo(String input) {
return input;
}
};

With:

Deprecated. As of Web Services Metadata 2.0 with no replacement.

This annotation was originally used to create a JAX-RPC handler chain. In this version, the annotation is ALWAYS ignored.

This annotation will be permanently removed in a future version of Web Services Metadata.
 
16Add support for JAX-WS.
Currenty the spec refers to JAX-RPC 1.1 wrt:
  • Class defintion
  • Method signature
  • Parameter and return types
  • Holder types
  • Handler API and processing
  • Name mangling


It would be nice if it stated that JAX-WS would use these annotations at runtime on both the client and server. 		Section 1 - Introduction

Replace:

JAX-RPC 1.1

With:

JAX-WS 2.0

Section 1.4 - Objectives

Replace:

It is not a goal of this specification to support every feature or to enable the creation of every Web Service that is possible to write with existing specifications (JAX-WS 2.0 [5] extends on this specification to provide finer control over the resultant Web Service). However, it is a goal to make it easy to build the commonly needed types of Web Services.

With:

It is not a goal of this specification to support every feature or to enable the creation of every Web Service that is possible to write with existing specifications (JAX-WS 2.0 [5] provides finer control over the resultant Web Service). However, it is a goal to make it easy to build the commonly needed types of Web Services.

Section 2.1 - Programming Model Overview

Replace:

JSR-181 builds on the existing J2EE 1.4 server programming model described by JAX-RPC and JSR-109.

With:

JSR-181, along with JAX-WS and JSR109, defines a programming model for building web services on the Java platform.

Section 2.2.1 - Start With Java

Replace:

By default, the WSDL produced from the Java source follows the Java to XML/WSDL mapping defined by JAX-RPC 1.1.

With:

By default, the WSDL produced from the Java source follows the Java to XML/WSDL mapping defined by JAX-WS 2.0.

Section 2.4 - Runtime Responsibilities

Remove:

Chapter 9 defines one such a mapping, to the Java EE 5 environment. Subsequent revisions to the specification will update this mapping for other environments, such as Java EE 5.

Section 3 - Server Programming Model

Replace:

The JSR-181 server programming model is a simplification of the existing J2EE Web Services server programming models, as defined in JAX-RPC and JSR-109.

With:

The JSR-181 server programming model is a simplification of the existing Java EE Web Services server programming models, as defined in JAX-WS and JSR-109.

Section 3.2 - Service Endpoint Interface

Replace:

A JSR-181 service endpoint interface MUST meet the requirements specified by JAX-RPC 1.1 [5], section 5.2,

With:

A JSR-181 service endpoint interface MUST meet the requirements specified by JAX-WS 2.0 [5], section 3.4,

Section 3.2 - Service Endpoint Interface

Remove:

Section 7.1 contains the complete list of annotations allowed on a service endpoint interface.

Section 3.3 - Web Methods

Replace:

The method's parameters, return value, and exceptions MUST follow the rules defined by JAX-RPC 1.1 [5], section 5.

With:

The method's parameters, return value, and exceptions MUST follow the rules defined by JAX-WS 2.0 [5], section 3.6.

Section 4.4.1 - Description

Replace:

JAX-RPC 1.1 [5], section 4.3.5

With:

JAX-WS 2.0 [5], section 2.3.3

Section 5 - Java Mapping to XML/WSDL

Replace:

By default, JSR-181 follows the Java to XML/WSDL mapping defined in JAX-RPC 1.1 [5] section 5, except as noted in this section.

With:

By default, JSR-181 follows the Java to XML/WSDL mapping defined in JAX-WS 2.0 [5] section 3, except as noted in this section.

Section 5.1 - Service Endpoint Interface

Remove:

As described in JAX-RPC 1.1 [5] section 5.2,

Section 5.1 - Service Endpoint Interface

Replace:

JAX-RPC

With:

JAX-WS

Section 5.3 - Web Method Mapping

Replace:

If not present, the wsdl:operation local name is mapped from the name of the Java method according to the rules defined in JAX-RPC 1.1 [5], section 5.5.5.

With:

If not present, the wsdl:operation local name is mapped from the name of the Java method according to the rules defined in JAX-WS 2.0 [5], section 3.5.

Section 5.3 - Web Method Mapping

Replace:

Java types used as method parameters, return values, and exceptions are mapped according to the rules defined in JAX-RPC 1.1 [5], section 5.5.5.

With:

Java types used as method parameters, return values, and exceptions are mapped according to the rules defined in JAX-WS 2.0 [5], section 3.6.

Section 6 - SOAP Binding

Replace:

By default JSR-181 follows the SOAP binding defined in JAX-RPC 1.1 [5], section 6.

With:

By default JSR-181 follows the SOAP binding defined in JAX-WS 2.0 [5], section 10.

Section 6 - SOAP Binding

Remove:

The @SOAPBinding, @WebParam, and @WebResult annotations allow the developer to further customize this binding for a particular Web Service.

Section 7 - Mapping JSR-181 to the J2EE 1.4 Runtime Environment

Remove:

7 Mapping JSR-181 to the J2EE 1.4 Runtime Environment
7.1 Overview
This section describes the mapping of JSR-181 metadata onto J2EE 1.4 Web Services, as defined in JAX-RPC 1.1 and JSR-109 v1.1.

Note: Although this specification defines a standard mapping for metadata to JSR-109 deployment descriptors, the actual production or export of JSR-109 artifacts is OPTIONAL. Semantic support for this mapping is mandatory and is what guarantees portable deployment across J2EE environments.

The following diagram shows the non-normative processing model for JSR-181 on top of J2EE 1.4.




One or more service implementation beans are passed to the JSR-181 processor in source or class form. The JSR-181 processor examines the annotations in each Web Service file and uses this information to generate a JSR-109 deployment unit (EAR or WAR file). The JSR-109 deployment unit contains the following artifacts:

o The compiled Java classes required for deployment. This includes the Web Service implementations, all referenced Java classes, and any generated Home or Remote interfaces.
o WSDL documents describing each service. If @WebService.wsdlLocation is specified, the WSDL file will be copied with all of its dependencies from this location and placed into the deployment unit. If @WebService.wsdlLocation is not specified, the WSDL file is generated from the annotations in the service implementation bean.
o Service endpoint interfaces defining the methods implemented by each service. The service endpoint interface may be written by the developer or generated from the annotations on the service implementation bean.
o The webservices.xml deployment descriptor. This deployment descriptor contains references to all of the Web Services in the deployment unit. There will be one webservice entry for each Web Service class processed by the JSR-181 processor. Section 7.4.1 Mapping from JSR-181 to webservices.xml describes the mapping from JSR-181 annotations to entries in webservices.xml.
o The jax-rpc-mapping.xml deployment descriptor. Section 7.4.3 - Mapping from JSR-181 to jax-rpc-mapping.xml describes the mapping from JSR-181 annotations to entries in jax-rpc-mapping.xml.
o One of either a web.xml or ejb-jar.xml deployment descriptor. The JSR-181 processor will generate either a web.xml deployment descriptor (for servlet endpoints) or an ejb-jar.xml deployment descriptor (for stateless session beans) depending on the implementation model chosen for the service. See the next section for more information on selecting an implementation model.

Once generated, the values in the deployment descriptors may be overridden by the deployer or administrator using standard deployment tools, including JSR 88 deployment plans. This capability allows customization of the Web Service without requiring access to the source code.
7.2 Implementation Models
J2EE 1.4 Web Services may be implemented as plain classes in the servlet container or as stateless session beans in the EJB container. A JSR-181 implementation targeting J2EE 1.4 MUST provide an out-of-band mechanism allowing the developer to specify explicitly the container in which a particular Web Service implementation should run. Future versions of the specification will combine with other J2EE 5.0 technologies (such as EJB3) to provide a standard annotation-driven approach to specifying container-specific technologies and qualities of service.
7.3 Service Endpoint Interface
Every J2EE 1.4 Web Service is required to reference a service endpoint interface that defines the methods implemented by the service. If the JSR-181 service implementation bean does not reference a service endpoint interface through the @WebService.endpointInterface annotation, the JSR-181 processor is REQUIRED to generate the interface from the annotations on the implementation bean. The generated service endpoint interface is given an implementation-defined name, placed in an implementation-defined package, and contains a method for each designated web method on the service implementation bean. The signature of each service endpoint interface method is identical to that of the corresponding web method, except that it includes java.rmi.RemoteException in the list of checked exceptions.
7.4 Mapping from JSR-181 to JSR-109 Deployment Descriptors
The JSR-109 deployment model for Web Services defines two deployment descriptors - the JSR-109 deployment descriptor (webservices.xml) and the JAX-RPC mapping file (jax-rpc-mapping.xml). These files contain deployment and mapping information for J2EE Web Services. The following sections describe the mapping from JSR-181 to the JSR-109 deployment descriptors. A JSR-181 implementation that produces JSR-109 deployment descriptors MUST conform to this mapping.
7.4.1 Mapping from JSR-181 to webservices.xml
Every endpoint supported by a JSR-181 Web Service results in a unique webservice entry in webservices.xml. The following table shows the relationship between elements in the webservice and JSR-181 annotations:
webservices.xml entry JSR-181 Annotation and Member-Value
webservices/webservice One entry per Web Service
webservices/webservice/wsdl-file WSDL generated from service implementation bean or copied from @WebService.wsdlLocation
webservices/webservice/jax-rpc-mapping-file JAX-RPC mapping file generated from service implementation bean
webservices/webservice/port-component/port-component-name Implementation defined
webservices/webservice/port-component/wsdl-port Implementation defined
webservices/webservice/port-component/service-endpoint-interface Generated from the annotations defined on the Web Service
webservices/webservice/service-impl-bean/ejb-link or webservices/webservice/service-impl-bean/service-link Implementation defined
webservices/webservice/handler @SOAPMessageHandlers or @HandlerChain

7.4.2 Example - Mapping JSR-181 to webservices.xml

Java Source:

@WebService(targetNamespace="http://www.openuri.org/MyNamespace"
name="StockQuoteService")
@SOAPBinding
@SOAPMessageHandlers({
@SOAPMessageHandler(
className = "com.fabrikam.handlers.LogHandler",
initParams = {
@InitParam(name="logCategory", value="MyService")
}
),
@SOAPMessageHandler(
className = "com.fabrikam.handlers.AuthorizationHandler"
roles = {"SecurityProvider"},
headers = {
"{http://openuri.org/examples/security}SecurityHeader"
}
),
@SOAPMessageHandler(
className = "com.fabrikam.handlers.RoutingHandler"
)
})
public class StockQuoteServiceImpl {

@WebMethod(operationName="GetLastTrade")
public long getLastTrade(String tickerSymbol) {
// . . .
}

@WebMethod(operationName="GetTickerSymbols")
public String[] getTickerSymbols() {
// . . .
}
}

Resulting webservices.xml:

<webservices>
<webservice
xmlns:ns1="http://www.openuri.org/MyNamespace">
<wsdl-file>StockQuoteService.wsdl</wsdl-file>
<port-component>
<port-component-name>
StockQuoteServiceSoapHttp
</port-component-name>
<service-endpoint-interface>
StockQuoteService
</service-endpoint-interface>
<wsdl-port>ns1:StockQuoteServiceSoapHttpPort</wsdl-port>

<handler>
<handler-name>
com.fabrikam.handlers.LogHandler
</handler-name>
<handler-class>
com.fabrikam.handlers.LogHandler
</handler-class>
<init-param>
<param-name>logCategory</param-name>
<param-value>MyService</param-value>
</init-param>
</handler>
<handler>
<handler-name>
com.fabrikam.handlers.AuthorizationHandler
</handler-name>
<handler-class>
com.fabrikam.handlers.AuthorizationHandler
</handler-class>
<soap-role>SecurityProvider</soap-role>
<soap-header
xmlns:ns2=http://openuri.org/examples/security>
ns2:SecurityHeader
</soap-header>
</handler>
<handler>
<handler-name>
com.fabrikam.handlers.RoutingHandler
</handler-name>
<handler-class>
com.fabrikam.handlers.RoutingHandler
</handler-class>
</handler>
<ejb-link>StockQuoteServiceEJB</ejb-link>
</port-component>
</webservice>
</webservices>

7.4.3 Mapping from JSR-181 to jax-rpc-mapping.xml

Every JSR-181 Web Service results in a unique service-endpoint-mapping entry in the jax-rpc-mapping file. The following table shows the relationship between the elements in the service-endpoint-mapping and JSR-181 annotations.

Jax-rpc-mapping.xml entry JSR-181 Annotation and Member-Value
/java-wsdl-mapping/service-endpoint-mapping One entry per Web Service
/java-wsdl-mapping/service-endpoint-mapping/service-endpoint-interface Generated from the annotations on the Web Service.
/java-wsdl-mapping/service-endpoint-mapping/wsdl-port-type @WebService.name
/java-wsdl-mapping/service-endpoint-mapping/wsdl-binding Implementation defined
/java-wsdl-mapping/service-endpoint-mapping/service-endpoint-method-mapping/wsdl-operation @WebMethod.operationName
/java-wsdl-mapping/service-endpoint-mapping/service-endpoint-method-mapping/wrapped-element Present if @SOAPBinding.parameterStyle is WRAPPED

7.4.4 Example - Mapping from JSR-181 to jax-rpc-mapping.xml

Java Source:

@WebService(targetNamespace="http://www.openuri.org/MyNamespace"
name="StockQuoteService")
@SOAPBinding(name="StockQuoteServiceSoap")
public class StockQuoteServiceImpl {

@WebMethod(operationName="GetLastTrade")
public GetLastTradeResponse getLastTrade(
GetLastTradeRequest request) {
// . . .
}

@WebMethod(operationName="GetTickerSymbols")
public String[] getTickerSymbols() {
// . . .
}
}

Resulting java-xml-rpc-mapping.xml:

<java-wsdl-mapping>
<service-endpoint-mapping
xmlns:ns1="http://www.openuri.org/MyNamespace">
<service-endpoint-interface>StockQuoteService</service-endpoint-interface>
<wsdl-port-type>ns1:StockQuoteService</wsdl-port-type>
<wsdl-binding>ns1:StockQuoteServiceSoap</wsdl-binding>
<service-endpoint-method-mapping>
<java-method-name>getLastTrade</java-method-name>
<wsdl-operation>GetLastTrade</wsdl-operation>
<wrapped-element/>
</service-endpoint-method-mapping>
<service-endpoint-method-mapping>
<java-method-name>getTickerSymbols</java-method-name>
<wsdl-operation>GetTickerSymbols</wsdl-operation>
<wrapped-element/>
</service-endpoint-method-mapping>
</service-endpoint-mapping>
</java-wsdl-mapping>

Section 9 - References

Add:

12. JAX-WS V2.0
http://www.jcp.org/en/jsr/detail?id=224

Appendix A: Relationship to Other Standards

Replace:

JAX-RPC 1.1

With:

JAX-WS 2.0
 
17Update section 3.1 Service Implementation Bean, Item 6 that describe exposing all public methods if not @WebMethod annotations are declared to include consideration of annotation inheritence. Section 3.1 - Service Implementation Bean

Replace:

6. If the implementation bean does not implement a service endpoint interface all public methods other than those inherited from java.lang.Object will be exposed as Web Service operations. This behavior can be overridden by using the WebMethod annotation to specify explicitly those public methods that are to be exposed. If a WebMethod annotation is present, only the methods to which it is applied are exposed.

With:

6. If the implementation bean does not implement a service endpoint interface and there are no @WebMethod annotations in the implementation bean (excluding @WebMethod annotations used to exclude inherited @WebMethods), all public methods other than those inherited from java.lang.Object will be exposed as Web Service operations, subject to the inheritance rules specified in Common Annotations for the Java Platform [12], section 2.1.

Section 3.2 - Service Endpoint Interface

Replace:

- All of the methods on the service endpoint interface are mapped to WSDL operations, regardless of whether they include a @WebMethod annotation.

With:

- All of the methods on the service endpoint interface are mapped to WSDL operations (including methods inherited from super-interfaces), regardless of whether they include a @WebMethod annotation.

Section 9 - References

Add:

12. Common Annotations for the Java Platform
http://www.jcp.org/en/jsr/detail?id=250
 
18Change default of @WebResult.name to @WebMethod.operationName + "Response" for Doc/lit/bare operations. Section 4.5.1 - Description

Replace:

"return"

With:

If the operation is document style and the parameter style is BARE, @WebParam.operationName+"Response"

Otherwise, "return"

Section 4.5.2 - Annotation Type Definition

Replace:

String name() default "return";

With:

String name() default "";
 
19Clarify the usage of @webService.targetNamespace Section 3.1

Replace:

In this case, the service implementation bean MUST NOT include any JSR-181 annotations other than @WebService(endpointInterface and serviceName attributes only) and @HandlerChain.

With:

In this case, the service implementation bean MUST NOT include any JSR-181 annotations other than @WebService and @HandlerChain. In addition, the @WebService annotation MUST NOT include the name annotation element.

Section 4.1.1 - Description

Replace:

The XML namespace used for the WSDL and XML elements generated from this Web Service.

With:

If the @WebService.targetNamespace annotation is on a service endpoint interface, the targetNamespace is used for the namespace for the wsdl:portType (and associated XML elements).

If the @WebService.targetNamespace annotation is on a service implementation bean that does NOT reference a service endpoint interface (via the endpointInterface annotation element), the targetNamespace is used for both the wsdl:portType and the wsdl:service (and associated XML elements).

If the @WebService.targetNamespace annotation is on a service implementation bean that does reference a service endpoint interface (via the endpointInterface annotation element), the targetNamespace is used for only the wsdl:service (and associated XML elements).
 
20WebParam - The spec now states that OUT and INOUT modes are only used in RPC bindings and parameters marked as headers. Currently JAXRPC will also map doc/lit wrapped sub-elements to OUT, INOUT params. It is possible to use holders in doc/lit bare mode as well. Also, the spec should require that if a parameter is a Holder, that the mode annotation must be present and it should be OUT or INOUT. Section 4.4.1 WebParam.mode

Remove:

OUT and INOUT modes are only supported for RPC bindings or for parameters that map to headers.

Section 4.4.1 WebParam.mode

Add:

Parameters that are Holder Types MUST be OUT or INOUT.

Section 4.4.1 WebParam.mode

Replace:

IN

With:

IN (if not a Holder type)
INOUT (if a Holder type)

Section 6.1.2.1 - Document "Wrapped" Style

Remove:

The return value, if any, is the sole child element of the global element declaration for the output message.
 
21Add a new exclude element to @WebMethod that is used to override inherited @WebMethod annotations. Section 4.2.1 - Description

Add:

exclude Marks a method to NOT be exposed as a web method. Used to stop an inherited method from being exposed as part of this web service.

If this element is specified, other elements MUST NOT be specified for the @WebMethod.

Not allowed on interfaces. false

Section 4.2.2 - Annotation Type Definition

Add:

boolean exclude() default false;
 
22Need to spell out that if an implementation bean references an endpoint interface, it must implement all the methods in the service endpoint interface. Section 3.1 Service Implementation Bean

Replace:

The implementation bean MAY reference a service endpoint interface by using the @WebService.endpointInterface annotation.

With:

The implementation bean MAY reference a service endpoint interface by using the @WebService.endpointInterface annotation. <b>If the implementation bean references a service endpoint interface, it MUST implement all the methods on the service endpoint interface.</b>
 
23Change the @WebParam.name to default to arg0, arg1, etc (based on position in the method signature).

This is to provide support for JAX-WS processing from a class file (when the real parameter names are no longer available) 		Section 4.4.1 - Description

Replace:

Name of the parameter as it appears in the argument list.

With:

If the operation is document style and the parameter style is BARE, @WebMethod.operationName

Otherwise, argN where N represents the index of the parameter in the method signature (starting at arg0).
 
24Add @WebParam.partName and @WebResult.partName to specify part name used in the binding. Section 4.4.1 - Description

Add:

partName The name of the wsdl:part representing this parameter. This is only used if the operation is rpc style or if the operation is document style and the parameter style is BARE. @WebParam.name

Section 4.4.1 - Description

Replace:

Name of the parameter as it appears in the WSDL. For RPC bindings, this is name of the wsdl:part representing the parameter. For document bindings, this is the local name of the XML element representing the parameter.

With:

Name of the parameter.

If the operation is rpc style and @WebParam.partName has not been specified, this is name of the wsdl:part representing the parameter.

If the operation is document style or the parameter maps to a header, this is the local name of the XML element representing the parameter.

Section 4.4.2 - Annotation Type Definition

Add:

String partName() default "";

Section 4.5.1 - Description

Add:

partName The name of the wsdl:part representing this parameter. This is only used if the operation is rpc style or if the operation is document style and the parameter style is BARE. @WebResult.name

Section 4.5.1 - Description

Replace:

Name of return value as it appears in the WSDL and messages on the wire. For RPC bindings, this is the name of the wsdl:part representing the return value. For document bindings, this is the local name of the XML element representing the return value.

With:

Name of return value.

If the operation is rpc style and @WebResult.partName has not been specified, this is the name of the wsdl:part representing the return value.

If the operation is document style or the return value maps to a header, this is the local name of the XML element representing the return value.

Section 4.5.2 - Annotation Type Definition

Add:

String partName() default "";

Section 6.1.1 - RPC Operation Style

Remove:

The names of the parts default to the names of the parameters. If a parameter is annotated with @WebParam.name annotation, this name will be used as the name of the part instead of the parameter name.
 
25The name for headers must be unique with an operation. Section 6.2 - Headers

Add:

This QName must be unique within all headers of the method.
 
26Clean up references to SOAPAction Section 4.2.1 - Description

Replace:

The action for this operation. For SOAP bindings, this determines the value of the SOAPAction header.

With:

The action for this operation. For SOAP bindings, this determines the value of the soap action.
 
29If target namespace is set to "", this should map to the empty namespace, not the web service namespace. Section 4.4.1 - Description

Replace:

targetNamespace The XML namespace for the parameter. The targetNamespace for the Web Service

With:

targetNamespace The XML namespace for the parameter.

Only used if the operation is document style or the paramater maps to a header.

If the target namespace is set to "", this represents the empty namespace.
If the operation is document style and the parameter style is WRAPPED and the parameter does not map to a header, the empty namespace.

Otherwise, the targetNamespace for the Web Service.

Section 4.5.1 - Description

Replace:

targetNamespace The XML namespace for the parameter. The targetNamespace for the Web Service

With:

targetNamespace The XML namespace for the return value.

Only used if the operation is document style or the return value maps to a header.

If the target namespace is set to "", this represents the empty namespace.
If the operation is document style and the parameter style is WRAPPED and the return value does not map to a header, the empty namespace.

Otherwise, the targetNamespace for the Web Service.
.
 
30For the WebService targetNamespace default, this should reference section 3.2 of the JAX-WS spec for the algorithm to calculate a namespace from a Java package. Section 4.1.1 - Description

Replace:

Implementation-defined, as described in JAX-RPC 1.1 [5], section 5.5.2. Typically derived from the package containing the Web Service.

With:

Implementation-defined, as described in JAX-WS 2.0 [5], section 3.2.
 
31For doc/lit bare, we might want to require that any INOUT or OUT parameters must have a WebParam.name specified to avoid name clashes with the input parameter. Section 4.1.1 - Description

Add:

A name MUST be specified if the operation is document style and the parameter style is BARE and the mode is OUT or INOUT.
 
32Add a portName to @WebService for the wsdl:port Section 3.2 - Web Service

Add:

The service endpoint interface MUST NOT include the JSR-181 annotation elements portName, serviceName and endpointInterface of the annotation @WebService.

Section 4.1.1 - Description

Add:

portName Used as the name of the wsdl:port when mapped to WSDL 1.1.
Not allowed on interfaces. @WebService.name +"Port"

Section 4.1.2 - Annotation Type Definition

Add:

String portName() default "";

Section 5.2 - Web Service Class Mapping

Replace:

- The names of the wsdl:port and wsdl:binding sections are not significant and are left implementation-defined.

With:

- The local name of the wsdl:port maps to the value of the @WebService.portName member-value.
- The name wsdl:binding sections is not significant and are left implementation-defined.
 
33Include the updated Handler Schema Section 4.6.1

Replace:

The @HandlerChain annotation associates the Web Service with an externally defined handler chain. This annotation is typically used in scenarios where embedding the handler configuration directly in the Java source is not appropriate; for example, where the handler configuration needs to be shared across multiple Web Services, or where the handler chain consists of handlers for multiple transports.

It is an error to combine this annotation with the @SOAPMessageHandlers annotation.

With:

The @HandlerChain annotation associates the Web Service with an externally defined handler chain (JAX-WS 2.0 [5], Section 9).

Section 4.6.1 - Description

Add:

The @HandlerChain annotation MAY be specified on the type only. The annotation target includes METHOD and FIELD for use by JAX-WS 2.0 [5]. A JSR-181 Processor is REQUIRED to report an error if the @HanderChain annotation is used on a method.

Section 4.6.3 - Examples

Replace:

><handler-config>
<handler-chain>
<handler-chain-name>StandardHandlerChain</handler-chain-name>
<handler>
<handler-name>
com.fabrikam.handlers.LogHandler
</handler-name>
<handler-class>
com.fabrikam.handlers.LogHandler
</handler-class>
<init-param>
<param-name>logCategory</param-name>
<param-value>MyService</param-value>
</init-param>
</handler>
<handler>
<handler-name>
com.fabrikam.handlers.AuthorizationHandler
</handler-name>
<handler-class>
com.fabrikam.handlers.AuthorizationHandler
</handler-class>
<soap-role>SecurityProvider</soap-role>
<soap-header
xmlns:ns2=http://openuri.org/examples/security>
ns2:SecurityHeader
</soap-header>
</handler>
<handler>
<handler-name>
com.fabrikam.handlers.RoutingHandler
</handler-name>
<handler-class>
com.fabrikam.handlers.RoutingHandler
</handler-class>
</handler>
</handler-chain>
</handler-config>

With:

<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<bindings wsdlLocation="http://localhost:8080/jaxrpc-fromwsdl_handler/test?wsdl"
xmlns="http://java.sun.com/xml/ns/jaxws">

<bindings node="ns1:definitions" xmlns:ns1="http://schemas.xmlsoap.org/wsdl/">
<package name="fromwsdl.handler.client"/>
</bindings>

<bindings node="ns1:definitions/ns1:types/xs:schema[@targetNamespace='urn:test:types']"
xmlns:xs="http://www.w3.org/2001/XMLSchema"
xmlns:ns1="http://schemas.xmlsoap.org/wsdl/">
<ns2:schemaBindings xmlns:ns2="http://java.sun.com/xml/ns/jaxb">
<ns2:package name="fromwsdl.handler.client"/>
</ns2:schemaBindings>
</bindings>

<bindings>
<handler-chains xmlns="http://java.sun.com/xml/ns/javaee">
<handler-chain>
<handler>
<handler-class>fromwsdl.handler.common.BaseLogicalHandler</handler-class>
<init-param>
<param-name>handlerName</param-name>
<param-value>client0</param-value>
</init-param>
</handler>
</handler-chain>
<handler-chain>
<port-name-pattern xmlns:ns2="urn:test">ns2:Report*</port-name-pattern>
<handler>
<handler-class>fromwsdl.handler.common.BaseLogicalHandler</handler-class>
<init-param>
<param-name>handlerName</param-name>
<param-value>client2</param-value>
</init-param>
</handler>
</handler-chain>
<handler-chain>
<port-name-pattern xmlns:ns2="urn:test">ns2:ReportServicePort</port-name-pattern>
<handler>
<handler-class>fromwsdl.handler.common.BaseSOAPHandler</handler-class>
<init-param>
<param-name>handlerName</param-name>
<param-value>client6</param-value>
</init-param>
</handler>
</handler-chain>
<handler-chain>
<protocol-bindings>##SOAP11_HTTP</protocol-bindings>
<handler>
<handler-class>fromwsdl.handler.common.BaseSOAPHandler</handler-class>
<init-param>
<param-name>handlerName</param-name>
<param-value>client7</param-value>
</init-param>
<soap-role>http://sun.com/client/role1</soap-role>
<soap-role>http://sun.com/client/role2</soap-role>
</handler>
</handler-chain>
<handler-chain>
<protocol-bindings>##SOAP11_HTTP</protocol-bindings>
<handler>
<handler-class>fromwsdl.handler.common.BaseLogicalHandler</handler-class>
<init-param>
<param-name>handlerName</param-name>
<param-value>client3</param-value>
</init-param>
</handler>
</handler-chain>
</handler-chains>
</bindings>

</bindings>

Appendix B - Handler Chain Configuration File Schema

Replace:

This is the schema for the handler configuration file:

<?xml version="1.0" encoding="UTF-8"?>
<xsd:schema xmlns="http://www.w3.org/2001/XMLSchema"
targetNamespace="http://www.bea.com/xml/ns/jws"
xmlns:jws="http://www.bea.com/xml/ns/jws"
xmlns:j2ee="http://java.sun.com/xml/ns/j2ee"
xmlns:xsd="http://www.w3.org/2001/XMLSchema"
elementFormDefault="qualified"
annotation elementFormDefault="unqualified"
version="1.1">

<xsd:annotation>
<xsd:documentation>
<![CDATA[

This is the schema definition for the handler chain configuration
file used by JSR-181. It relies on the handler definitions that
are part of the standard J2EE deployment descriptors.

]]>
</xsd:documentation>
</xsd:annotation>

<xsd:include schemaLocation="j2ee_1_4.xsd"/>
<xsd:include schemaLocation="j2ee_web_services_1_1.xsd"/>

<xsd:complexType name="handler-chainType">
<xsd:sequence>
<xsd:element name="handler-chain-name"
type="j2ee:string"/>
<xsd:element name="handler"
type="j2ee:port-component_handlerType"
minOccurs="0" maxOccurs="unbounded"/>
</xsd:sequence>
</xsd:complexType>

<xsd:complexType name="handler-configType">
<xsd:sequence>
<xsd:element name="handler-chain"
type="jws:handler-chainType"
minOccurs="1" maxOccurs="unbounded"/>
</xsd:sequence>
</xsd:complexType>

<xsd:element name="handler-config" type="jws:handler-configType"/>
</xsd:schema>

With:

<?xml version="1.0" encoding="UTF-8"?>
<xsd:schema xmlns="http://www.w3.org/2001/XMLSchema"
targetNamespace="http://java.sun.com/xml/ns/javaee"
xmlns:javaee="http://java.sun.com/xml/ns/javaee"
xmlns:xsd="http://www.w3.org/2001/XMLSchema"
elementFormDefault="qualified"
annotation elementFormDefault="unqualified"
version="1.0">

<xsd:include schemaLocation="javaee_5.xsd"/>

<!-- **************************************************** -->

<xsd:element name="handler-chains"
type="javaee:handler-chainsType"/>
<xsd:annotation>
<xsd:documentation>

The handler-chains element is the root element for defining handlerchains.

</xsd:documentation>
</xsd:annotation>
</xsd:element>

<!-- **************************************************** -->

<xsd:complexType name="handler-chainsType">
<xsd:annotation>
<xsd:documentation>

The handler-chains element defines the handlerchains associated with this
service or service endpoint.

</xsd:documentation>
</xsd:annotation>

<xsd:sequence>
<xsd:element name="handler-chain"
type="javaee:handler-chainType"
minOccurs="1" maxOccurs="unbounded"/>
</xsd:sequence>

<xsd:annotation element name="id" type="xsd:ID"/>
</xsd:complexType>

<!-- **************************************************** -->

<xsd:complexType name="handler-chainType">
<xsd:annotation>
<xsd:documentation>

The handler-chain element defines the handlerchain.
Handlerchain can be defined such that the handlers in the
handlerchain operate,all ports of a service, on a specific
port or on a list of protocol-bindings. The choice of elements
service-name-pattern, port-name-pattern and protocol-bindings
are used to specify whether the handlers in handler-chain are
for a service, port or protocol binding. If none of these
choices are specified with the handler-chain element then the
handlers specified in the handler-chain will be applied on
everything.

</xsd:documentation>
</xsd:annotation>

<xsd:sequence>

<xsd:choice minOccurs="0" maxOccurs="1">
<xsd:element name="service-name-pattern"
type="javaee:qname-pattern" />
<xsd:element name="port-name-pattern"
type="javaee:qname-pattern" />
<xsd:element name="protocol-bindings"
type="javaee:protocol-bindingListType"/>
</xsd:choice>

<xsd:element name="handler"
type="javaee:handlerType"
minOccurs="1" maxOccurs="unbounded"/>
</xsd:sequence>

<xsd:annotation element name="id" type="xsd:ID"/>
</xsd:complexType>

<!-- **************************************************** -->

<xsd:simpleType name="protocol-URIAliasType">
<xsd:annotation>
<xsd:documentation>
Defines the type that is used for specifying tokens that
start with ## which are used to alias existing standard
protocol bindings and support aliases for new standard
binding URIs that are introduced in future specifications.

The following tokens alias the standard protocol binding
URIs:

##SOAP11_HTTP = "http://schemas.xmlsoap.org/wsdl/soap/http"
##SOAP12_HTTP = "http://www.w3.org/2003/05/soap/bindings/HTTP/"
##XML_HTTP = "http://www.w3.org/2004/08/wsdl/http"

</xsd:documentation>
</xsd:annotation>
<xsd:restriction base="xsd:token">
<xsd:pattern value="##.+"/>
</xsd:restriction>
</xsd:simpleType>

<!-- **************************************************** -->

<xsd:simpleType name="protocol-bindingListType">
<xsd:annotation>
<xsd:documentation>
Defines the type used for specifying a list of
protocol-bindingType(s). For e.g.

##SOAP11_HTTP ##SOAP12_HTTP ##XML_HTTP

</xsd:documentation>
</xsd:annotation>
<xsd:list itemType="javaee:protocol-bindingType"/>
</xsd:simpleType>

<!-- **************************************************** -->

<xsd:simpleType name="protocol-bindingType">
<xsd:annotation>
<xsd:documentation>
Defines the type used for specifying the URI for the
protocol binding used by the port-component. For
portability one could use one of the following tokens that
alias the standard binding types:

##SOAP11_HTTP
##SOAP12_HTTP
##XML_HTTP

Other specifications could define tokens that start with ##
to alias new standard binding URIs that are introduced.

</xsd:documentation>
</xsd:annotation>
<xsd:union memberTypes="xsd:anyURI javaee:protocol-URIAliasType"/>
</xsd:simpleType>

<!-- **************************************************** -->

<xsd:simpleType name="qname-pattern">
<xsd:annotation>
<xsd:documentation>
This is used to specify the QName pattern in the
annotation element service-name-pattern and port-name-pattern in
the handler-chain element

For example, the various forms acceptable here for
service-name-pattern annotation element in handler-chain element
are :

Exact Name: service-name-pattern="ns1:EchoService"

In this case, handlers specified in this
handler-chain element will apply to all ports with
this exact service name. The namespace prefix must
have been declared in a namespace declaration
annotation element in either the start-tag of the element
where the prefix is used or in an an ancestor
element (i.e. an element in whose content the
prefixed markup occurs)

Pattern : service-name-pattern="ns1:EchoService*"

In this case, handlers specified in this
handler-chain element will apply to all ports whose
Service names are like EchoService1, EchoServiceFoo
etc. The namespace prefix must have been declared in
a namespace declaration annotation element in either the
start-tag of the element where the prefix is used or
in an an ancestor element (i.e. an element in whose
content the prefixed markup occurs)

Wild Card : service-name-pattern="*"

In this case, handlers specified in this handler-chain
element will apply to ports of all service names.

The same can be applied to port-name annotation element in
handler-chain element.

</xsd:documentation>
</xsd:annotation>

<xsd:restriction base="xsd:token">
<xsd:pattern value="\*|([\i-[:]][\c-[:]]*:)?[\i-[:]][\c-[:]]*\*?"/>
</xsd:restriction>

</xsd:simpleType>


<!-- **************************************************** -->

<xsd:complexType name="handlerType">
<xsd:annotation>
<xsd:documentation>

Declares the handler. Handlers can access the
init-param name/value pairs using the HandlerInfo interface.

</xsd:documentation>
</xsd:annotation>
<xsd:sequence>
<xsd:group ref="javaee:descriptionGroup"/>
<xsd:element name="handler-name"
type="javaee:string">
<xsd:annotation>
<xsd:documentation>

Defines the name of the handler.

</xsd:documentation>
</xsd:annotation>
</xsd:element>
<xsd:element name="handler-class"
type="javaee:fully-qualified-classType">
<xsd:annotation>
<xsd:documentation>

Defines a fully qualified class name for the handler implementation.

</xsd:documentation>
</xsd:annotation>
</xsd:element>
<xsd:element name="init-param"
type="javaee:param-valueType"
minOccurs="0" maxOccurs="unbounded"/>

<xsd:element name="soap-role"
type="javaee:string"
minOccurs="0" maxOccurs="unbounded">
<xsd:annotation>
<xsd:documentation>

The soap-role element contains a SOAP actor definition that the
Handler will play as a role.

</xsd:documentation>
</xsd:annotation>
</xsd:element>
</xsd:sequence>
<xsd:annotation element name="id" type="xsd:ID"/>
</xsd:complexType>

</xsd:schema>
 
35Use consistent terminology when referring to document or rpc styles. Section 4.5.1 - Description

Replace:

For RPC bindings where @WebResult.partName has not been specified, this is the name of the wsdl:part representing the return value.

For document bindings, this is the local name of the XML element representing the return value.

With:

If the operation is rpc style and @WebResult.partName has not been specified, this is the name of the wsdl:part representing the return value.

If the operation is document style, this is the local name of the XML element representing the return value.
 
38Add a document/literal example to Using JSR-181 annotation to affect the shape of the WSDL Section 7 - Using JSR-181 annotations to affect the shape of the WSDL

Add:

7.2 Document Literal Style
Below is a complete example of a java source file with annotations followed by the resulting WSDL:

Java source:

import javax.jws.*;
import javax.jws.soap.*;

@WebService(
name="ExampleWebService",
targetNamespace="http://openuri.org/11/2003/ExampleWebService")
@SOAPBinding(style=SOAPBinding.Style.DOCUMENT, use=SOAPBinding.Use.LITERAL)
public class ExampleWebServiceImpl {

@WebMethod(action="urn:login")
@WebResult(name="Token")
public LoginToken login(
@WebParam(name="UserName") String username,
@WebParam(name="Password") String password) {
// ...
}

@WebMethod (action="urn:createCustomer")
@WebResult(name="CustomerId")
public String createCustomer(
@WebParam(name="Customer") Customer customer,
@WebParam(name="Token", header=true) LoginToken token) {
// ...
}

@WebMethod(action="urn:notifyTransfer")
@Oneway
public void notifyTransfer(
@WebParam(name="CustomerId") String customerId,
@WebParam(name="TransferData") TransferDocument transferData,
@WebParam(name="Token", header=true) LoginToken token) {
}
};


Resulting WSDL:

<?xml version='1.0' encoding='UTF-8'?>
<definitions
name="ExampleWebServiceImplServiceDefinitions"
targetNamespace="http://openuri.org/11/2003/ExampleWebService"
xmlns="http://schemas.xmlsoap.org/wsdl/"
xmlns:tns="http://openuri.org/11/2003/ExampleWebService"
xmlns:xs="http://www.w3.org/2001/XMLSchema"
xmlns:soap="http://schemas.xmlsoap.org/wsdl/soap/">

<types>
<xs:schema annotation elementFormDefault="unqualified"
targetNamespace="http://openuri.org/11/2003/ExampleWebService">

<xs:complexType name="LoginToken">
...
</xs:complexType>

<xs:complexType name="Customer">
...
</xs:complexType>

<xs:complexType name="TransferDocument">
...
</xs:complexType>

<xs:element name="Token" type="tns:LoginToken"/>

<xs:element name="createCustomer">
<xs:complexType>
<xs:sequence>
<xs:element name="Customer" type="tns:Customer"/>
</xs:sequence>
</xs:complexType>
</xs:element>

<xs:element name="createCustomerResponse">
<xs:complexType>
<xs:sequence>
<xs:element name="CustomerId" type="xs:string"/>
</xs:sequence>
</xs:complexType>
</xs:element>

<xs:element name="notifyTransfer">
<xs:complexType>
<xs:sequence>
<xs:element name="CustomerId" type="xs:string"/>
<xs:element name="TransferData" type="tns:TransferDocument"/>
</xs:sequence>
</xs:complexType>
</xs:element>

<xs:element name="login">
<xs:complexType>
<xs:sequence>
<xs:element name="UserName" type="xs:string"/>
<xs:element name="Password" type="xs:string"/>
</xs:sequence>
</xs:complexType>
</xs:element>

<xs:element name="loginResponse">
<xs:complexType>
<xs:sequence>
<xs:element name="Token" type="tns:LoginToken"/>
</xs:sequence>
</xs:complexType>
</xs:element>

</xs:schema>
</types>

<message name="createCustomer">
<part element="tns:createCustomer" name="parameters"/>
<part element="tns:Token" name="token"/>
</message>
<message name="createCustomerResponse">
<part element="tns:createCustomerResponse" name="parameters"/>
</message>

<message name="notifyTransfer">
<part element="tns:notifyTransfer" name="parameters"/>
<part element="tns:Token" name="token"/>
</message>

<message name="login">
<part element="tns:login" name="parameters"/>
</message>
<message name="loginResponse">
<part element="tns:loginResponse" name="parameters"/>
</message>

<portType name="ExampleWebService">

<operation name="createCustomer" parameterOrder="parameters token">
<input message="tns:createCustomer"/>
<output message="tns:createCustomerResponse"/>
</operation>

<operation name="notifyTransfer" parameterOrder="token">
<input message="tns:notifyTransfer"/>
</operation>

<operation name="login" parameterOrder="parameters">
<input message="tns:login"/>
<output message="tns:loginResponse"/>
</operation>

</portType>

<binding name="ExampleWebServiceImplServiceSoapBinding" type="tns:ExampleWebService">
<soap:binding style="document" transport="http://schemas.xmlsoap.org/soap/http"/>

<operation name="createCustomer">
<soap:operation soapAction="urn:createCustomer" style="document"/>
<input>
<soap:body parts="parameters" use="literal"/>
<soap:header message="tns:createCustomer" part="token" use="literal"/>
</input>
<output>
<soap:body parts="parameters" use="literal"/>
</output>
</operation>

<operation name="notifyTransfer">
<soap:operation soapAction="urn:notifyTransfer" style="document"/>
<input>
<soap:body parts="parameters" use="literal"/>
<soap:header message="tns:notifyTransfer" part="token" use="literal"/>
</input>
</operation>

<operation name="login">
<soap:operation soapAction="urn:login" style="document"/>
<input>
<soap:body parts="parameters" use="literal"/>
</input>
<output>
<soap:body parts="parameters" use="literal"/>
</output>
</operation>

</binding>

<service name="ExampleWebServiceImplService">
<port binding="tns:ExampleWebServiceImplServiceSoapBinding" name="ExampleWebServiceSoapPort">
<soap:address location="http://localhost:7001/ExampleWebServiceImpl/ExampleWebServiceImpl"/>
</port>
</service>

</definitions>