JAX-WS and JWS spec text merged.

Signed-off-by: Tomas Kraus <tomas.kraus@oracle.com>

spec/src/main/asciidoc/XMLWebServices.adoc

@@ -8,14 +8,15 @@ include::ch03-java_to_wsdl_mapping.adoc[]
 include::ch04-client_apis.adoc[]
 include::ch05-service_apis.adoc[]
 include::ch06-core_apis.adoc[]
-include::ch07-annotations.adoc[]
-include::ch08-customizations.adoc[]
-include::ch09-handler_framwork.adoc[]
-include::ch10-soap_binding.adoc[]
-include::ch11-http_binding.adoc[]
+include::ch07-ws_metadata.adoc[]
+include::ch08-annotations.adoc[]
+include::ch09-customizations.adoc[]
+include::ch10-handler_framwork.adoc[]
+include::ch11-soap_binding.adoc[]
+include::ch12-http_binding.adoc[]
 
 // no index of conformance requirements for now
 // include::appA-conformance_requirements.adoc[]
 include::appB-change_log.adoc[]
-include::appC-bibliography.adoc[]
-
+include::appC-JWS.adoc[]
+include::appD-bibliography.adoc[]

spec/src/main/asciidoc/appC-JWS.adoc

@@ -0,0 +1,213 @@
+//
+// Copyright (c) 2021 Contributors to the Eclipse Foundation
+//
+
+[appendix]
+[[app-jws-metadata]]
+== JWS Metadata
+
+=== JWS Metadata Relationship to Other Standards
+
+Jakarta Web Services Metadata relies on Java standards, Web Services standards, XML standards
+and Internet standards.
+
+Java Language standards: J2SE 5.0 is needed for the JSR-175 defined
+Metadata Facility.
+
+Java runtime and container standards: Jakarta Web Services Metadata does not define a
+container or runtime environment – implementers provide tools to map the
+Java classes to specific runtime environments. The functionality of the
+Jakarta containers is assumed. The features provided by Jakarta XML Web Services 2.3 are
+needed for the Web Services runtime as well as the mapping conventions;
+Java to XML/WSDL and WSDL/XML to Java. An optional mapping to Jakarta Enterprise Web Services
+deployment descriptors is provided in Jakarta Web Services Metadata.
+
+Web Services standards: SOAP 1.1 and WSDL 1.1 are used to describe the
+Web Service and define the XML messages.
+
+XML standards: The XML language and the XML Schema 1.0 are an integral
+part of Jakarta Web Services Metadata.
+
+Internet standards: HTTP and HTTP/S provide basic protocols for Web
+Services.
+
+=== Handler Chain Configuration File Schema
+
+The XML Schema for the handler chain configuration file is described at
+https://jakarta.ee/xml/ns/jakartaee/jakartaee_web_services_metadata_handler_3_0.xsd
+
+=== Non-Normative Examples of Alternate Binding Annotations
+
+This section defines non-normative examples of annotations for bindings
+to non-standard protocols and transports.
+
+==== Annotation Name: HttpGetBinding
+
+===== Description
+
+Non-normative example of an alternate binding – in this case a raw HTTP
+binding as specified in WSDL 1.1 [7] section 4.
+
+[cols=3, options=header]
+|===
+|Member-Value
+|Meaning
+|Default
+
+|location
+|The location of the HTTP GET endpoint. When defined at the class level,
+defines as the base URI for all operations on the service. When defined
+at the method level, defines the URI for a particular operation relative
+to the base URI for the service.
+|Implementation-defined
+|===
+
+===== Annotation Type Definition
+
+[source,java]
+----
+@Target({TYPE, METHOD})
+public @interface HttpGetBinding {
+   String location() default "";
+}
+----
+
+===== Example
+
+[source,java]
+----
+@WebService
+@HttpGetBinding(location="MyWebServices")
+public class MyWebServiceImpl {
+   @WebMethod
+   @HttpGetBinding(location="ExampleOperation")
+   public void myOperation() {
+   }
+};
+----
+
+=== JWS Specification Change Log
+
+Version 3.0
+
+* Changed specification version and license.
+* Changed package name to jakarta.jws.
+* Updated Handler Chain Configuration File Schema in Appendix B to accommodate changed
+namespace.
+
+Version 2.1
+
+* Changed specification version and license information.
+* Updated Handler Chain Configuration File Schema in Appendix B to fix
+errors, add missing elements, and make it valid.
+* Updated Section 3.1 to clarify the explanation of when an SEI is
+implicitly defined by an implementation bean. The revised text refers to
+the appropriate section 3.3 in the Jakarta XML Web Services 2.0 specification for the
+actual SEI rules.
+* Updated the table in Section 4.4.1 describing the default "name" member
+value of the jakarta.jws.WebParam annotation to resolve the issue reported. The
+requirement to specify a name for "document" style, parameter style
+"BARE", and mode "OUT" or "INOUT" is lifted and default rules are
+defined. This change is consistent with section 3.6.2.2 of the Jakarta XML Web Services
+2.0 specification.
+
+Version 2.0
+
+* Added @WebResult.header.
+* A document "bare" style operation can have a void return type and a
+Holder as a parameter. The Holder of course would have to be INOUT. It
+could also have 2 parameters one IN and one OUT.
+* Changed @SOAPBinding to be configurable on a per operation basis rather
+than on the entire interface.
+* Made @HandlerChain.name and @SOAPMessageHandlers deprecated.
+* Added support for Jakarta XML Web Services.
+* Updated section 3.1 Service Implementation Bean, Item 6 to state that
+exposing all public methods if not @WebMethod annotations are declared
+to include consideration of annotation inheritence.
+* Changed default of @WebResult.name to
+@WebMethod.operationName + "Response" for Doc/lit/bare operations.
+* Clarified @WebService.targetNamespace usage
+* Clarified @WebParam.mode usage.
+* Added @WebMethod.exclude.
+* Explicitly stated that if an implementation bean references an endpoint
+interface, it must implement all the methods in the service endpoint
+interface.
+* Changed @WebParam.name to default to arg0, arg1, etc (based on position
+in the method signature).
+* Added @WebParam.partName and @WebResult.partName to specify part name
+used in the binding.
+* Added requirement that the name for headers must be unique with an
+operation.
+* Clairified that a target namespace of "" maps to the empty namespace,
+not the web service namespace.
+* For doc/lit bare, require that any INOUT or OUT parameters must have a
+@WebParam.name specified to avoid name clashes with the input parameter.
+
+
+* Added @WebService.portName for the wsdl:port
+* Updated Handler schema
+* Added document/literal example to Using Jakarta Web Services Metadata annotation to affect the
+shape of the WSDL
+* Included various editorial changes.
+
+Version 0.9.4
+
+* Allowing @HandlerChain and @SOAPMessageHandler on implementation when an
+endpointInterface is used.
+
+Version 0.9.3
+
+* Using RFC 2119 Keyword convention.
+* Added Retention annotation to spec annotation definitions.
+* Fixed various Java and XML syntax errors.
+* Changed Implementation Bean to expose all public method by default.
+* WSDL generation is REQUIRED.
+* Clarified support for Start with WSDL, and Start with WSDL and Java
+development modes as OPTIONAL.
+* Clarified @HandlerChain.file attribute syntax and processing requirements.
+
+Version 0.9.2
+
+* Removed security annotations as these will be defined by JSR-250 –
+Common Annotations.
+
+Version 0.9.1
+
+* Changed default name of @WebResult to be "return" instead of "result".
+* Fixed various Java and XML syntax errors.
+
+=== References
+
+. JSR-175 A Metadata Facility for the Java(TM) Programming Language
+https://jcp.org/en/jsr/detail?id=175
+
+. Jakarta Deployment 1.7
+https://jakarta.ee/specifications/deployment/1.7/
+
+. XML Schema 1.0
+https://www.w3.org/TR/xmlschema-1/
+
+. Jakarta EE 9
+https://jakarta.ee/specifications/platform/9/
+
+. Jakarta XML Web Services 3.0
+https://jakarta.ee/specifications/xml-web-services/3.0/
+
+. Jakarta Enterprise Web Services 2.0
+https://jakarta.ee/specifications/enterprise-ws/2.0/
+
+. Jakarta Annotations 2.0
+https://jakarta.ee/specifications/annotations/2.0/
+
+. Web Services Definition Language (WSDL) 1.1
+https://www.w3.org/TR/wsdl/
+
+. Simple Object Access Protocol (SOAP) 1.1
+https://www.w3.org/TR/2000/NOTE-SOAP-20000508/
+
+. Apache AXIS "JWS" drop-in deployment of Web Services
+
+. BEA WebLogic Workshop "JWS" annotated Java Web Services
+
+. RFC 2119: Keywords for use in RFCs to Indicate Requirement Levels
+https://www.ietf.org/rfc/rfc2119.txt

