 | Use of Interaction Pattern Names in non-MO specific ways | David S. Berry | Burleigh Scott | david.s.berry@jpl.nasa.gov | 5-3 | 5.4, figure 5-3 |
From: "Submit Message" (figure)
To: "Pass Message" (figure)
From: "Transmit Message" (figure, second occurrence)
To : "Route Message" (figure)
From: "a) The consumer application submits a message to the MAL for transmission to the provider."
To: "a) The consumer application passes a message to the MAL for routing to the provider."
From: "... no special initial messages are defined or sent"
To: "... no special initial messages are defined or routed"
From: "... using the initial message sent by a consumer."
To: "... using the initial message from a consumer."
From: "... cannot require that a particular operation must be invoked..."
To: "... cannot require that a particular operation must be started..."
Justification: "submit" and "transmit" are MAL interaction pattern names. Use of these terms in generic ways should be avoided. This figure is interesting because the operation "Transmit Message" is used twice, once properly (the first) and once generically (the second). | Recommended | |
| Use of Interaction Pattern Names in non-MO specific ways | David S. Berry | Burleigh Scott | david.s.berry@jpl.nasa.gov | 5-2 | 5.3, figure 5-2 | From: "Invoke Operation" (figure)
To: "Start Operation" (figure)
From: "Submit Message" (figure)
To : "Pass Message" (figure)
Justification: "invoke" and "submit" are MAL interaction pattern names. Use of these terms in generic ways should be avoided. | Recommended | |
| Use of Interaction Pattern Names in non-MO specific ways | David S. Berry | Burleigh Scott | david.s.berry@jpl.nasa.gov | 5-1 | 5.2, Figure 5-1 | From: "Invoke Operation" (figure)
To: "Start Operation" (figure)
From: "Submit Message" (figure)
To : "Pass Message" (figure)
From: "f) ... to invoke a MO service... creates and submits..."
To: "f) ... to start a MO service... creates and passes"
From: "g) The MAL implementation submits..."
To: "g) The MAL implementation passes..."
| Recommended | |
| Use of Interaction Pattern Names in non-MO specific ways | David S. Berry | Burleigh Scott | david.s.berry@jpl.nasa.gov | 4-18 | 4.6.2 & Figure 4-14 | From: "Message Reception Sequence" (title)
To: "Inbound Message Sequence" (title)
From: "Receive Message" (figure)
To: "Message arrival" (figure)
From: "Transmit decoding error" (figure)
To: "Return decoding error" (figure)
From: "The basic outline... Transport layer receives a message..."
To: "The basic outline... a message arrives at the Transport layer..."
From: "g) ... and transmits this back to the message source."
To: "g) ... and returns this to the message source."
Justification: "receive" and "transmit" are MAL interaction pattern names; use of the terms in a generic fashion should be avoided.
| Recommended | |
| Use of Interaction Pattern Names in non-MO specific ways | David S. Berry | Burleigh Scott | david.s.berry@jpl.nasa.gov | 4-17 | 4.6.1 | From: "... the Transport layer receives message from the MAL..."
To: "... the MAL transmits the message to the Transport layer..."
From: "a) the MAL submits the message to the Transport layer..."
To: "a) the MAL transmits the message to the Transport layer..."
From: "c) ... then the error is also transmitted..."
To: "c)... then the error is also routed..."
From: "i) ... and transmits the encoded message..."
To: "i) ... and passes the encoded message..." or "i) ... and routes the encoded message..."
From: "k) ... during sending by the Transport it..."
To: "k) ... during routing by the Transport layer..."
Justification: several MAL interaction pattern names are used in this section in generic ways... this usage should be avoided.
| Recommended | |
| Use of Interaction Pattern Names in non-MO specific ways | David S. Berry | Burleigh Scott | david.s.berry@jpl.nasa.gov | 4-16 | 4.6.1 & Figure 4-13 | From: "Message Sending Sequence"
To: "Outbound Message Sequence"
From: "Figure 4-13 shows the message sending sequence..."
To: "Figure 4-13 shows the outbound message sequence..."
From: "Transmit error message to transaction source" (figure)
To: "Pass error message to transaction source" (figure)
From: "Transmit message" (figure)
To: "Pass message" or "Route message" (figure)
Justification: "Send" and "Transmit" are MAL interaction pattern names. Using them in a generic fashion should be avoided. | Recommended | |
| Use of Interaction Pattern Names in non-MO specific ways | David S. Berry | Burleigh Scott | david.s.berry@jpl.nasa.gov | 4-15 | 4.6 | From: "The Transport layer is responsible for taking the abstract message from the MAL and transmitting it to the destination:"
To: "The Transport layer is responsible for taking the abstract message from the MAL and routing it to the destination:"
From: "d) ... the actual transmission..."
To: "d) ... the actual routing... "
From: "NOTE 2 ... to transmit the fragments..."
To : "NOTE 2... to route the fragments..."
Justification: "Transmit" is a MAL interaction pattern name. Use of the name in a generic fashion should be avoided.
| Recommended | |
| Use of Interaction Pattern Names in non-MO specific ways | David S. Berry | Burleigh Scott | david.s.berry@jpl.nasa.gov | 4-14 | 4.5.1 | From: "a) The MAL component submits a message... received or sent by the MAL."
To: "a) The MAL component passes a message... inbound to the MAL or outbound from the MAL."
Alternative:
"a) The MAL component routes a message..."
From: "d) ... sent/received..."
To: "d) ... processed ..."
Justification: the use of MAL interaction pattern names in generic ways should be avoided. | Recommended | |
| Use of Interaction Pattern Names in non-MO specific ways | David S. Berry | Burleigh Scott | david.s.berry@jpl.nasa.gov | 4-14 | 4.5.1 | From: "...regardless of whether a message is being sent or received."
To: "...regardless of whether the message is from consumer=>provider or provider=>consumer." (other similar alternatives exist).
Justification: use of interaction pattern names in generic ways should be avoided. | Recommended | |
| Use of Interaction Pattern Names in non-MO specific ways | David S. Berry | Burleigh Scott | david.s.berry@jpl.nasa.gov | 4-11 | 4.4.2 & Figure 4-9 | This section and figure exhibit the same issue documented in several other RIDs, specifically, use of MAL interaction pattern names in generic ways.
Specifically, the terms "reception", "submit", "sender" should be reviewed for acceptable alternatives. There are a number of possibilities, as documented in several prior RIDs to this effect.
In general, the generic use of terms that have been defined in specialized ways for the MAL should be avoided. | Recommended | |
| Use of Interaction Pattern Names in non-MO specific ways | David S. Berry | Burleigh Scott | david.s.berry@jpl.nasa.gov | 4-9 | 4.4.1 and Figure 4-8 | This section and figure exhibit the same issue documented in several other RIDs, specifically, use of MAL interaction pattern names in generic ways.
Specifically, the terms "sending", "send", "sender", "submit", "receives" should be reviewed for acceptable alternatives. There are a number of possibilities, as documented in several prior RIDs to this effect. | Recommended | |
| Use of Interaction Pattern Names in non-MO specific ways | David S. Berry | Burleigh Scott | david.s.berry@jpl.nasa.gov | 4-7 | 4.3.3 & Figure 4-6 | This section and figure use MAL internaction pattern names in generic ways, which should be avoided.
From: "4.3.3 Message Reception Sequence"
To: "4.3.3 Message Arrival at MO Service Layer"
From: "Figure 4-6 shows the message reception sequence for the MO Service Layer"
To: "Figure 4-6 shows the sequence when a message arrives at the MO Service Layer"
From: "a) The MO Service Layer receives the message from the MAL"
To: "a) A message from the MAL arrives at the MO Service Layer"
From: "g) If no errors... invokes the relevant Application aspect"
To: "g) If no errors... starts the relevant Application asepect"
Justification: "receive", "invoke" are MAL interaction pattern names, therefore using the same terms in a generic fashion should be avoided.
| Recommended | |
| Use of Interaction Pattern Names in non-MO specific ways | David S. Berry | Burleigh Scott | david.s.berry@jpl.nasa.gov | 4-6 | 4.3.2 and Figure 4-5 | This section/figure use several MAL Interaction Pattern names in generic ways, which should be avoided. Specific changes recommended are:
From: "invoke" (both in figure and in text)
To: "start" (both in figure and in text)
From: "sending sequence" (section title, figure)
To: "message sequence down the stack" (section title, figure)
From: "submit" (both in figure and in text)
To: "pass" (both in figure and in text)
From: "in response to a received message" (text)
To: "in response to a message" (text)
From: "failure to send", "sent successfully" (text)
To: "failure to pass", "passed successfully" (text)
From: "received or accepted" (text)
To: "accepted" (text)
From: "further messages received for that operation" (text)
To: "further messages for that operation" (text)
Justification: The terms "invoke", "send", "submit" and "receive" are specific interaction pattern names in the MAL. Generic use of these terms should be avoided.
| Editorial | |
| Use of Interaction Pattern Names in non-MO specific ways | David S. Berry | Burleigh Scott | david.s.berry@jpl.nasa.gov | 4-5 | 4.3.1(b) | From: "It uses the abstract service interface of the MAL to send messages and receive messages."
To: "It uses the abstract service interface of the MAL for input and output of messages."
Justification: Avoids generic use of "send" and "receive", which are the names of MAL interaction patterns. | Recommended | |
| Use of Interaction Pattern Names in non-MO specific ways | David S. Berry | Burleigh Scott | david.s.berry@jpl.nasa.gov | 4-4 | 4.2.3(c) | From: "The MAL first checks that the message may be received using the Access Control component. The rules of the Access Control component are deployment specific; it is a deployment decision as to what must be checked before a message is received."
To: "The MAL first checks the message using the Access Control component. The rules of the Access Control component are deployment specific; it is a deployment decision as to what must be checked before a message is further processed."
Justification: By the time the message gets to the MAL, it has already been "RECEIVE"d in terms of the formal interaction pattern. Use of the term "receive" in this generic sense should be avoided given that the term has a specialized meaning in the MO framework. | Recommended | |
| Use of Interaction Pattern Names in non-MO specific ways | David S. Berry | Burleigh Scott | david.s.berry@jpl.nasa.gov | 4-4 | 4.2.3 | In section 4.2.3 and Figure 4-3, the term "invoke" is used as part of the description of the high-level message sequence up the stack. Furthermore, this section describes the "reception sequence" up the stack.
Confusion could be caused because the term "invoke" and "receive" are names of specific protocol interaction patterns in the Message Abstraction Layer.
The generic use of these terms should be avoided given that they have specialized meanings in the MAL.
Suggestions:
1. Replace "Invoke" with "Start" in this section/figure (e.g., "Start relevant application aspect"
2. Replace "reception sequence" with "message sequence up the stack"
3. Change (a) from "The Transport layer receives a message from another entity (step not shown)" to "A message from another entity arrives at the Transport layer (step not shown)". This is because the term "Receive" is the name of the interaction pattern for passing the message from the transport layer to the MAL.
NOTE that the terms "Check" and "Receive" are also used in this section/figure, and these are also interaction patterns. However, because the actions represented in the section/figure correspond exactly to the corresponding interaction patterns for these terms, there is no risk of confusion. | Recommended | |
| Suggested re-phrasing | David S. Berry | Burleigh Scott | david.s.berry@jpl.nasa.gov | 4-3 | 4.2.2 | From: "High-Level Sending Sequence"
To: "High-Level Message Sequence Down Stack"
Justification: SEND is a specific MAL interaction pattern. In 4.2.2, the phrase "sending sequence" is used several times. Since the word "send" has a special use in the MO/MAL, the use of "send" in its generic sense should be avoided.
Alternative: this could be characterized as C=>P and P=>C, or as C<=>P sending sequence, where C=consumer and P=provider. While a bit more wordy, this also accurately describes the message directionality without overloading the word "send". | Recommended | |
| Use of Interaction Pattern Names in non-MO specific ways | David S. Berry | Burleigh Scott | david.s.berry@jpl.nasa.gov | 4-3 | 4.2.2 and Figure 4-2 | In section 4.2.2 and Figure 4-2, the terms "invoke" and "submit" are used as part of the description of the high-level message sequence down the stack. Furthermore, these sections describe the "sending sequence" down the stack.
Confusion could be caused because the terms "invoke", "submit" and "send" are all names of specific protocol interaction patterns in the Message Abstraction Layer.
The generic use of these terms should be avoided given that they have specialized meanings in the MAL.
Suggestions:
1. Replace "Invoke" with "Start" in this section/figure (e.g., "Start service operation"
2. Replace "Submit" with "Pass" in the figure (e.g., "Pass Message")
NOTE that the terms "Check" and "Transmit" are also used in this section/figure, and these are also interaction patterns. However, because the actions represented in the section/figure correspond exactly to the corresponding interaction patterns for these terms, there is no risk of confusion. | Recommended | |
| Mismatch between text and figure | David S. Berry | Burleigh Scott | david.s.berry@jpl.nasa.gov | 3-19 | 3.8.2.1(e) | From: "... each definition may have zero to n occurrences..."
To: "... each definition may have one to n occurrences..."
Justfication: In figure 3-6 the connection between Definition and Occurrence shows a 1-to-n relationship, not 0-to-n.
Alternative: Change figure 3-6 to show a 0-to-n relationship. | Recommended | |
| Loss of Connection Reporting | David S. Berry | Burleigh Scott | david.s.berry@jpl.nasa.gov | 3-16 | 3.7.5(c) | From: "... send an appropriate standard error code to the application..."
To: "... send an appropriate standard error code to both applications..."
Justification: Since in this scenario a connection between the provider and consumer has been established, both the provider and the consumer should be notified if there is a loss of the connection. | Recommended | |
| Oppositie Definition of "Timely" with respect to SLE | David S. Berry | Burleigh Scott | david.s.berry@jpl.nasa.gov | 3-14 | 3.7.2.1 | There should be some coordination between Cross-Support Services and SM&C with respect to the definition of the term "Timely". In the SLE, the meaning of "timely" is quite a bit different than in SM&C. In the SLE definition, data could be dropped, but in the SM&C definition, data will not be dropped. This opposing definition will likely cause some troubles in the future. | Technical Fact | |
| Apparent Flaw in "Assured" QoS definition | David S. Berry | Burleigh Scott | david.s.berry@jpl.nasa.gov | 3-14 | 3.7.2.1(b) | It is stated that the "Assured" QoS "ensures delivery of messages to its [sic] destination", however, given that the "Queued" QoS builds on "Assured" by providing support for Loose Time Coupling, there is an implication that "Assured" does not support Loose Time Coupling.
This seems to represent a possible flaw in the naming of "Assured" QoS. Based on the defining characteristic "ensured delivery of messages to its destination", I would assume that this would cover Loose Time Coupling.
Since "Assured" does not support Loose Time Coupling, it may be misnamed.
| Recommended | |
| Correspondence of Figure 3-3 and 3.6.4 (a) through 3.6.4 (j) | David S. Berry | Burleigh Scott | david.s.berry@jpl.nasa.gov | 3-10 through 3-11 | 3.6.4 | It is not clear to me that the text in 3.6.4(a) through (j) correctly corresponds to the Figure 3-3. I think the text should be reviewed closely to ensure that correspondence between the text and the diagram. 3.6.4(g) in particular appears to imply a message flow that is not shown in the diagram. There is a diagrammed step analogous to 3.6.4(a) that is not described (e.g., in a 3.6.4(k) that is not currently present). | Recommended | |
| Locus of Authentication should be clarified | David S. Berry | Burleigh Scott | david.s.berry@jpl.nasa.gov | 3-9 | 3.6.3(b) and 3.6.3(c) | Figure 3-2 and the accompanying text implies that authentication is provided by the Consumer/Provider Access Control services. However, 3.6.3(b) implies that the transport layer provides authentication when it is stated that: "Presented to the MAL by the lower Transport layer is a generic message with authenticated consumer credentials". Then 3.6.3(c) states that "... from this point the MAL performs authentication ...
Thus it is not clear whether authentication is provided by the Access Control, the transport layer, or the MAL. | Recommended | |
| Sudden use of "client/server" | David S. Berry | Burleigh Scott | david.s.berry@jpl.nasa.gov | 3-7 | 3.6.1 | The bulk of this book refers to entities as "consumer" and "provider", but in section 3.6 the terms "client" and "server" are introduced. There are only a handful of places where "client" is used, mostly in section 3.6. The term "server" is used in the context of "client/server" only once.
Recommend: continue use of terms "consumer" and "provider" instead of "client" and "server". | Recommended | |
| Unclear paragraph | David S. Berry | Burleigh Scott | david.s.berry@jpl.nasa.gov | 3-6 | 3.5.5.1 | The first two sentences of the paragraph imply that the URI must contain domain, session and network zone information, however, the third sentence then states "The URI address itself is not required to contain any reference to the domain, session and network zone, ...". On the surface, the third sentence seems to be a contradiction of the first two sentences. If the intent of sentence 3 could be clarified further that would probably be beneficial. | Recommended | |
| Definition of "Network Zone" | David S. Berry | Burleigh Scott | david.s.berry@jpl.nasa.gov | 3-6 | 3.5.4 | The term "network zone" should be defined "In the context of MO...", just as was the term "session" in paragraph 3.5.2 .
Justification: (a) the term is a common term being used in a specific fashion (perhaps this is less true with the term "network zone" than with the term "domain", but (b) still applies), (b) symmetry with paragraph 3.5.2. | Recommended | |
| Definition of "Domain" | David S. Berry | Burleigh Scott | david.s.berry@jpl.nasa.gov | 3-5 | 3.5.3 | The term "domain" should be defined "In the context of MO...", just as was the term "session" in the preceding paragraph.
Justification: (a) the term is a common term being used in a specific fashion, (b) symmetry with paragraph 3.5.2. | Recommended | |
| Paragraph Order | David S. Berry | Burleigh Scott | david.s.berry@jpl.nasa.gov | 3-5 | 3.5.2.5 | Suggest moving the paragraph currently numbered 3.5.2.5 to just after the paragraph numbered 3.5.2.1 .
Justification: The paragraph currently numbered 3.5.2.5 defines the term "session", which has already been used in 3.5.2.2, 3.5.2.3, and 3.5.2.4 without formal definition. The definition should precede these several usages. | Recommended | |
| Redundancy | David S. Berry | Burleigh Scott | david.s.berry@jpl.nasa.gov | 3-1 | 3.2(c) | From: "onboard-to-onboard" and "space-to-space"
To: "space-to-space"
Alternative: "onboard-to-onboard"
Justfication: the phrase as written seems redundant; it is not clear how "onboard-to-onboard" differs from "space-to-space". Pick one. | Editorial | |
| Word Choice | David S. Berry | Burleigh Scott | david.s.berry@jpl.nasa.gov | 2-7 | 2.6, last sub-paragraph | From: "... a bespoke transport/encoding..."
To: "... a customized transport/encoding ..."
Justification: the word "bespoke" is not part of common technical vocabulary. My guess is that nearly everyone who reads this book will have to look up the word in a dictionary, as I did. | Editorial | |
| Section number error | David S. Berry | Burleigh Scott | david.s.berry@jpl.nasa.gov | 1-1 | 1.5 | From: "a) Section 0 provides..."
To: "a) Section 1 provides..."
| Editorial | |