[Moims-sc] Re: [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)

[Shames, Peter M (313B)]

OK.  Thanks David.  That helps.

Peter



On 5/19/11 2:16 AM, "David Feliot" <David.Feliot at scalagent.com> wrote:

>Peter,
>
>The "track changes" version has just been uploaded on the CWE. The link
>is:
>http://cwe.ccsds.org/moims/docs/MOIMS-SMandC/Draft%20Documents/MAL%20Java%
>20API/521x2r0_CESG_Approval-0.1-changes-2.doc
>
>This document should display the changes you're interested in. However it
>doesn't show the many "terse style" changes that have been submitted
>before. If you need to see them then you can check the following document:
>http://cwe.ccsds.org/moims/docs/MOIMS-SMandC/Draft%20Documents/MAL%20Java%
>20API/521x2r0_CESG_Approval-0.1-changes-1.doc
>
>Best regards,
>David.
>
>
>> Nestor,
>>
>> I have had some extensive discussions with Erwann on this document.  I
>> just did a side by side comparison of the resulting document and my
>> original inputs.  It would have saved time if I had been provided a
>>"track
>> changes" version so I could see at a glance what had been changed.  I
>>did
>> identify that there have been a couple of changes made that resolved
>>some
>> issues.  There were two more that I identified that were not changed
>>and I
>> have made two markups in the attached, shown as "track changes" so they
>> can easily be located.
>>
>> The issue of a CCSDS wide Java namespace registry, which is implied in
>>sec
>> 3.1, must still be resolved in CESG, but it does not appear to be
>> controversial and is the sensible thing to do.  I suggest that we
>> acknowledge it in a note now and plan to include the SANA registry
>>section
>> in the next revision of the document.
>>
>> With these changes I am content to see the book released for review.   I
>> will reserve the right to review the final document for resolution of
>>all
>> the shall, should, must, language repairs.  In any event, I fully expect
>> many of these to be identified by the agency review.
>>
>> Regards, Peter
>>
>>
>>
>> From: Nestor Peccia
>><Nestor.Peccia at esa.int<mailto:Nestor.Peccia at esa.int>>
>> Date: Wed, 18 May 2011 08:02:38 -0700
>> To: CCSDS Engineering Steering Group - CESG Exec
>> <cesg at mailman.ccsds.org<mailto:cesg at mailman.ccsds.org>>
>> Cc: MOIMS-SC MOIMS-SC
>> <moims-sc at mailman.ccsds.org<mailto: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.
>> _______________________________________________
>> Moims-sc mailing list
>> Moims-sc at mailman.ccsds.org
>> http://mailman.ccsds.org/mailman/listinfo/moims-sc
>>
>