spec/src/main/asciidoc/ch01-introduction.adoc

@@ -25,6 +25,10 @@ oriented XML Web Services in the Java platform. Jakarta XML RPC<<bib7>> added
 support for the WS-I Basic Profile 1.0<<bib8>> to improve interoperability between
 Jakarta XML RPC implementations and with services implemented using other technologies.
 
+Jakarta Web Services Metadata defines the syntax and semantics of Java Web Service
+(JWS) metadata and default values and implementers are expected to provide tools that map the
+annotated Java classes onto a specific runtime environment.
+
 Jakarta XML Web Services (this specification) is a follow-on to Jakarta XML RPC,
 extending it as described in the following sections.
 
@@ -40,6 +44,28 @@ new versions of the standards it depends on have been released.
 Jakarta XML Web Services relates to these specifications
 and standards as follows:
 
+Jakarta Web Services Metadata::
+
+* Define an annotated Java syntax for programming Web Service
+applications.
+* Provide a simplified model for Web Service development that facilitates
+and accelerates development.
+* Provide a syntax that is amenable to manipulation by tools.
+* Define a standard for to building and deploying Web Services without
+requiring knowledge and implementation of generalized APIs and
+deployment descriptors.
+
+This specification addresses the need to simplify:
+
+* Development of server applications that conform both to basic SOAP and
+WSDL standards.
+* Building Web Services that can be deployed with the core Web Services
+APIs and existing Jakarta EE standards.
+* Separate control of public Web Service message contracts and private
+implementation signatures, because in practice public and private
+formats evolve on different schedules.
+
+
 Jakarta XML Binding::
 Due primarily to scheduling concerns, JAX-RPC 1.0 defined its own data
 binding facilities. With the release of JAXB 1.0 <<bib9>>
