ACTION 186 - top to bottom review of current copy of spec

Looking at the version stamped: 2010/07/09 21:04:59
http://dev.w3.org/cvsweb/~checkout~/2008/ws/soapjms/soapjms.html?content-type=text/html;%20charset=utf-8

This review is broken up into three parts:
 * A note
 * Issues to raise
 * Editorial items

I found quite a number of quite minor issues related to the use of RFC
2119 keywords where we ought to avoid their use.  Where the uses were
clearly intended to be non-normative, I flagged it as an "editorial"
change, for which I'm not planning to raise an issue.  Examples included
sections that are clearly marked as "introduction", or common
(lowercase) usage of "should", and "may".  Otherwise, I identify an
issue, although, in many cases, it will be very simple to resolve.

I will be sending a follow-up email to appropriately address these items.

A Note
======
Section 1.4.1: According to this "It is the intent of the W3C SOAP JMS
Binding Working Group that the SOAP/JMS XML namespace URI will not
change arbitrarily with each subsequent revision of the corresponding
XML Schema documents as the specifications transition through Candidate
Recommendation, Proposed Recommendation and Recommendation status.
However, should the specifications revert to Working Draft status, and a
subsequent revision, published as a WD, CR or PR draft, results in
non-backwardly compatible changes from a previously published WD, CR or
PR draft of the specification, the namespace URI will be changed
accordingly."

According to the above, we should revert to a working draft first,
before doing another CR, since we're changing the URI.  We've
effectively already decided not to do that, but I thought I should point
out the inconsistency.

Issues to raise
===============

Abstract: Needs work.  Currently reads:
"This document specifies how SOAP should bind to a messaging system that
supports the Java Message Service (JMS) [Java Message Service]. Binding
is specified for both SOAP 1.1 [SOAP 1.1] and SOAP 1.2 [SOAP 1.2
Messaging Framework] using the SOAP 1.2 Protocol Binding Framework. " --
uses RFC 2119 keyword, doesn't say anything about WSDL.

Section 2.2: paragraph #2: "If the specified property is present then it
MUST be processed as specified." -- not flagged as an assertion. Also,
possibly spurious, since each property has its own normative statements.

Section 2.2.1: jndiConnectionFactoryName, jndiInitialContextFactory,
jndiURL, jndiContextParameter definition:
"MAY be specified in JMS URI, WSDL, or somewhere else in the
environment" --> This doesn't really work.  Seems like it should just
read "Can be specified in the JMS URI, WSDL, ..."

Section 2.2.1: jndiContextParameter definition:
Includes two "MAY"s and one "MUST", but none are flagged as assertions.
 The "MAY" here seems spurious, and should be replaced with "can"

Section 2.2: soapjms:replyToName definition: "Specifies the name of the
destination to which a response message SHOULD  be sent".  Not flagged
as normative, and I suspect it ought to read "Specifies the name of the
destination to which a response message will be sent."

Section 2.2.2: soapjms:topicReplyToName definition
"name of the topic destination to which a response message SHOULD  be
sent" --> Perhaps ought to read "name of the Topic destination to which
a response message will be sent"
"not relevant and MUST be ignored" --> This is not flagged as an
assertion.  Also, "the replyToName is specified in the URI, WSDL, or
environment, topicReplyToName is not relevant and MUST be ignored." -
MUST is not bolded, and statement is not flagged as an assertion.

Section 2.4: Four "MUST" statements not flagged as normative assertions:
First pair: "Based on the sending node's use of SOAP 1.1, SOAP 1.2, SOAP
Messages with Attachments, and MTOM, the contentType  property MUST be
set as it would be for SOAP/HTTP, and the message body MUST use the
corresponding format. "

Second pair: "For example, if the SOAP payload is formatted as a simple
SOAP envelope, the contentType  property value MUST be specified as
"text/xml" for SOAP 1.1 or "application/soap+xml" for SOAP 1.2. On the
other hand, if the SOAP payload is formatted as a MIME multipart
message, the contentType  property value MUST be specified as
"multipart/related". "

Section 2.4.1: Another MUST statement without an assertion: "Since the
message is already in
text format the "encoding" attribute in the XML header MUST be ignored."

Section 2.5:
First: "An instance of a binding to JMS conforming to this binding
specification MUST support the following message exchange patterns:†"

and shortly following: "In the case of SOAP 1.2 a conforming SOAP-JMS
Binding instance MUST  support the following message exchange patterns:†"

These seem redundant.

Section 2.4, 2.6.1.1, 2.7.1:

Protocol 2027: "The contents of the JMS Message body MUST be the SOAP
payload as a JMS BytesMessage or TextMessage. "

Protocol 2034: "(request-response MEP - requesting node) The message
MUST  be created as a JMS BytesMessage or TextMessage as defined in 2.4
The JMS Message Body."

Protocol 2040: The message MUST be created as a JMS BytesMessage or
TextMessage  as defined in 2.4 The JMS Message Body.†

I conclude that normative statements 2034, 2040 are redundant with 2027.

Section 2.6.1.1:
Description of JMSReplyTo has a "must" that should be replaced.

Section 2.6.1.3:
"If a well formed response message is received a transition to "Success"
is made."  Doesn't say what to do for the other cases ("transition to
fail.").  Suggestion - change this to: "... a transition to "Success" is
made, and otherwise transition to fail."

