[CESG] Whereabouts oif poll: 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)

[Barkley, Erik J (317H)]

Nestor,

My conditions have been addressed.  I have no further issues and, as far as I am concerned, the document may proceed to agency reviews.

Best regards,

-Erik

From: cesg-bounces at mailman.ccsds.org [mailto:cesg-bounces at mailman.ccsds.org] On Behalf Of Nestor.Peccia at esa.int
Sent: Wednesday, May 18, 2011 8:03 AM
To: CCSDS Engineering Steering Group - CESG Exec
Cc: moims-sc at mailman.ccsds.org
Subject: [CESG] Whereabouts oif poll: 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)


Erik, Gilles and Peter

You have approved with conditions the Pre-Red review of MO MAL - Java API RB (before being issued for Agency Review )

The Java API editor captain has been discussing with you the necessary updates required to satisfy your conditions

You will find attach the new version.

As MOIMS AD, I am requesting you to confirm that your conditions are satisfied

Once this step is completed, I will request the CESG Chair to start the corresponding CMC poll



I attach below for your convenience the poll results

ciao
nestor
============================================





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)







CSS AD  Barkley Erik
 APPROVE WITH CONDITIONS (state conditions that must be satisfied)
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?

SEA AD  Shames Peter
 APPROVE WITH CONDITIONS (state conditions that must be satisfied)
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.

SLS DAD  Moury Gilles
 APPROVE WITH CONDITIONS (state conditions that must be satisfied) 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.
-------------- next part --------------
An HTML attachment was scrubbed...
URL: http://mailman.ccsds.org/pipermail/cesg/attachments/20110525/0992c753/attachment.html