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

[Yang Lei <yanglei@us.ibm.com>]

Here is the latest proposal for Issue 27 ported onto the CD02 Rev1 Merge version. The proposal is pending the comments from Dave and Mike regarding componentType of the implementation policy annotated java implementations.

(See attached file: sca-javacaa-1.1-spec-cd02-rev1+Merge+Issue27.doc)(See attached file: sca-javacaa-1.1-spec-cd02-rev1+Merge+Issue27.pdf)

I saved the document by only turning myself as the reviewer.. However if the word document still shows the change from both Mike and me, please turn off Mike as the reviewer then you can see the changes related to Issue 27.


Thanks.

Regards,

Yang Lei

WebSphere SCA Feature Pack Development -- SCA Architect
Phone: (919) 543 8887 T/L 441-8887
e-mail: yanglei@us.ibm.com

SCA Feature Pack: http://washome.austin.ibm.com/xwiki/bin/view/SCA2Team/WebHome
RTP Technical Vitality: http://swgcomm.bluehost.ibm.com/siteFiles/labs.html?location=SEUS&type=cluster
WebSphere Lab Advocate for Royal Bank of Scotland


Mike Edwards <mike_edwards@uk.ibm.com>

Mike Edwards <mike_edwards@uk.ibm.com>

02/03/2009 08:09 AM

To	"OASIS Java" <sca-j@lists.oasis-open.org>
cc
Subject	[sca-j] Editorial Rework of CD02 Rev1 to Merge Policy Annotation Material with rest of 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: 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

(See attached file: sca-javacaa-1.1-spec-cd02-rev1+Merge.doc)(See attached file: sca-javacaa-1.1-spec-cd02-rev1+Merge.pdf)---------------------------------------------------------------------
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 

sca-javacaa-1.1-spec-cd02-rev1+Merge+Issue27.doc

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

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

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