Use of JCP site is subject to the
JCP Terms of Use and the
Oracle Privacy Policy
|
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.
|
PROPOSED CHANGES |
||
Request | Summary | Specification |
1 | Change version to 2.0 | Title page Replace: Version 1.0 With: Version 2.0 |
2 | WebResult - WebParam has a header="true" attribute. WebResult does not have any such attribute. 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 attribute 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. |
3 | A document "bare" style operation can have a void return type and a Holder as a parameter. The Holder of course would have to be INOUT. It could also have 2 parameters one IN and one OUT. | 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. |
7 | SOAPBinding - 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}) |
12 | For 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. |
16 | Add support for JAX-WS. Currenty the spec refers to JAX-RPC 1.1 wrt:
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 |
17 | Update 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 |
18 | Change 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 ""; |
19 | Clarify the usage of @webService.targetNamespace | 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 attribute), 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 attribute), the targetNamespace is used for only the wsdl:service (and associated XML elements). |
20 | WebParam - 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. |
21 | Add 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; |
22 | Need 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> |
23 | Change 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). |
24 | Add @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. |
25 | The 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. |
26 | Clean 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. |
29 | If 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. . |
30 | For 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. |
31 | For 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. |
32 | Add 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. |
33 | Include 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" attributeFormDefault="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" attributeFormDefault="unqualified" version="1.0"> <xsd:include schemaLocation="javaee_5.xsd"/> <!-- **************************************************** --> <xsd:element name="handler-chains" type="javaee:handler-chainsType" minOccurs="0" maxOccurs="1"/> <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:attribute 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:attribute 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 attribute service-name-pattern and port-name-pattern in the handler-chain element For example, the various forms acceptable here for service-name-pattern attribute 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 attribute 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 attribute 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 attribute 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:group ref="javaee:jndiEnvironmentRefsGroup"/> </xsd:sequence> <xsd:attribute name="id" type="xsd:ID"/> </xsd:complexType> </xsd:schema> |
35 | Use 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. |
38 | Add 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 attributeFormDefault="unqualified" targetNamespace="http://openuri.org/11/2003/ExampleWebService"> <xs:complexType name="LoginToken"> ... </xs:complexType> <xs:complexType name="Customer"> ... </xs:complexType> <xs:complexType name="TransferDocument"> ... </xs:complexType> <xs:element name="Token" type="tns:LoginToken"/> <xs:element name="createCustomer"> <xs:complexType> <xs:sequence> <xs:element name="Customer" type="tns:Customer"/> </xs:sequence> </xs:complexType> </xs:element> <xs:element name="createCustomerResponse"> <xs:complexType> <xs:sequence> <xs:element name="CustomerId" type="xs:string"/> </xs:sequence> </xs:complexType> </xs:element> <xs:element name="notifyTransfer"> <xs:complexType> <xs:sequence> <xs:element name="CustomerId" type="xs:string"/> <xs:element name="TransferData" type="tns:TransferDocument"/> </xs:sequence> </xs:complexType> </xs:element> <xs:element name="login"> <xs:complexType> <xs:sequence> <xs:element name="UserName" type="xs:string"/> <xs:element name="Password" type="xs:string"/> </xs:sequence> </xs:complexType> </xs:element> <xs:element name="loginResponse"> <xs:complexType> <xs:sequence> <xs:element name="Token" type="tns:LoginToken"/> </xs:sequence> </xs:complexType> </xs:element> </xs:schema> </types> <message name="createCustomer"> <part element="tns:createCustomer" name="parameters"/> <part element="tns:Token" name="token"/> </message> <message name="createCustomerResponse"> <part element="tns:createCustomerResponse" name="parameters"/> </message> <message name="notifyTransfer"> <part element="tns:notifyTransfer" name="parameters"/> <part element="tns:Token" name="token"/> </message> <message name="login"> <part element="tns:login" name="parameters"/> </message> <message name="loginResponse"> <part element="tns:loginResponse" name="parameters"/> </message> <portType name="ExampleWebService"> <operation name="createCustomer" parameterOrder="parameters token"> <input message="tns:createCustomer"/> <output message="tns:createCustomerResponse"/> </operation> <operation name="notifyTransfer" parameterOrder="token"> <input message="tns:notifyTransfer"/> </operation> <operation name="login" parameterOrder="parameters"> <input message="tns:login"/> <output message="tns:loginResponse"/> </operation> </portType> <binding name="ExampleWebServiceImplServiceSoapBinding" type="tns:ExampleWebService"> <soap:binding style="document" transport="http://schemas.xmlsoap.org/soap/http"/> <operation name="createCustomer"> <soap:operation soapAction="urn:createCustomer" style="document"/> <input> <soap:body parts="parameters" use="literal"/> <soap:header message="tns:createCustomer" part="token" use="literal"/> </input> <output> <soap:body parts="parameters" use="literal"/> </output> </operation> <operation name="notifyTransfer"> <soap:operation soapAction="urn:notifyTransfer" style="document"/> <input> <soap:body parts="parameters" use="literal"/> <soap:header message="tns:notifyTransfer" part="token" use="literal"/> </input> </operation> <operation name="login"> <soap:operation soapAction="urn:login" style="document"/> <input> <soap:body parts="parameters" use="literal"/> </input> <output> <soap:body parts="parameters" use="literal"/> </output> </operation> </binding> <service name="ExampleWebServiceImplService"> <port binding="tns:ExampleWebServiceImplServiceSoapBinding" name="ExampleWebServiceSoapPort"> <soap:address location="http://localhost:7001/ExampleWebServiceImpl/ExampleWebServiceImpl"/> </port> </service> </definitions> |