[Cesg-all] Result of CESG poll closing 12 January 2010

[Thomas Gannett]

CESG E-Poll Identifier:  CESG-P-2010-12-001 
Pre-Red CESG review and approval of CCSDS 
521.2-R-0, Mission Operations Message Abstraction 
Layer—JAVA API (Proposed Red Book)
Results of CESG poll beginning 15 December 2010 and ending 12 January 2010:

                  Abstain:  0 (0%)
  Approve Unconditionally:  1 (25%) (Peccia)
  Approve with Conditions:  3 (75%) (Shames, Barkley, Moury)
  Disapprove with Comment:  0 (0%)

CONDITIONS/COMMENTS:

      Peter Shames (Approve with 
Conditions):  This document contains a number of 
problematic areas.  A few of the more prominent 
ones are indicated in notes embedded in the attached PDF file.

The most significant problem, however, is that 
while the document purports to be a Magenta Book, 
with normative content, and states that it 
follows the expected "shall", "must", "may" 
conventions, it does not, in general, actually do 
so.  The problem is so pervasive that I have not 
attempted to mark the occurrences.

If the indicated issues are fixed prior to 
distribution for a technical review I would be 
inclined to let these other issues go until after 
the document is reviewed by the agencies for 
technical content.  In any case the necessary 
editorial changes will need to be handled prior to final publication.

      Erik Barkley (Approve with 
Conditions):  1)  section 1.3, applicability: I 
would expect, as this is a Java API, some sort of 
statement of applicability with regard to a 
minimal JVM version. If there is no such 
restriction then the applicability statement 
should also indicate this.  It also seems to me 
that there is the potential for different 
versions of the MAL and that this is in fact 
applicable only to what is probably version 1 of 
the MAL.  It seems to me that as this is a 
platform specific binding for a particular 
version of the abstraction layer then this kind 
of applicability needs to be indicated.

2) section 1.4:  the rationale statement is 
laudable but strikes this reviewer more as a 
general set of goals. Minimizing the set of 
concepts is all well and good but does not really 
provide a rationale for why the API specification 
exists. I think the rationale is very simply to 
provide the ability to develop and utilize 
Mal-based services in Java and that is really all 
the rationale that CCSDS needs in producing this 
type of recommendation. Suggest updating the 
rationale statement to at least indicate 
this.   It seems this could be supported with 
more tightly aligned CCSDS goals such as creating 
a guide for promoting interoperability between 
various software packages that implement the API 
and applications using the API.

3) section 1.8:  the statement that this document 
contains no normative references seems 
incorrect.  Presumably this is an API that 
depends upon a MAL Blue Book at some point -- 
isn't reference B3 a CCSDS Blue Book defining 
MAL, normative?  Suggest updating this section. 
Some sort of caution with regard to normative 
references being updated/being subject to 
revision would seem to be in order rather than 
some declaration that no normative references are 
to be found. Also, Java compliance (in section 
2.3) seems like another normative reference (and 
is also related to concerns of proper applicability statements as noted above).

4) Section 2.1:  it seems odd to have a CCSDS 
magenta track publication contain language about 
a proposed set of recommendations. As this is a 
CCSDS recommended practice I would suggest that 
an exact documentation tree be inserted, or if 
this is indeed the MO/SM+C documentation tree 
simply remove the word "proposed".

5) Section 4: There is some inconsistent style 
between this section and section 3 with regard to 
describing what various method redefinitions are 
about. Section 3 provides declarations as to what 
the method redefinitions do. In section 4 Java 
code snippets are used to indicate what the 
method does.  It seems that a simple declaration 
would be good enough.  For example, 4.4.4.11 why 
should the reviewer have to read

"The method ‘toString’ is redefined as follows:
public String toString() {
StringBuffer buf = new StringBuffer();
buf.append(‘(‘);
buf.append(super.toString());
For all fields:
buf.append(",<field name>");
buf.append('=');
buf.append(<field name>);
Finally:
buf.append(')');
return buf.toString();
}"


rather than just simply be told that be told that 
the string returned will formatted with enclosing 
'()' and have embedded equals signs?  Suggest 
using the same style as in section 3, or at least 
offer a rationale as to why code reading is required to understand the API.


Minor: (Does not really need to be 
changed):  Suggest, in section 3.1 onward 
changing the variable name MAL to something like 
MALInstance or MALContext  as the current 
variable definition tends to read as "MAL which 
is provided by  MAL" and is somewhat confusing. 
Granted, software engineers will be able to 
quickly figure this out but to generally promote 
CCSDS recommendations I think it may be of 
benefit to consider a slight renaming.

General:  in general, it seems that the code 
example should be moved to a separate annex so 
that the API can be stated in CCSDS terse style.


General question for CESG:  as this is a Java 
API, perhaps we should consider producing this 
kind of information as JavaDocs?  And perhaps this could be registered in SANA?

      Gilles Moury (Approve with 
Conditions):  Since this document is a magenta 
book and since its intent is to specifiy an API 
in JAVA, all sections from section 3 onward 
should contain prescriptive requirements (apart 
from NOTES and reserved sub-sections for 
explanatory text). For example, methods 
signatures and associated parameters should be 
prescriptive (if I understood well the purpose of 
this magenta book). All examples of code should 
be moved to annex (or non-normative NOTES), since 
they only describe an implementation of the 
functions using or providing the API.


Total Respondents:  4

No response was received from the following Area(s):

      SOIS
      SIS



SECRETARIAT INTERPRETATION OF RESULTS:  Approved with Conditions
PROPOSED SECRETARIAT ACTION:            Await resolution of comments

* * * * * * * * * * * * * * * * * * * * * * * *