Editorial Rework of CD02 Rev1 to Merge Policy Annotation Material with restof spec

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:  

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+Merge.doc

sca-javacaa-1.1-spec-cd02-rev1+Merge.pdf