Re: [sca-j] [Issue 226] POJO v.1.1 Test Assertions Version 1.0

[Bryan Aupperle <aupperle@us.ibm.com>]

Lots of points and sub-points here.  Comments
in line <bea>
... </bea>

Bryan Aupperle, Ph.D.
STSM, WebSphere Enterprise Platform Software Solution Architect
WW Center of Excellence for Enterprise Systems & Banking Center of
Excellence Application Integration Architect
Master Inventor

Research Triangle Park,  NC 
+1 919-254-7508 (T/L 444-7508)
Internet Address: aupperle@us.ibm.com



From:      
 Anish Karmarkar <Anish.Karmarkar@oracle.com>
To:      
 Patrick Durusau <patrick@durusau.net>
Cc:      
 sca-j-comment@lists.oasis-open.org,
tab@lists.oasis-open.org, OASIS Java <sca-j@lists.oasis-open.org>
Date:      
 12/27/2010 05:26 PM
Subject:    
   [sca-j] [Issue
226] POJO v.1.1 Test Assertions Version 1.0

---

Thanks for your comments.
This is filed as issue JAVA-226 [1] and will be considered by the SCA-J
TC on one of their future calls after the holiday break.

-Anish
--

[1] http://osoa.org/jira/browse/JAVA-226

On 12/23/2010 6:20 PM, Patrick Durusau wrote:
> Greetings,
>
> Some comments on behalf of the TAB.
>
> Citation Format:
>
> Reads:
>
> When referencing this specification the following citation format
should
> be used:
> SCA-POJO-CI-TA-v1.0OASIS Committee Specification Draft 01, SCA POJO
> Component Implementation v1.1 Test Assertions Version 1.0, November
> 2010,
> http://docs.oasis-open.org/opencsa/sca-j/sca-j-pojo-ci-1.1-test-assertions-1.0-csd01.pdf
>
>
> *****
>
> Actually not. That is to say what is given isn't a citation format
but
> the citation for the standard.
>
> Thus:
>
> Citation of this specification:
>
> Shortref: SCA-POJO-CI-TA-v1.0
>
> Name: OASIS Committee Specification Draft 01, SCA POJO Component
> Implementation v1.1 Test Assertions Version 1.0, November 2010
>
> Location:
> http://docs.oasis-open.org/opencsa/sca-j/sca-j-pojo-ci-1.1-test-assertions-1.0-csd01.pdf
>
>
> ****
>
> BTW, did you know the entire name is a hyperlink in the PDF?
>
> ****

<bea> As I remarked
in an earlier e-mail, this was added by TC-admin during the publication
process and seems to be a new part of the template. </bea>

>
> Not to quibble but the format for the test assertions are defined
in
> [TA-Guide]. So, why does 1.1 Example Test Assertion repeat that definition?
>
> BTW, 1.1 should either be cut or re-written.

<bea> I think it
is nice to have a summary of the TA-Guide so that a reader does not have
to go read that document. </bea>

>
> Illustrative issues (not all of them):
>
> Reads: Assertion ID: Is a unique ID for the test assertion.
>
> Should read: Assertion ID: The unique ID of a test assertion.
>
> ***
>

<bea> nit. </bea>

> Reads: Source: The identifier(s) of normative
statement(s) in *the
> specification* ??? which one?
>
> ***
>

<bea> We clearly
identify that in Section 1 (lines 20-21). </bea>

> Reads: "Target: Identifies the target which
is addressed by this
> assertion."
>
> If I knew what that was intended to mean I might be able to help.
> Defining a term using a term is risky business.
>
> BTW, "typically" statement should be in notes if allowed
at all.
>
> artefact -> artifact (yes, I know British spelling and all that.)
>
> ****
>

<bea> These are
the the format definitions (which are in the TA-Guide). </bea>

> Reads: Prerequisites: Defines any prerequisites
for this test assertion.
> The prerequisites may be defined in terms of one or more other test
> assertions that must be true.
>
> Should read: Prerequisites: Defines prerequisites for a test assertion.
>
> Prerequisites may be defined in terms of one or more other test
> assertions that must be true.
>

<bea> nit. </bea>

> Question: Is this a normative "may?"
If so, probably needs to be in a
> separate line and use a style for the line to make it easy to extract
> later on. That is a separate style for must, may, can, etc.
>

