[Issue 226] POJO v.1.1 Test Assertions Version 1.0

[Anish Karmarkar <Anish.Karmarkar@oracle.com>]

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?
>
> ****
>
> 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.
>
> 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.
>
> ***
>
> Reads: Source: The identifier(s) of normative statement(s) in *the
> specification* ??? which one?
>
> ***
>
> 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.)
>
> ****
>
> 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.
>
> 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.
>
> 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.
>
> *****
>
> 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)
>
> *****
>
> 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
>
> ****
>
> 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?)
>
> 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
>
> 2 Test Assertions
>
> General comments:
>
> [JC120001] is not a sufficient reference to something outside this
> document.
>
> In JC1-TA-2001, lose the "" marks around Tags (and all that follow).
>
> 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.
>
> 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.
>
>
> 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.
>
>
> 4 Conformance - No conformance statements for Test Assertions?
>
> Or is that the purpose of unknown conformance clause mapping?
>
> Hope everyone is having a great holiday season!
>
> Patrick
>