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

Further issues filed based on this email:

On 07/12/2010 12:16 PM, Eric Johnson wrote:
> 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.
> 

[snip]
> 
> Issues to raise
> ===============
> 

[snip]

> 
> 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.

Filed as http://www.w3.org/2002/ws/soapjms/tracker/issues/47

> 
> 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". "

Filed as http://www.w3.org/2002/ws/soapjms/tracker/issues/48

Please look at this one carefully, as it took me a long time to think
through what I thought the right proposal should be - you might disagree
with my proposal.

> 
> 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."
>

Filed as http://www.w3.org/2002/ws/soapjms/tracker/issues/49

> 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.

Filed as: http://www.w3.org/2002/ws/soapjms/tracker/issues/50

> 
> 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.
> 

Filed as: http://www.w3.org/2002/ws/soapjms/tracker/issues/51

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

Filed as: http://www.w3.org/2002/ws/soapjms/tracker/issues/52

> 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."

Filed as: http://www.w3.org/2002/ws/soapjms/tracker/issues/53

> 
> 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.

Filed as: http://www.w3.org/2002/ws/soapjms/tracker/issues/54

Note that my proposal replaces SHOULD --> "ought to".

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

Filed as: http://www.w3.org/2002/ws/soapjms/tracker/issues/55

Note that the above proposal is a dramatic change.

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

Filed as: http://www.w3.org/2002/ws/soapjms/tracker/issues/56

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

Filed as: http://www.w3.org/2002/ws/soapjms/tracker/issues/57

> 
> 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.

Filed as: http://www.w3.org/2002/ws/soapjms/tracker/issues/58

Whew!

Done with that.

-Eric.

> 
> 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 Friday, 16 July 2010 19:36:45 UTC