@@ -464,6 +490,31 @@ Brian Zotter (BEA Systems) +
 Nicholas L Gallardo (IBM) +
 Alessio Soldano (Red Hat) +
 
+==== JWS Expert Group Members
+The following people have been part of the original JWS Specification
+Expert Group:
+
+Alexander Aptus (Togethersoft Corporation) +
+John Bossons +
+Charles Campbell +
+Shih-Chang Chen (Oracle) +
+Alan Davies (SeeBeyond Technology Corp) +
+Stuart Edmondston (BEA Systems) +
+John Harby +
+RajivMordani (Sun Microsystems) +
+Michael Morton (IBM) +
+Simon Nash (IBM) +
+Mark Pollack +
+Srividya Rajagopalan (Nokia) +
+Krishna Sankar (Cisco Systems) +
+Manfred Schneider (SAP AG) +
+John Schneider (BEA Systems) +
+Kalyan Seshu (Paramati Technologies) +
+Rahul Sharma (Motorola) +
+Michael Shenfield (Research In Motion) +
+Evan Simeone (PalmSource) +
+Brian Zotter (BEA Systems) +
+
 [[acknowledgements]]
 === Acknowledgements
 
@@ -480,3 +531,9 @@ contributions to the 2.2 reference implementation and to the
 specification. JAX-WS TCK team (Arthur Frechette, Alan Frechette) and
 SQE team (Jonathan Benoit) assisted the conformance testing of the 2.2
 specification.
+
+Manoj Cheenath (BEA Systems), Don Ferguson (BEA Systems), Chris Fry (BEA
+Systems), Neal Yin (BEA Systems), Beverley Talbott (BEA Systems), Matt Mihic,
+Jim Trezzo, Doug Kohlert (Sun Microsystems), Jitendra Kotamraju (Sun
+Microsystems), and Rama Pulavarthi (Sun Microsystems) have all provided
+valuable technical input to the JWS specification.