 | Periodicity of Update? | David S. Berry | Burleigh Scott | david.s.berry@jpl.nasa.gov | 3-43 | 3.5.5.8.1.2 | The semantics of the PROGRESS interaction pattern do not appear to indicate the periodicity of the UPDATE messages... it seems that this could be an important element of the PROGRESS semantics.
NOTE: This may not be the applicable section against which to enter this RID, but I was not able to determine what would be the best placement. | Recommended | |
| Process Description Clarification | David S. Berry | Burleigh Scott | david.s.berry@jpl.nasa.gov | 3-38 to 3-39 | 3.5.5.4 | From: a) The first is when the acknowledgement is replaced with an error message (see 4.4.6) shown in the first sequence above.
To: a) The first is when the acknowledgement is replaced with an error message (see 4.4.6) shown in the 'PROGRESS Ack Fail' sequence above.
From: b) The second is when an error is generated during the processing of the body of the operation but after the initial acknowledgement is sent as shown in the second sequence above.
To: b) The second is when an error is generated during the processing of the body of the operation but after the initial acknowledgement is sent as shown in 'PROGRESS Update Fail' sequence above.
From: c) The third is when an error is generated after the updates but before the final response as shown in the third sequence above.
To: c) The third is when an error is generated after the updates but before the final response as shown in the 'PROGRESS Response Fail' sequence above.
Justification: Since the sequences are named, the names should be used instead of the terms 'first', 'second' and 'third'.
| Recommended | |
| Missing helpful section reference | David S. Berry | Burleigh Scott | david.s.berry@jpl.nasa.gov | 3-14 (first instance, 10 others in document) | 3.5.2.8.3.5 (10 others in document) | From: "The contents of the StandardError structure shall immediately follow the above message
header."
To: "The contents of the StandardError structure (see 4.4.6) shall immediately follow the above message
header."
Justification: The terminology "StandardError structure" is not explained until section 4.4.6, but the "From" phrase is used 11 times in the document. | Recommended | |
| More Comments on "Effect on Reception" | David S. Berry | Burleigh Scott | david.s.berry@jpl.nasa.gov | 3-29 | 3.5.4.8.1.4 | Here are some additional comments on "Effect on Reception", in this case, with respect to the INVOKE interaction pattern (similar remarks likely apply to other "Effect on Reception" descriptions, as well as other process descriptions in the document). I continue to feel that there are missing steps in the interaction patterns.
I'm not exactly sure what the "To" text in this section should be, however, it does seem that the intended process is something like this:
a) consumer generates 'INVOKE Request'
b) consumer-side access control interface checks the 'INVOKE Request'
c) consumer MAL transmits an 'INVOKE Message' to the provider MAL and enters the Initiated State.
d) on reception of the 'INVOKE Message', the Provider MAL generates an 'INVOKE Indication' addressed to the provider (it is not clear to me whether or not the provider-side access control interface gets involved here prior to generating the 'INVOKE Indication' or not... but it seems likely that it SHOULD be... more likely here on the receiving side than on the sending side in my opinion).
e) the provider MAL enters the Initiated State.
f) the provider then starts processing the operation
Justification: the current wording of the process, which states that "On reception of an INVOKE Indication by the provider, a (sic) the provider MAL shall enter the Initiated State" raises the question as to what entity generated the INVOKE Indication; it seems logical that the entity that generates this would be the provider MAL. As written, the text implies that the consumer MAL sends the INVOKE Message direct to the provider and the provider communicates with the provider MAL and directs it to enter the Initiated state. This is what the current text implies to me, but I don't think that is the intent of the interaction pattern. | Recommended | |
| Missing Interaction Pattern Steps (?) in "Effect on Reception" | David S. Berry | Burleigh Scott | david.s.berry@jpl.nasa.gov | 3-5 | 3.5.1.8.1.4 | I thought of entering this RID after reading through page 3-29, and having some trouble understanding the interaction patterns. I then went back to this first interaction pattern, and see that the facets of the process that trouble me are present here too... thus by extension probably throughout the document. I thus recommend that all of the "Effect on Reception" processes be reviewed with this RID in mind, i.e., with careful attention to the apparently distinct roles of the consumer, consumer MAL, provider MAL, and consumer MAL. The process as written in this case seems to imply direct communication between the consumer MAL and the provider, when I don't think this is the case (unless I totally misunderstand the purpose of the MAL).
From: a) Reception of a SEND Request shall, once checked via the Access Control interface, cause the consumer MAL to initiate a SEND IP by transmitting a SEND Message to the provider.
To: a) Reception of a SEND Request shall, once checked via the Access Control interface, cause the consumer MAL to initiate a SEND IP by transmitting a SEND Message to the provider MAL.
From: c) On reception of a SEND Indication a provider shall process the operation.
d) The pattern shall end at this point for the provider.
To: c) On reception of a SEND Message, the provider MAL generate a "SEND Indication" and transmit it to the provider.
d) On reception of a SEND Indication a provider shall process the operation.
e) The pattern shall end at this point for the provider. | Recommended | |
| Process Description Clarification | David S. Berry | Burleigh Scott | david.s.berry@jpl.nasa.gov | 3-25 | 3.5.4.4 | From: It is expected that the first case would be used to report an error with the invoke request and the second to report an error that occurs during processing.
To: It is expected that the 'INVOKE Fail' sequence would be used to report an error with the invoke request and the 'INVOKE Response Fail' sequence would be used to report an error that occurs during processing.
Justification: Since the sequences are named, the names should be used instead of the terms 'first' and 'second'.
| Recommended | |
| Process Description Clarification | David S. Berry | Burleigh Scott | david.s.berry@jpl.nasa.gov | 3-25 | 3.5.4.4 | From: The provider may return an error message (see 4.4.6) in replacement of the ACK message, shown in the first sequence above.
To: The provider may return an error message (see 4.4.6) in replacement of the ACK message, shown in the 'INVOKE Fail' sequence above.
Justification: Clarifies the exact name of the sequence. | Recommended | |
| Suggested diagram | David S. Berry | Burleigh Scott | david.s.berry@jpl.nasa.gov | N/A | N/A | Diagrams such as Figure 3-1 purport to show the flow associated with an interaction pattern, but the text seems to imply a more layered structure that does not seem to be diagrammed anywhere. This RID suggests a diagram that shows more detail of the implied flow.
There are a number of places in the text that refer to the "consumer" and "provider". There is also substantial usage of the phrases "consumer MAL" and "provider MAL", implying that these MALs are distinct aspects of the consumer and provider. There also appear to be implied calls to the Access Control Interface between the consumer and consumer MAL (and symmetrically for the provider) given that each request or indication seems to require checking by the Access Control Interface. This suggests a potential diagram that shows a flow:
C <=> CACI <=> CMAL <=> PMAL <=> PACI <=> P
where C = consumer, CACI = consumer-side access control interface, CMAL = consumer MAL, PMAL = provider MAL, PACI = provider-side access control interface, P = provider.
In such a diagram, the distinct nature of the consumer and consumer MAL (symmetrical for the provider) would be clearly delineated. | Recommended | |
| Recommend adding acronym | David S. Berry | Burleigh Scott | david.s.berry@jpl.nasa.gov | 3-5 | 3.5.1.8.1.3 | From: "...the Access Control interface..."
To: "...the Access Control interface (ACI)...". The ACI acronym should also be added to Annex A (Acronyms).
Justification: The phrase "Access Control interace" is used 83 times in the body of the document, but no acronym is defined. This could be useful. | Recommended | |
| Awkward Process Definition for "When Generated" | David S. Berry | Burleigh Scott | david.s.berry@jpl.nasa.gov | 3-5 | 3.5.1.8.1.3 | From: "b) A SEND Indication shall be generated by the provider MAL upon reception of a SEND Message, once checked via the Access Control interface, from a consumer."
To: "b) Access Control Interface checks validity of the SEND Message."
"c) A SEND Indication shall be generated by the provider MAL upon reception of a SEND Message from a consumer."
Alternative:
To: "b) Once checked via the Access Control interface, a SEND Message received from a consumer shall result in generation of a SEND Indication by the provider MAL."
Justification: The additional detail better describes the actual process. As it is written, step (b) describes 2 steps, but the first of the 2 steps is described after describing the second. There is also a vaguely troubling aspect here in that it seems the Access Control Interface should be described prior to Section 3.5 given that the Access Control Interface check is part of every interaction pattern described in 3.5. So this (a), (b), (c) recommendation could/should apply to all the interaction patterns described in 3.5. It should also be noted that step (c) in the recommendation only occurs in the event of a RESPONSE from the Access Control Interface, but not in the event of an ERROR. If the Access Control Interface is defined prior to section 3.5, this would be a much clearer process description.
In any case, the current wording of (b) is rather awkward. In glancing at other portions of the text it appears that this awkward construction may be widely present in the document. | Recommended | |
| Undefined Acronym | David S. Berry | Burleigh Scott | david.s.berry@jpl.nasa.gov | A-1 | Annex A | The acronym "IP Interaction Pattern" should be added to Annex A. It is used extensively in the document, but is not in the Acronym annex. | Recommended | |
| Undefined Acronym | David S. Berry | Burleigh Scott | david.s.berry@jpl.nasa.gov | 3-4 | 3.5.1.8.1.1 | From: "The SEND Request primitive shall be used by the consumer application to initiate a SEND IP."
To: "The SEND Request primitive shall be used by the consumer application to initiate a SEND Interaction Pattern (IP)."
Justification: The "IP" acronym is not defined in the text.
Alternatively, the "IP" acronym could follow one of several prior uses of the term "interaction pattern". | Editorial | |
| Apparent Incomplete Sentence | David S. Berry | Burleigh Scott | david.s.berry@jpl.nasa.gov | 3-2 | 3.3(b) | From: "It is detailed in, and the pattern shall end at this point."
To: "It is detailed in [applicable section], and the pattern shall end at this point."
Justification: The fragment "It is detailed in..." seems to imply that it was intended to be followed by a section reference. Regardless if this was the intent, the sentence does not appear to make sense as written. | Editorial | |
| Section should be better documented or deleted | David S. Berry | Burleigh Scott | david.s.berry@jpl.nasa.gov | 2-7 | 2.3 | This section describes "Abstract Service Specifications", but this description does not appear to add anything to the book under review. Thus it is either (a) not documented sufficiently, or (b) should be removed. For example, the first sentence mentions abstract service specification Blue Books, which is presumably where one might find instances of the "Service Overview Table". But there are no "Service Overview Tables" in the 521.0-R-2 (i.e., book under review). Similarly, when I read this section, I tried to understand the significance of the fields "Support in replay" and "Capability Set". These concepts are primarily found only in annotations in the XML schema, but not in section 2.3. Granted, these are discussed in the Reference Model, but they appear to not be used in the MAL at all. Finally, the 4th paragraph is quite cryptic, and leads one to the question as to whether or not there is a one-to-one correspondence between Service Identifiers and Service Numbers, and Operation Identifiers and Operation Numbers. None of these concepts is really addressed in the MAL. Hence, the recommendation to either better document or remove this section. | Recommended | |
| Word Order | David Berry | Burleigh Scott | david.s.berry@jpl.nasa.gov | 2-5 | 2.2.8.5 | From: "Usually for a Request is it the transmission..."
To: "Usually for a Request it is the transmission...
Justification: Present word order is indicative of a question, but this is meant to be a statement. | Editorial | |
| Word Choice | David Berry | Burleigh Scott | david.s.berry@jpl.nasa.gov | 2-2 | 2.2.4 | From: "The Error Handling section... in the pattern that..."
To: "The Error Handling section... in the pattern where..."
Justification: better word choice | Editorial | |