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:
From:
Simon Nash <>
To:
OASIS Java <>
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:
>
>
> ------------------------------------------------------------------------
>
> /
> /
>
> /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
