Re: [sca-bindings] Attempt #3 to resolve issues 57, 58, and 59

[Simon Holdsworth <simon_holdsworth@uk.ibm.com>]

Simon,

That's what I referred to originally
as treating acronymns as single letters, so they are always uppercased
or lowercased in their entirety.

The simplication of that that the intent
naming convention uses is that they are just always uppercase.  The
two concerns I have with that are that then you can't simply differentiate
between types and elements by looking at the first character, and that
combinations of acronyms look odd (JNDIURL for example).

Unfortunately the Jms vs JMS is really
down to taste and familiarity, I remember seeing this somewhere in someone's
API in the past and balking at it, these days I'm not so bothered.

I'm starting to wonder if the cost has
exceeded the benefit for this issue - perhaps we should just have a vote
on the two or three options and go with the majority.

Regards, Simon

Simon Holdsworth
STSM, SCA Bindings Architect; Master Inventor; OASIS SCA Bindings TC Chair
MP 211, IBM UK Labs, Hursley Park, Winchester SO21 2JN, UK
Tel +44-1962-815059 (Internal 245059) Fax +44-1962-816898
Internet - Simon_Holdsworth@uk.ibm.com

Simon Nash <oasis@cjnash.com>

05/02/2009 19:54

To	OASIS Bindings <sca-bindings@lists.oasis-open.org>
cc
Subject	Re: [sca-bindings] Attempt #3 to resolve issues 57, 58, and 59

Eric Johnson wrote:
> Based on Simon H's feedback, I've incorporated a few changes.
> 
> Discussion points (deltas from last email):
> 
>     * We seem to agree that "jndiUrl" is the acceptable
form of an
>       attribute name, so I've removed discussion around
that.
 >
It might be too late for me to speak up (again) on this, but
I'll make one last attempt.

My brain does not work like Simon H's by turning acronyms into
words.  At least, if it does so, it does so very selectively,
and on the rare occasions when it does this, the result is
an all-lower-case string and not a camel-case string.  So my
brain feels pretty comfortable with both URI and uri, but when
it sees Uri, it throws a wobbly.

If no-one else feels this way, I'll accept that I am just
strange and concede the point.  But on the small off-chance
that someone else has a brain wired similarly to mine, I'll
propose an alternative convention for dealing with acronyms.

Rule 1: Acronyms are not treated as words.  They are written
         as either all upper-case or all lower-case.
Rule 2: Acronyms at the start of a name can be written as
         either all lower-case or all upper-case.  If
they are
         followed immediately by another acronym, lower-case
         must be used.
Rule 3: Acronyms not at the start of a name are always
         written as all upper-case.

This would lead to the following possible patterns, where
aaa, bbb, ccc are acronyms and www, xxx, yyy are words:

  aaa           e.g. uri
  AAA           e.g. URI
  aaaBBB        e.g. jndiURL
  aaaBBBCCC     Do we have any of these?  Even if we
do, my brain
                would find this
more comfortable than aaaBbbCcc
  aaaWww        e.g. jmsType
  AAAWww        e.g. JMSType
  aaaBBBWww     Do we have any of these?  Even if we
do, my brain
                would find this
more comfortable than aaaBbbWww
  aaaWwwBBBXxx  and so on...

   Simon

>     * Simon expressed concern around the notion of saying
that values of
>       elements and attributes might follow the policy
pattern, instead
>       of the naming of attributes and elements.  That
seems fine to me. 
>       It doesn't actually change how anything is capitalized.
 I've