<bea> Fair point.
</bea>

> Question: Do you really want to limit prerequisites
to true? What if my
> prerequisite is to fail a test? That is my test assertion results
in
> false, which means some other prerequisite comes into play.
>
> *****
>

<bea> Yes prerequisites
must be true or any test would either not be valid or produce unpredictable
results. </bea>

> Reads: Predicate: The meat of the assertion -
something that should
> evaluate to true or false for the given target.
>
> ???
>
> Sorry, "The meat of the assertion..." doesn't qualify as
standards prose.
>
> Try:
>
> The test defined by an assertion.
>
> All tests, when applied to a target, result in true or false conditions.
>
> (I am not sure what is expected. A result, report, condition, etc.
> change as appropriate)
>

<bea> nit. </bea>

> *****
>
> Reads: Prescription Level: Mandatory (for MUST requirements) or
> Preferred (for SHOULD requirements) or Permitted (for MAY requirements).
>
> Question: Why redefine MUST, SHOULD and MAY?
>
> Suggest: Prescription Level: MUST, SHOULD, MAY
>

<bea> Terminology
from the TA-Guide. </bea>

> ****
>
> Reads: Tags: Zero or more labels that may be attached to this test
> assertion - these tags can be used to group sets of assertions.
>
> Suggest: Tags: Tags: Zero or more labels that may be attached to a
test
> assertion.
>
> Note: Tags can be used to group sets of assertions.
>
> (Well, except that I don't know how the standard defines grouping
or for
> what purpose. Or do you mean some informal search type grouping?)
>

<bea> nit. </bea>

> 1.2 Terminology
>
> as described in IETF RFC 2119 [RFC 2119] -> it is usually written:
>
> as described in [RFC 2119].
>
> 1.3 Normative References:
>
>
> [RFC 2119] S. Bradner. Key words for use in RFCs to Indicate Requirement
> Levels. IETF RFC 2119, March 1997.
>
>
> The IETF says:
>
> RFC2119 Bradner, S., "Key words for use in RFCs to Indicate Requirement
> Levels", BCP 14, RFC 2119, March 1997.
>
> Yes, I know, the template has it as you do. The template is wrong.
See
> the canonical list at: ftp://ftp.rfc-editor.org/in-notes/rfc-ref.txt
>

<bea> We are just
following the template... </bea>

> 2 Test Assertions
>
> General comments:
>
> [JC120001] is not a sufficient reference to something outside this
> document.
>

<bea> We have already
stated that this is a normative statement in the spec. </bea>

> In JC1-TA-2001, lose the "" marks around
Tags (and all that follow).
>

<bea> nit. </bea>

> In JC1-TA-2002 (and following), there is no "SCA
POJO component
> implementation class" defined here or elsewhere.
>
> In Service Component Architecture SCA-J Common Annotations and APIs
> Specification Version 1.1, the term "SCA POJO component implementation
> class" is never defined so far as I can tell. There is reference
to a
> "Java implementation class" but even there, not to define
it.
>

<bea> Not sure if
he meant CAA or POJO CI. The POJO CI spec does discuss Java implementation
classes in many places </bea>

> Just to skip ahead a bit, look at:
>
> JC1-TA-4002
>
> "The SCA Runtime converts the property value into an instance
of the
> property's Java type as defined by the XML to Java mappings in the
JAXB
> specification with XML schema validation enabled."
>
> I can't find the JAXB specification reference in this document.
>
> In the Service Component Architecture document there is a reference
to
> JAX-B but it would be an assumption on my part that they are the same.
>
>

<bea> Fair point.
</bea>

> 3 Service Component Architecture POJO Component
Implementation
> Specification Version 1.1
>
> It isn't clear where the references in the Conformance Statement are
> pointing.
>
> The only likely normative reference is JAVACI but that has an Annex
of
> conformance statements, which is clearly not allowed under the OASIS
rules.
>
>

<bea> ???? The annex
in the spec is a tabular restatement of the statements in the document
body. </bea>

> 4 Conformance - No conformance statements for
Test Assertions?
>
> Or is that the purpose of unknown conformance clause mapping?
>

<bea> The assertions
do not add any normative statements. See my remarks on issue 227. </bea>

> Hope everyone is having a great holiday season!
>
> Patrick
>

---------------------------------------------------------------------
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