Re: [sca-j] Editorial Rework of CD02 Rev1 to Merge Policy AnnotationMaterial with rest of spec

[Simon Nash <oasis@cjnash.com>]

Comments inline.

   Simon

Mike Edwards wrote:
> 
> Simon,
> 
> Thanks for a stellar turnaround.
> 
> Comments inline.
> 
> *Updated version:*
> 
> 
> 
> 
> Yours,  Mike.
> 
> Strategist - Emerging Technologies, SCA & SDO.
> Co Chair OASIS SCA Assembly TC.
> IBM Hursley Park, Mail Point 146, Winchester, SO21 2JN, Great Britain.
> Phone & FAX: +44-1962-818014    Mobile: +44-7802-467431  
> Email:  mike_edwards@uk.ibm.com
> 
> 
> From: 	Simon Nash <oasis@cjnash.com>
> To: 	OASIS Java <sca-j@lists.oasis-open.org>
> Date: 	03/02/2009 14:40
> Subject: 	Re: [sca-j] Editorial Rework of CD02 Rev1 to Merge Policy 
> Annotation Material with rest of spec
> 
> 
> ------------------------------------------------------------------------
> 
> 
> 
> Mike,
> Thanks for doing this.  I have a few editorial comments.
> 
> 1. In the first example in section 7.1, the @Requires
>    annotation needs to be imported as well as the @Reference
>    annotation.
> *<Done>*
> 
> 2. In section 7.1, the EBNF style used for @Requires and
>    qualifiedIntent does not conform to the EBNF specification.
>    These should be defined as follows:
> 
>      @Requires( “qualifiedIntent” {, “qualifiedIntent”} )
> 
>      qualifiedIntent ::= QName{.qualifier}
> *<Depends on your favoured form of EBNF.  Do you have a reference to 
> your favoured format?*
> 
> *I used this for guidance:*
> *http://www.cs.man.ac.uk/~pjj/bnf/bnf.html*
> 
> *...and I chose the form "derived from regular expressions" outlined 
> about 3/4 of the way down the*
> *referenced page.  I like it because it is near in form to our 
> pseudoschemas>*
> 
There is an ISO standard ISO/IEC 14977 for EBNF:
   http://www.cl.cam.ac.uk/~mgk25/iso-14977.pdf
See also the Wikipedia article on EBNF:
   http://en.wikipedia.org/wiki/Extended_Backus%E2%80%93Naur_form

This standard form uses curly braces { ... } for zero or more
repetitions and square brackets [ ... ] for an optional item.

I can't find a formal definition of the form you have used.
The links on the page you referenced point to articles about
regular expressions rather than EBNF.  The closest match to
your favoured notation that I found by following these links
was a paper that mentions "Minimal BASIC" which seems to be a
metalanguage that was used for one of the BASIC language
definitions.

I think the { ... } and [ ... ] notations from ISO EBNF
are well known and well understood, and it would be better to
use these instead of than a vaguely defined hybrid of EBNF and
regular expressions.

   Simon