Section 2.6.2.3, table, description of JMSDeliveryMode.
"this SHOULD be the same as that specified on the request" --> Not
tagged as an assertion.

Section 2.7.2:
There are three "MUST"s, two "SHOULD"s, and one "MAY" that are not
tagged as normative statements.

Section 3.3.2: "the transport attribute MUST be set to the value
http://www.w3.org/2010/soapjms/ . "  --> Not flagged as an assertion.

Section 3.3.5: Normative statement not flagged as such. (A MUST and a
SHOULD.)

Appendix A:
* Some of the references are non-normative, but are not listed as such.
* References to some of the other W3C hosted specs are to the latest
versions, rather than a specific draft.

Editorial items:
================

Section 1.1: First paragraph: "It should also enable customers to
implement their own Web services for part of their infrastructure..."
--> "This will also enable customers...".  Also "It should enable them
to write" --> "This will enable them to write..."

Section 1.1, paragraph #2: "...it should be possible for a client
running..." --> "...it ought to be possible for a client running..."

Section 1.1, paragraph #3: "...details of how such gateways should be
designed..." --> "...details of how such gateways can be designed..."

Section 1.1: First bullet - use of the word "must" --> should be "have to"

Section 1.1: 2nd bullet: "The WSDL binding that may be used to describe
SOAP/JMS" --> "The WSDL binding that describes SOAP/JMS"

Section 1.1: Third bullet, also section 1.6, #1, also section 3.3.5
The spec is currently inconsistent: JMS-URI vs. JMS URI.  The majority
of the uses are of the form "JMS URI", so I changed these three
inconsistent references.

Section 1.2: First bullet - "... but the customer must still use a
single implementation of JMS..." --> "... but the customer still needs
to use a single implementation of JMS..."

Section 1.3: Paragraph #1: "This document specifies how SOAP should
bind..." --> "This document specifies how SOAP binds..."

Section 1.4: Reference to section "Faults" should be a link.

Also, "How these subcodes should be treated is dealt with in the section
"Faults"." --> "The section Faults discusses the treatment of these
subcodes."

Section 1.4.1: last paragraph: "However, should the specifications
revert to Working Draft status..." --> "However, in the event that the
specifications revert to Working Draft status"

Section 2.1: First paragraph:
"... and implicitly the JMS calls that must be made" --> "... and
implicitly the JMS calls that need to be made"

paragraph #2: "...how JMS connections and destinations should be
handled." --> "...how JMS connections and destinations are handled."
Also, "such as priority, soapAction and targetService should be handled
within the SOAP/JMS implementation." --> "such as priority, soapAction
and targetService are handled within the SOAP/JMS implementation."

Section 2.2.1: Definition of jndiURL - apparently missing a space
between "InitialContext" and the word "constructor".

Section 2.2.2: soapjms:priority definition - missing comma in "if
specified MUST" --> "if specified, MUST"

Section 2.2.2.1: "...an example of how a JMS Message Header property MAY
be set" --> "...an example of how a JMS Message Header property can be set"

Section 2.2.3.1: "... an example of how a JMS Message property MAY be
set" --> "... an example of how a JMS Message property can be set".

Section 2.3: " This specification does not mandate how an implementation
should obtain these credentials" --> " This specification does not
mandate how an implementation might obtain these credentials"
Also, "Implementers of this binding should consider how to most
appropriately expose authentication functionality to their users in a
way that meshes smoothly with the models exposed by their environments"
--> "Implementers of this binding are encouraged consider the most
appropriately way to expose authentication functionality to their users
such that it meshes smoothly with the models exposed by their environments"

Section 2.4: "The formatting of the SOAP payload is determined by the
sending SOAP node, and should follow the same pattern as for the
SOAP/HTTP binding" -->
"The sending SOAP noad follows the same pattern as for the SOAP/HTTP
binding when determining the format of the SOAP payload."

Section 2.4.1: "The impact on network consumption should be measured for
particular scenarios and JMS providers" --> "The impact on network
consumption ought to be measured for particular scenarios and JMS providers"

Section 2.6.1.2: "and that Destination is where implementations should
be listening" --> "and that Destination is where implementations need to
listen"

2.6.2.2, 2.7.2: Message Exchange Context should reference the relevant
SOAP 1.2 section http://www.w3.org/TR/soap12-part2/#soapmec

Section 2.7, first bullet:
"A SOAP Node instantiated at the sending JMS interface may take on the
role..." --> "A SOAP Node instantiated at the sending JMS interface
takes on the role..."

Section 3: paragraph #2 begins:

"The associated SOAP Underlying Transport Binding above contains..." -
this is presumably a reference to section #2, but is not captured as a
link.  Also, the name of the section is "SOAP Underlying Protocol Binding"

Section 3.3 (and all subsections), all the examples.

All the examples show a portion of a WSDL file.  For clarity, we should
add a sentence to the second paragraph of section 3.3: "To aid in
focusing on the relevant details, all of the WSDL examples in this
section show only a portion of a WSDL file."

Section 3.3.4, paragraph #1:
"For example, the jndiInitialContextFactory  may be indicated..." -->
"For example, the jndiInitialContextFactory  can be indicated..."

Appendix A:
References not listed alphabetically (URI Scheme for JMS)

Received on Monday, 12 July 2010 19:19:23 UTC