Hi Everyone,
Stephen - I have been thinking about the aspects of multiple
specifications that you have been previously written about (ie.
Visibility of assertions in a referenced spec). I don't think this
resolves with the aspects of multiple specs that I have been thinking
about (ie. Assertion inclusion: complete, partial, with changed
meaning). At this point, I would suggest that we break section 3.4
into two sub-sections:
3.4 The Case of Multiple Specifications
3.4.1 Specification Visibility
your text
3.4.2 Composition of Assertions
my text.
I am also thinking that there should be some intro text before the two
subsections describing the purpose of having multiple specs. Below is
my draft (containing many of Jack's suggestions).
Please feel free to add suggestions or corrections.
Thanks,
Kevin L
3.4 The Case of Multiple
Specifications
Modularity and succinct description within specifications can be
achieved by leveraging existing specification from other existing
specifications. Spec writers often create "umbrella specifications",
or larger scoped specifications that delegate certain normative
descriptions to other existing "referenced specifications". For proper
specification analysis, the closure of test assertions from an
umbrella specification and all referenced specifications should be
considered.
There are two aspects of analysis of multiple specifications that
can be considered: Specification Visibility (3.4.1) which deals with
how assertions from a referenced specification are
descriibed/considered in the umbrella specification, and Composition
of Assertions (3.4.2) which describes how implementation of the
umbrella spec must be conformant to all or portions of referenced specs.
3.4.1 Specification Visibility
Consider a case where a
specification is the
normative source but it itself refers normatively to a second
specification. Consider firstly the case where the second specification
is treated as a black box; where there is no visibility of any test
assertions covering this second black-box specification. Here there may
be a prerequisite that all test assertions for the black-box
specification be treated as a single Boolean requirement.
In
a second case the specification refers to a second specification for
which the test assertions are given visibility and here the test
assertions of the first specification may refer to test assertions of
the second as explicit prerequisites.
Of
course, any number of normative sources may be involved, some
black-box, others not. Such sources may include specifications but also
sets of schemas, diagrams and other artifacts.
3.4.2 Composition of Assertions
There are three cases to consider describing how assertions from a
referenced specification may be included within an umbrella
specification: wholesale inclusion, conditional or partial inclusion,
and inclusion with some changes.
Wholesale inclusion describes where a predicate in an umbrella
specification describes complete conformance to a referenced
specification.
(Need Widget Specs Example of wholesale inclusion of referenced spec,
below is one I invented)
<<within Umbrella
Specification WidgetSpec 1.0>>
TA id: widget-TA7
Target:
WidgetSpec 1.0
Normative
Source: specification requirement 101, part 12
Predicate:
This specification is conformant to WidgetMobile Small Screen
Specification 1.2.
Prescription
Level: mandatory
<<Interpretation:
This assertion implies that widgets
conformant to the WidgetSpec 1.0 must
be conformant to all behavior specified in the WidgetMobile Small Screen Specification 1.2>>
Conditional or Partial inclusion describes where a predicate in an
umbrella specification describes partial inclusion of a referenced
specification in some way. One such way is if the referenced
specification contains some portion that is optional. The umbrella
spec may have a predicate that
- (a.) requires that the optional portions
be implemented in the umbrella,
- (b.) optional portions are conditionally
required (for example, based on the presence of hardware or some other
such support), or
- (c.) that the optional portions may
remain optional.
(Need Widget specs examples of partial inclusion of a referenced spec,
below is one I invented)
<<within Umbrella
Specification WidgetSpec 1.0>>
TA id: widget-TA7
Target:
WidgetSpec 1.0
Normative
Source: specification requirement 101, part 12
Predicate:
This specification is conformant to WidgetMobile Small Screen
Specification 1.2 for widgets with screen size of 760 x 480 or
less.
Prescription
Level: required (based on presence of hardware), otherwise
optional.
<<Interpretation:
This assertion implies that widgets conformant to the WidgetSpec
1.0 must be conformant to all optional behavior specified in the WidgetMobile Small Screen Specification 1.2
that applies to widgets with a hardware restriction of screen size 760 x 480 or less
>>
'Inclusion, with changes' describes where a predicate in an umbrella
specification describes the inclusion of assertions from a referenced
specification, where there is some restricted set of changes applied to
one or more included assertions. Acceptable changes to assertions may
include: (a) strengthening the prescription level of an assertion (eg.
x MAY do y => x MUST do y), or strengthening the meaning of an
assertion with additional requirements (eg. IF x THEN z => IF (x
AND y) THEN z).
<Need Widget specs examples of
inclusion with changes>
<<within Umbrella Specification
WidgetSpec 1.0>>
TA id: widget-TA7
Target:
WidgetSpec 1.0
Normative
Source: specification requirement 111, part 22
Predicate:
This specification requires that optional portions of the Widget
Wireless Data Specification 3.1+ MUST be implemented.
Prescription
Level: required.
<<Interpretation:
This assertion implies that widgets conformant to the WidgetSpec
1.0 must also be conformant to a subset of optional behavior
specified in the Widget Wireless Data
Specification 3.1+ (that are now
mandatory, ie. MUST be implemented)
>>
Durand, Jacques R. wrote:
Thats useful input. I like the
term "umbrella specification" , but I find "component specification"
could be misleading. Could be narrowly understood as covering a
component of the Umbrella targets. How about "referenced" spec, or
"subsidiary" spec instead?
The three cases need be
presented, even if succinctly.
Some suggestion for a final
proposal:
- be light on examples that are
tight to specific specs (Java, etc) and see if we can abstract these
using the "widget" imaginary spec. Ideally the guideline doc should be
understood also by people outside the software industry...
- concrete recommendations /
best practices would be useful, e.g. showing what are the various ways
to handle these referencing specs:
In case TAs exist for the
component spec:
o by using some blanket
predicate asserting "conformance to component spec" in the prerequisite
element of TAs of the umbrella spec.
o by selectively referencing
appropriate TAs of the component spec in the prerequisite element of
Umbrella TA.
o by selectively referencing a
group of TAs (e.g. related to a conformance profile) of the component
spec in the prerequisite element of Umbrella TA.
Finally, some statements in the
umbrella spec just combine with statements of the component spec on an
equal footing (not using them as prerequisites). That is the case of "binding"
normative statements that specify how to use both specs together, i.e.
there are TAs for stating that the binding is right, and the
NormativeSource element of such a TA is likely to refer to both specs.
Finally, there is the 3rd case below where some
change is made to the original statement. In taht case, it might be
that a new TA has to be written (and used as pre-req again). This
problem is similar to Conformance Clauses that also can change a SHOULD
into a MUST, etc. Note that if the change is just the presription
level, and if the TA is used as prereq, that does not change the
meaning of the pre-req: regardless of the prescription level, the
prerequisite MUST evaluate to True for the umbrella TA to be applicable.
Jacques
Hello Jacques, Everyone,
Sorry for the delay on this. I have had a chance to review these
behaviors of multiple specifications with various spec leads within
Sun.
In this email, I wish to clarify some terminology and behavior, as well
as provide citations for Java Specifications illustrating this behavior.
Terminology
Umbrella Specification
A specification, which aggregates behavior through references to other
(component) specifications.
Component Specification
A specification that is referred to by another specification.
Behaviors
1.) An umbrella specification refers to a component
specification (wholesale, all assertions are directly inherited in the
umbrella)
This happens very typically in Java Umbrella
specs.
Examples:
Java EE 5.0 spec (http://www.jcp.org/aboutJava/communityprocess/final/jsr244/index.html)
Section 2.6 - Specifies inclusion of many component specs:
[HTTP, HTTPS, Java Transaction API, RMI-IIOP, Java IDL, JDBC,
Java Persistence API, Java Message Services, JavaMail, JavaBeans
Activation Framework, JAXP, EE Connector Architecture, Security
Services, Deployment Services, Web Services, Management Services]
Java Technology for Wireless Industry (JTWI) Spec (http://jcp.org/aboutJava/communityprocess/final/jsr185/index.html)
Specifies inclusion of 5 component specs
Mobile Service Architecture (MSA) Spec (http://jcp.org/aboutJava/communityprocess/final/jsr248/index.html)
Specifies inclusion of 18 component specs
2.) An umbrella specification refers to a component specification
(partially/conditionally, some assertions are directly inherited in the
umbrella, others with clarifications (additional requirements))
a.) In Java EE umbrella specifications, the spec may:
i.)Specifying requirement of an optional profile (subset of spec)
b.) in Java ME umbrella specifications, the spec has
i.) optional components that may become required
ii.) optional components that may be conditionally required (based
on hardware availability)
iii.) optional components that may remain purely optional.
Example:
Java EE 5.0 spec (http://www.jcp.org/aboutJava/communityprocess/final/jsr244/index.html)
Section 4.3.2 - specifies mandatory implementation of an optional
part of a component spec:
"This specification requires all Java EE products to support
the javax.transaction.xa.XAResource interface, as specified in the
Connector specification."
3.) An umbrella specification refers to a component
specification with changes (some assertion's meanings are (slightly)
changed within the context of the umbrella)
a.) In Java EE umbrella specifications, clarifications
may be:
i.) Strengthening an Assertion (xxx MAY do yyy
=> xxx MUST do yyy)
b.) in Java ME umbrella specifications, a spec may
specify a component spec
i.) with additional requirements
Example:
Java Technology for Wireless Industry
(JTWI) Spec (http://jcp.org/aboutJava/communityprocess/final/jsr185/index.html),
Section 3.3, the umbrella poses an additional requirement on the
measurement of current time:
"In a compliant device, the method
java.lang.System.currentTimeMillis() must record the elapsed time in
increments not to exceed 40 milliseconds."
These behaviors (observations) can probably be further generalized.
Perhaps Stephen can help us do this. Also, some spec leads here
suggested other possible behaviors linking umbrella specs to a range of
versions of a component spec (I'm starting to look at this now).
Hope this helps. Thanks,
Kevin L
Durand, Jacques R. wrote:
Kevin:
inline
Cheers,
Jacques
Hi Everyone,
Stephen - I had an AI to comment on this section, but it was
delayed while I was recovering.
The placeholder text for this section (3.4) is sufficient, but
terse. I think there are a few main points that mostly need to be
hilited:
1.) (primary) specifications may *reference* (component) specifications
<JD> Maybe its worth relating to some
real-world cases, possibly illustrating different forms of
"referencing". In many cases (such as mentioned by K-TAG) the
composition is of a layering of specs. This is overwhelmingly the case
for "protocols"
(telecom, networking, messaging). In other cases, this is more an
"embedding", i.e. the implementations of two referencing-referenced
specs have a component relationship: an impl of spec A contains a
component that is an implementation of spec B. E.g. a MIME multi-part
message is designed for embedding instances of XML docs, or other doc
type.
In both cases, there are usually some "binding"
requirements specifying how these specs integrate. That means we have
to deal with 3 kinds of normative sources, not two:
- primary TAs (source: primary spec)
- binding TAs (source: binding requirements,
often found in "Appendix N: binding with spec XYZ" )
- "referred" TAs. (source: component or
underlying spec)
2.) References to (component) specifications may be complete
(inheriting all TAs) or partial (inheriting a subset of TAs, possibly
based on a logical condition).
3.) TAs inherited from a component specification may have a different
meaning, based on the context (umbrella) where it is interpreted. This
may lead to modification of the TA, or modification of the
implementation (test) extended from the TA
It would be good to give illustrations of each of these
characteristics. I can conjure up some examples - but our colleagues
in the KTag showed interest in this topic before, - perhaps they might
be able to provide 'real world' examples.
Here are some conjured examples:
1.) (primary) specifications may *reference* (component) specifications
This specification (S#24355Widg) is the
overriding description behavior of Widgets. S#24355Widg
includes specifications of (S#24340WidgEmb) widgets embedded in
real-time devices, (S#24344WidgMob) Mobile widgets, and (S#24346WidgConst)
widgets in constrained computing environments.
<JD> these examples may not be best to
illustrate our topic: Unlike the above cases of layering (where the
test targets are really distinct) or of composition (where test targets
are component of each other - still quite distinct in nature) the
test targets are here subclass of each other. We could make the case
that all these are actually different parts of a same spec. (like the
requirements for medium-size widgets are merely an extension to the
requirements set for widgets.)
However, presented from another angle, the
example you mention may actually be an interesting case of referencing
specs, but the other way around !!! The embedded widget spec is the one
referencing the widget spec, not the other way ! (because an embedded
widget inherits from widget)
So you say:
>S#24355Widg includes specifications
for S#24344WidgMob Mobile widgets
But
we could make the case for the opposite: because a mobile widget is
still always a widget, the requirements for mobile widget include the
requirements for widget that are supposed to apply to all widgets. We
could say the same of "medium-size widgets" which also include
(inherit) all reqs for "widget". I have tried to illustrate this
relationsship in the Target Classes subsection (3.5.1) proposal.
2.) References to
(component) specifications may be complete (inheriting all TAs) or
partial (inheriting a subset of TAs, possibly based on a logical
condition).
S#24355Widg includes specifications for S#24344WidgMob
Mobile widgets, with the exception of behaviors specified for
continuous connection environments.
3.) TAs inherited from a component specification may have a different
meaning, based on the context (umbrella) where it is interpreted. This
may lead to modification of the TA, or modification of the
implementation (test) extended from the TA
TA#45: S#24344WidgMob Mobile widgets specifies that
a phone-number look-up must take 3 seconds
This specification (S#24355Widg) includes specification of S#24344WidgMob.
S#24355Widg may be used on spacecraft, approaching
the speed of light.
Due to non-constant properties of time as a body approaches the speed
of light, TA#45 must be altered to a smaller time boundary
(< 3 seconds) to operate correctly in this environment.
<JD> there has to be a more down-to-earth
example !! :-) My general opinion would be: even if we know there is
some valid point to make in the guideline, if we can't get our hands on
a good non controversial example, then let us not make that point
(unless it is really trivial ) - I'd just wait for a good example in
the next version of the guideline. We won't be criticized for not
covering everything (this is a mere entry-level guideline doc, not a TA
encyclopedia) , but we can be criticized for making statements that
could be misinterpreted or seen as dubious or gratuitous.
[OK - this last example is extremely hypothetical!]
A few other complications from multiple specifications also came to
mind:
4.) TAs that conflict
It is possible that two specification may each contain a similar
TA that conflicts the other. When the specifications stand alone,
these TAs do not pose a problem. However, when the two specifications
are joined in a primary specification, a behavioral conflict arises in
the specification.
This situation would require the primary specification to resolve
the conflict (either by discluding one of the behaviors, or modifying
the meaning of one of the TAs to be compatible with the other.
5.) Modification of TAs ... to a point.
Care must be taken when TAs in a referenced specification are
modified (for inclusion in a primary specification). At some
particular amount of modification, the TA is fundamentally changed from
it's original meaning (in the original specification). At this point,
the author of the primary specification should consider discluding the
inherited TA, and creating a new TA within the context of the primary
specification.
Hope this helps, Regards,
Kevin L
---------------------------------------------------------------------
To unsubscribe from this mail list, you must leave the OASIS TC that
generates this mail. You may a link to this group and all your TCs in
OASIS at: https://www.oasis-open.org/apps/org/workgroup/portal/my_workgroups.php
|