> 
> 3. In section 7.2, the EBNF style used for qualifiers and
>    qualifier does not conform to the EBNF specification.
>    These should be defined as follows:
> 
>    qualifiers ::= “qualifier” {, “qualifier”}
>    qualifier  ::= NCName[.qualifier]
> *<Ditto>*
> 
> 4. In section 8.7, the section title should be "Constants"
>    for consistency with other section titles in chapter 8.
> *<Done>*
> 
> 5. In section 8.7, change "constnat" to "constant".
> *<Done>*
> 
> 6. In section 9.12, the @Intent annotation definition uses
>    the org.osoa.sca.annotation package.  It should be
>    org.osoa.oasisopen.annotation.
> *<Done>*
> 
> 7. In section 9.12, the Java code is in the wrong font.
> *<Done>*
> 
> 8. In section 9.16, change ...atribute of an intent annotation..."
>    to "...attribute of a specific intent annotation..." (as discussed
>    during yesterday's call).  Similarly, change "...used in an intent
>    annotation..." to "...used in a specific intent annotation...".
> *<Done>*
> 
> 9. In section 9.19, change "User can also define specific intents
>    using @Intent annotation..." to "Users can also define specific
>    intent annotations using the @Intent annotation...".
> *<Done>*
> 
>   Simon
> 
> Mike Edwards wrote:
>  >
>  > Folk,
>  >
>  > I've carried out the editorial reworking of CD02 Rev1 to deal with the
>  > fact that the Policy Annotation material from
>  > the (old) Section 10 was not well integrated with the rest of the spec,
>  > as discussed in yesterday's F2F call.
>  >
>  > The reworked version of the spec is attached to this email.
>  >
>  >
>  >
>  >
>  > The changes are all intended to be editorial, so we could simply decide
>  > to accept this version as CD02 Rev2
>  > without the need for a formal issue.  However, if you would prefer,
>  > given the significant reworking of the material,
>  > I will be happy to raise an Issue to cover the changes.
>  >
>  > In the reworking I dealt with the comments that Simon Nash made on Issue
>  > 27, but which mostly had to do with the
>  > pre-existing material and not the new & changed material proposed for
>  > Issue 27:
>  >
>  >
>  > Comments from Simon Nash:
>  >
>  >   1. The definition of @Intent is missing from chapter 8.
>  >
>  > *<Done>*
>  >
>  >  2. Section 8.2 should not define the Constants interface and
>  >     the SCA_PREFIX constant.  These should be defined in a
>  >     separate section.
>  > *<Done>*
>  >
>  >  3. In section 8.19, the description of @Qualifier is hard to
>  >     understand.  It says "The @Qualifier annotation can be applied
>  >     to an attribute as an @Intent annotation to indicate the
>  >     attribute provides qualifiers for the intent."  A clearer
>  >     description would be "The @Qualifier annotation can be
>  >     applied to an attribute of an intent annotation definition
>  >     to indicate the attribute provides qualifiers for the intent.
>  >     The annotation definition containing the @Qualifier annotation
>  >     MUST be annotated with @Intent."
>  > *<Done>*
>  >
>  >  4. The forward references from chapter 8 to chapter 10 make it
>  >     hard to understand the chapter 8 descriptions of these annotations
>  >     without reading chapter 10 first.  Could we move chapter 10 to
>  >     a new position between chapters 6 and 7?
>  > *<Done - Chapter 10 is now Chapter 7>*
>  >
>  >  5. In section 10.1, the example classes should not be declared
>  >     in the package org.oasisopen.sca.annotations.  Instead, they
>  >     should import the @Requires and @Reference annotation
>  >     definitions from that package.
>  > *<Done>*
>  >
>  >  6. The formal syntax for the @Requires annotation is specified as
>  >       @Requires( “qualifiedIntent” | {“qualifiedIntent” [,
>  > “qualifiedIntent”]}
>  >     which would only allow up to two intent strings to be specified.
>  >     I believe this should say
>  >       @Requires( “qualifiedIntent” | {“qualifiedIntent” [,
>  > “qualifiedIntent”]...}
>  > *<Done - I have chosen a different style of EBNF for these expressions
>  > which I hope is clearer*
>  > *- comments welcome>*
>  >
>  >  7. The formal syntax for qualifiedIntent also seems more
>  >     restrictive than it should be.  It is given as
>  >       qualifiedIntent ::= QName | QName.qualifier |
>  > QName.qualifier1.qualifier2
>  >     which would only allow up to two levels of qualification.
>  >     I believe this should say
>  >       qualifiedIntent ::= QName[.qualifier]...
>  > *<Done - as for previous>*
>  >
>  >  8. Similar to comment 6 above, the definition of qualifiers in
>  >     section 10.2 should be
>  >       qualifiers ::= ”qualifier” | {“qualifier” [, “qualifier”]... }
>  >
>  > *<Done - as for previous>*
>  >
>  >  9. In section 10.2, the definition of qualifier is
>  >       qualifier ::= NCName | NCName/qualifier
>  >     which uses "/" as a separator.  This is inconsistent with
>  >     section 10.1, which used "." as a separator.
>  > *<Done - "." now used as separator>*
>  >
>  > 10. In section 10.2.1, the last sentence of the second paragraph
>  >     is misleading.  It says "These String constants are then
>  >     available for use with the @Requires annotation and it should
>  >     also be possible to use one or more of them as parameters to
>  >     the @Intent annotation."  In fact they cannot be used as
>  >     parameters to the @Intent annotation, but they are available
>  >     for use as parameters to the specific intent annotation that
>  >     defines them.
>  > *<Done>*
>  >
>  > 11. Section 10.3 says that intent annotations can be used on a class,
>  >     an interface, a method or a field.  However, the definitions in
>  >     chapter 8 say that these annotations can also be used on a parameter.
>  >     The bulleted list in section 10.3 should include a bullet for
>  >     "constructor parameter".
>  > *<Done>*
>  >
>  > 12. In section 10.3, the second last paragraph says that "If an
>  >     annotation is specified at both the class/interface level and
>  >     the method or field level, then the method or field level
>  >     annotation completely overrides the class level annotation of
>  >     the same type."  In this, the word "type" is not very precise.
>  >     It would be clearer to say "... the same base intent name."
>  >     using the precise terminology of section 10.1.
>  > *<Done>*
>  >
>  > 13. There are a number of problems with Example 2b in section 10.3.1.
>  >     a. The <service> definitions for HelloService and HelloChildService
>  >        should be inside the <component> definitions for
>  >        HelloServiceComponent and HelloChildServiceComponent, not
>  >        free-floating inside the <composite> definition.
>  >     b. The <operation> definitions should not be within <component>
>  >        defintions.  I believe the intention may have been to put them
>  >        within <service> definitions.
>  >     c. <operation> elements within <service> definitions were
>  >        recently removed from the Assembly spec because of a decision
>  >        by the Policy TC.
>  >     d. The contents of the <operation> definitions don't seem
>  >        consistent.  For the operations in HelloService, the <operation>
>  >        elements provide fully explicit definitions of the intents that
>  >        apply to the operations.  However, for the operations in
>  >        HelloChildService, some of the <operation> elements only provide
>  >        partial definitions of the intents that apply.  Specifically,
>  >          "hello" specifies "confidentiality/transport" but does not
>  >             specify "authentication" and "integrity/transport".
>  >          "helloWorld" specifies "authentication" but does not
>  >             specify "integrity/transport" or "confidentiality/message"
>  >
>  > *<The problems here are so extensive as to require the raising of a new
>  > issue >*
>  >
>  > 14. Section 10.4 refers to a component type document associated
>  >     with a Java class.  We no longer have component type documents
>  >     for <implementation.java>.  Should this reference be removed?
>  > *<Done>*
>  >
>  > 15. Section 10.4.  The general rule for intents is not that they
>  >     represent fundamental requirements of an implementation, but
>  >     that they represents restrictions that can't be relaxed.  So
>  >     an intent specified by an implementation could be overriden by
>  >     some other intent that is more restrictive, but not by some
>  >     other intent that is less restrictive.
>  > *<Done> *
>  >
>  > 16. Section 10.5 says that @PolicySets can be used on a class,
>  >     an interface, a method or a field.  However, section 8.17 says
>  >     that this annotation can also be used on a parameter.  The
>  >     bulleted list in section 10.5 should include a bullet for
>  >     "constructor parameter".
>  >
>  > 17. In the example in section 10.6.1, the Java interface declarations
>  >     use dot-qualified names, which isn't correct Java syntax.  Also,
>  >     these names use a "service." prefix which should be changed to
>  >     "services." so that it is consistent with the code following
>  >     these delarations.
>  > *<Done>*
>  >
>  > 18. In section 10.6.2, the PermitAll and DenyAll bullets have some
>  >     added text that is bulleted but shouldn't be.
>  > *<Part of Issue 27 - not changed>*
>  >
>  > 19. In section 10.6.2.1, should the fromUSDollarToCurrency method
>  >     be declared in the AccountService interface?  It currently
>  >     only appears in the implementation class.
>  > *<Left this one - I think there may be larger problems with the sample
>  > that need dealing*
>  > *with under another issue>*
>  >
>  >
>  >
>  > Yours,  Mike.
>  >
>  > Strategist - Emerging Technologies, SCA & SDO.
>  > Co Chair OASIS SCA Assembly TC.
>  > IBM Hursley Park, Mail Point 146, Winchester, SO21 2JN, Great Britain.
>  > Phone & FAX: +44-1962-818014    Mobile: +44-7802-467431  
>  > Email:  mike_edwards@uk.ibm.com
>  >
>  >
>  > ------------------------------------------------------------------------
>  >
>  > /
>  > /
>  >
>  > /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/
>  >
>  >
>  >
>  >
>  >
>  >
>  >
>  > ------------------------------------------------------------------------
>  >
>  > ---------------------------------------------------------------------
>  > 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/
> 
> 
> 
> 
> 
> 
> 
> 
> 
> ------------------------------------------------------------------------
> 
> /
> /
> 
> /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/
> 
> 
> 
> 
> 
> 
> 
> ------------------------------------------------------------------------
> 
> ---------------------------------------------------------------------
> 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