W3C home > Mailing lists > Public > public-soap-jms@w3.org > September 2009

NEW ISSUE: WSDL section of spec uses RFC 2119 keywords inappropriately

From: Eric Johnson <eric@tibco.com>
Date: Mon, 28 Sep 2009 18:07:48 -0700
Message-ID: <4AC15DE4.3090909@tibco.com>
To: SOAP-JMS <public-soap-jms@w3.org>
Title: RFC 2119 keywords out of place

Description: Several uses of "may" are sprinkled throughout the
document, but are not intended to be normative.

Specifically
============
Section 1.4:

"Parenthetic remarks about fault subcodes are mentioned throughout the
document where a conformance issue may result in an error."

Should be rewritten as:
"Parenthetic remarks about fault subcodes are mentioned throughout the
document where a conformance issue could result in an error."

Section 1.5:
"The numeric suffixes are assigned sequentially and never reused so
there may be gaps in the sequence."

Should be rewritten as:
"The numeric suffixes are assigned sequentially and never reused so
there could be gaps in the sequence."

Section 2.1:
"Many people may think of the JMS calls as the SOAP/JMS message format."

Should be rewritten as:
"One might think of the JMS calls as the SOAP/JMS message format."

Section 2.2.1:
"..., it is not possible to enumerate all the ways that connection
information may be set."

-->
"..., it is not possible to enumerate all the ways that connection
information can be set."

Section 2.2.3:
"If the value of the property is text/xml or application/soap+xml, a
charset parameter may be present; if the value of the property is
multipart/related, a type parameter may be present."

-->
"If the value of the property is text/xml or application/soap+xml, a
charset parameter might be present; if the value of the property is
multipart/related, a type parameter might be present."

Section 2.3:
"There are at least two places where authentication may need to occur..."

-->
"There are at least two places where authentication might need to occur..."

and:
"Credentials such as usernames and passwords may be required to access
directories and to obtain JMS Connections from ConnectionFactories..."

-->
"Credentials such as usernames and passwords might be required to access
directories and to obtain JMS Connections from ConnectionFactories..."

and:
"...although typically they may be available as API parameters..."

-->
"...although typically they can be available as API parameters..."

Section 2.4.1:
"While the use of TextMessage may be attractive in some scenarios, ..."

-->
"While the use of TextMessage might be attractive in some scenarios, ..."

and
"... using TextMessage may do more than double the memory requirements
to receive a message."

-->
"... using TextMessage might more than double the memory required to
receive a message."

and:
"As significant as the concerns around memory consumption may be,..."

-->
"As significant as the concerns around memory consumption might be, ..."

and:
"A JMS provider might be encoding a TextMessage with UTF-8, and may
further compress such messages."

-->
""A JMS provider might be encoding a TextMessage with UTF-8, and could
further compress such messages."

and:
"With these two techniques, the data transferred via network calls may
end up being no larger than a corresponding BytesMessage
representation, even with attachments."

-->
"With these two techniques, the data transferred via network calls could
end up being no larger than a corresponding BytesMessage
representation, even with attachments."

Section 2.5.1:
"Topics may be used as destinations for SOAP messages over JMS."

-->
"Topics can be used as destinations for SOAP messages over JMS."

Section 2.6.1.1:

(table)
"... the queue may be a temporary queue generated as described in the
JMS specification. "

-->
"... the queue can be a temporary queue generated as described in the
JMS specification. "

Section 2.7:
"For JMS messages sent to a Queue destination this MEP results in a SOAP
message which may be received by zero or one receiver."

-->
"For JMS messages sent to a Queue destination this MEP results in a SOAP
message which will be received by zero or one receiver."

Section 2.7.2:
"Note, however, that in many cases where receipt is unsuccessful,
information identifying the message or its sender may be unreliable, in
which case there may be little if any value in reflecting a
message-specific fault."

-->
"Note, however, that in many cases where receipt is unsuccessful,
information identifying the message or its sender can be unreliable, in
which case there will be little if any value in reflecting a
message-specific fault."

Section 3.4.4:
"Various JMS properties described in the SOAP/JMS binding specification
may be set in three places in the WSDL..."

-->
"Various JMS properties described in the SOAP/JMS binding specification
can be set in three places in the WSDL..."

Section 3.5:
"More generally, each allowed property may be expressed as a WSDL 2.0
extension element,"

-->
"More generally, each allowed property can be expressed as a WSDL 2.0
extension element,"

and:
"As with the WSDL 1.1 binding, you may also set connection properties in
the URI."

-->
"As with the WSDL 1.1 binding, the connection properties can also be set
in the URI."

Section 3.6.1.1:
"For a particular interaction, you may search for a given property on
the Endpoint component, then Service, then Binding, taking whichever
value you find first."

-->
"For a particular interaction, the property might be found on the
Endpoint component, then Service, then Binding, taking whichever value
you find first."
Received on Tuesday, 29 September 2009 01:08:30 GMT

This archive was generated by hypermail 2.2.0+W3C-0.50 : Saturday, 18 December 2010 18:16:21 GMT