>       changed the text below.
>     * Simon expressed editorial concern that changing "JMSDeliveryMode"
>       to "deliveryMode", for example, needs
text to map back to the JMS
>       header, so I've added that text.
> 
> The following is the proposed resolution (#3) for issues 57, 58, 59,
> where underlines and strikeouts are used to show deltas from the last
> proposal.
> 
> Each specification (ws, jms, jca) adds a section 1.4 - Naming Conventions.
> 
> The text of that section as follows (between the two line breaks):
> 
> ------------------------------------------------------------------------
> 
> This specification follows some naming conventions for artifacts defined
> by the specification.  In addition to the conventions defined
by section 
> 1.3 of the Assembly [SCA-Assembly] specification, this specification
> adds two additional conventions:
> 
>     * Where the names of elements and attributes consist
partially or
>       wholly of acronyms, those acronyms will be treated
as if they are
>       words, and use the CamelCase conventions outlined
in the Assembly
>       specification.  For example, an attribute
might be named "uri", or
>       "jndiUrl".
>     * For the values of XML Schema elements or_and_ attributes
defined
>       in this specification, the values follow the
same convention as
>       the names of intents in the Assembly specification_attributes_.
>       If the value is of type QName, the local part
of the QName value
>       follows the same convention as _the _names of
intents_attributes_.
> 
> 
> ------------------------------------------------------------------------
> For resolution of http://www.osoa.org/jira/browse/BINDINGS-58, also
> apply the following changes to the binding.jca specification:
> 
> (In document sca-binding-jca-1.1-spec-cd01-rev4.pdf)
> 
> Rename element "jca.outbound.connection" to "outboundConnection",
all 
> occurrences.
> Rename element "jca.inbound.connection" to "inboundConnection",
all 
> occurrences.
> Rename element "jca.outbound.interaction" to "outboundInteraction",
all 
> occurrences.
> Rename element "jca.inbound.interaction" to inboundInteraction",
all 
> occurrences.
> Rename attribute "binding.jca/@jndiURL" to "jndiUrl",
all occurrences.
> The value "ifnotexist" (multiple attributes) should everywhere
be 
> changed to "ifNotExist".
> The values of the "resAuth" element, "Container"
and "Application" 
> should be renamed to "container" and "application".
> 
> ------------------------------------------------------------------------
> For resolution of http://www.osoa.org/jira/browse/BINDINGS-59, also
> apply the following changes to the binding.jms specification:
> 
> (In document sca-binding-jms-1.1-spec-cd01-rev4.pdf)
> 
> Rename attribute "binding.jms/jndiURL" to "jndiUrl"
for all occurrences
> The value "ifnotexist" should everywhere be changed to "ifNotExist".
> The attributes "JMSType", "JMSDeliveryMode", "JMSTimeToLive",
> "JMSPriority", and "JMSSelector" are renamed to
"type", "deliveryMode", 
> "timeToLive", "priority", and "selector",
respectively.
> 
>     _Further, in section 3, line 217 - 218, change "specifies
the value
>     to use for the JMS header property" to "specifies
the value to use
>     for the JMS header property JMSType, JMSDeliveryMode,
JMSTimeToLive,
>     JMSPrioirty, and JMSSelector, respectively."
>     line 252, change " specifies the value to use for
the JMS header
>     property" to "specifies the value to use for
the JMS header property
>     JMSType, JMSDeliveryMode, JMSTimeToLive, and JMSPriority,
respectively"
>     _
> 
> Change "PERSISTENT" value to "persistent"
> Change "NON_PERSISTENT" value to "nonpersistent"
> Change "sca:MessageId" value to "sca:messageId"
> Change "sca:CorrelationID" value to "sca:correlationId"
> Rename jndiURL attribute to "jndiUrl"
> Rename the element "wireformat.jmsdefault" to "wireFormat.jmsDefault"
> 
> 
> The "jms" intent referenced in section 5 of this specification
needs to 
> be capitalized as "JMS" to correspond to the Policy specification.
> 
> ------------------------------------------------------------------------
> For resolution of http://www.osoa.org/jira/browse/BINDINGS-57, also
> apply the following changes to the binding.ws specification:
> 
> Rename the intents (section #4) from "soap", "soap.1_1"
and "soap.1_2" 
> to "SOAP", "SOAP.1_1", and "SOAP.1_2",
respectively.
> 
> ------------------------------------------------------------------------
> 
> Hopefully, this wraps it up.
> 
> -Eric.
> 
> ---------------------------------------------------------------------
To 
> unsubscribe from this mail list, you must leave the OASIS TC that
> generates this mail. Follow this link to all your TCs in OASIS at:
> https://www.oasis-open.org/apps/org/workgroup/portal/my_workgroups.php



---------------------------------------------------------------------
To unsubscribe from this mail list, you must leave the OASIS TC that
generates this mail.  Follow this link to all your TCs in OASIS at:
https://www.oasis-open.org/apps/org/workgroup/portal/my_workgroups.php

---

Unless stated otherwise above:
IBM United Kingdom Limited - Registered in England and Wales with number 741598.
Registered office: PO Box 41, North Harbour, Portsmouth, Hampshire PO6 3AU