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

[Mike Edwards <mike_edwards@uk.ibm.com>]

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>


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

sca-javacaa-1.1-spec-cd02-rev1+Merge2.doc