Issues for Lightweight Log FTF

List of issues (green=resolved, yellow=pending Board vote, red=unresolved)

List options: All ; Open Issues only; or Closed Issues only

Issue 5884: LW Log Service IDL errors
Issue 5885: issue with section 2.4.2 retrieveById
Issue 5888: Page 43. In Section 4 The Complete Logging Service IDL
Issue 5889: Notation used in PIM
Issue 5890: Sponsoring Task Force
Issue 5908: InvalidParam exception
Issue 5913: current write operation
Issue 5914: Section 4 of the Specification -- the IDL
Issue 5915: LogRecordSequence
Issue 5916: Text of the Specification: (PIM)
Issue 5917: Text of the Specification: (PSM)
Issue 5920: use of IDL type string for data that's logged is not cross-language compati

Issue 5884: LW Log Service IDL errors (lwlog-ftf)

The Lightweight Log draft adopted specification contains some errors in
its IDL.


There is a struct called ProducerLogRecord, which is being referred to
later on as LogProducerRecord in the LogProducer interface (page 56).
Furthermore, the LogFullAction enum is wrongly referred to as
LogFullActionType. The same goes for AdministrativeState which is being
referred to as AdministrativeStateType from the LogAdministrator
interface definition.

We have implemented the above service as part of our SCA Core Framework
implementation.  However, we have an issue with section 2.4.2 retrieveById of
the document.


This section states (we have numbered the sentences in question):


S1: "The log will update howMany to indicate the number of records returned and
will set currentId to the id of the record following the last retrieved record.


S2: "If there are no further records available, currentId will be set to zero."


S3: "If the record specified by the currentId does not exist, or if the Log is
empty, the retrieveById operation returns an empty list of LogRecords, and sets
both, currentId and howMany to zero."


This behavior can create a problem as follows.


1) A log is operational with 10 records, Id 1 through 10.


2) An application issues a retrievById request for 5 logs starting at ID 6.


3) The log retrieves records 6 through 10, updates the howMany to 5, and sets
the currentId to 11, per S1 above


NOTE: At this point it is unclear if S2 applies.  Certainly, at this point in
time, no more records are available but setting currentId to zero is in conflict
with S1 and doesn't appear to make sense.  The following steps assume that S1 is
followed and S2 is ignored.


4) The log is still operational but has not written any additional records when
the same application issues a retrievById for 10 records starting at record id
11 (what it believes to be the next record).


5) The currentId of 11 does not exist in the log, so S3 applies.  Consequently,
the log returns an empty set of LogRecords and sets both howMany and currentId
to zero.


6) The application now believes the currentId in the log has been reset to zero.


7) The log writes records 11 through 14.


At this point the application has lost a valid reference into the log to obtain
the next record by Id.


We would like to recommend the following changes to the retrieveById .


S1: No Change


S2: Strike from the paragraph.


S3: Strike as worded and add the following conditions:


S3.A) If the record specified by currentId does not exist AND the currentId
provided by the call is greater than the Id of the last record written by the
log, the retrieveById operation returns an empty list of LogRecords, sets
howMany to zero, and leaves the currentId unchanged.


S3.B) If the record specified by currentId does not exist AND the currentId
provided by the call is zero OR less than the first Id of the log, the
retrieveById operation returns an list of LogRecords starting with the first
available records, sets howMany to the number of records retrieved, and sets the
currentId to one past the last record retrieved.


S3.C) If the record specified by currentId does not exist and the Log is empty,
the retrieveById operation returns an empty list of LogRecords, sets hoMany to
zero, and sets the curentId to zero.


Change S3.A allows a client to request log records and leave the currentId
pointing the next log record in the eent that at the time of the retrievById
operation, there were no log records available but the log is operational and
just had not written any additional records since the applications last request.


Change S3.B addresses the scenarios where the client may have a Id reference
that has been written and cleared since it's last retrieveId request and the
first available log Id is greater than the Id requested.  It also provides the
mechanism for allowing a client to issue a retrieveById without knowing the
current state of the log and obtain the first set of available log records.


Change S3.C identifies the empty log condition to the application as opposed to
simply no further records available at the time of the call.

Page 43. In Section 4 The Complete Logging Service IDL, the text incorrectly uses all capitol letters for PRAGMA. Therefore

Recommendation: Change #PRAGMA prefix "omg.org" to
             #pragma prefix "omg.org".     

Throughout the PIM. "void" is used to indicate that no data is returned from the operation. The comment is about the PIM operations where void is specified for the return type.  Recommend that "void" be removed from the PIM. Void is not conformant to UML PIM.  
void is language (c, Java) specific

+ oper1 (in MyType, in MyType)

Would this change require changes in the PSM as well, in order to specify "void"?

The name of the sponsoring task force is Real-time, Embedded, and Specialized Systems (RTESS). Currently references do not consistently include the acronym.

Recommendation: Update page .8, Section .10 text and page 7, Section .8, both title and text to be:
Real-time, Embedded, and Specialized Systems (RTESS).  

Neither the PSM for CORBA nor the IDL mention the
InvalidParam exception. (The IDL uses the exception,
but does not define it.)

The current write operation only has on parameter (ProducerLogRecordSequence) that allows a sequence of log records to be written.

add an additional write operation with a simple parameter that allows a single log record to be written and does not require a sequence. 

            "Complete Logging Service IDL"

* Names the raised exception "InvalidParam" without ever
   declaring it.  Add to the IDL, probably near the beginning,
   the following declaration, or its equivalent:
       exception InvalidParam {
          string Details;
       };


* Syntax error in:
        enum LogFullAction (WRAP, HALT);
   Change to:
        enum LogFullAction {WRAP, HALT};

  [Error above is also in the specification text, section 3.2.4]

* These types appear needed by the IDL but nowhere actually
   defined in the IDL:
                        ProducerLogRecordSequence
                        LogProducerRecord

They are naming-confusion/consistency problems, and they
also appear in the text of the specification.
   They involve writers' confusion between the interface
name ("LogProducer") and the type names ProducerLog...
It is correctable by changing the current defective declaration
from:
        typedef sequence<LogProducerRecord
           LogProducerRecordSequence;
to:
        typedef sequence<ProducerLogRecord
           ProducerLogRecordSequence;
The text of the specification in section 3.3.3 (page 3-15) should
also be corrected for these word inversion problems.

end 1st issue. These are IDL issues in addition to the ones identified in 5885.

* It is inconsistent to define LogRecordSequence outside of
   the interface of its user LogConsumer
   while attempting to define ProducerLogRecordSequence inside of
   the interface of its user LogProducer.

This is mostly sequential.  There is considerable, coding-oriented
meat here.  Forgive the initial attention to a few trivial
capitalization/editing problems noted.

Needs a consistent capitalization of RecordID/RecordId (recordId?),
starting with the table of contents and including every figure and
code example, as well as the text. (The IDL uses the former, but the specification text
   uses both.  (I understand that the CORBA is supposed to be
   case-insensitive, but that will not be true of the generated
   C++ or Java code.)

Page 2-5, section 2.2.2 ",do denote" should be ", to denote"

Page 2-7, section 2.2.9 "LogRecordType" should be "LogRecord type"

Page 2-15, near end of section 2.5 "unique record Id" should be
changed to "unique recordId"  (join the separated words, and use
whatever consistent capitalization is selected).

Page 2-16, section 2.6.2 "Void" type in the parameters box should
be "void" for consistency.

Page 2-17, section 2.6.3 "Void" type in the parameters box should
be "void" for consistency.

Page 2-18, section 2.6.5, code snipet  "Destroy () : void"
should be  "destroy () : void"  for consistency.

Page 3-2, Section 3.2 at the top omits any mapping to the
Platform Specific Model of the PIM section 2.2.1 InvalidParam
exception.  The appropriate text needs to be added.
(Since the actual IDL is mostly derived from the Section 3.2
details, this omission apparently led to the omission of the
exception declaration from the IDL, cited above.)

Page 3-3, section 3.2.4, remove syntax error
from:
         enum LogFullAction (WRAP, HALT);
to:
         enum LogFullAction {WRAP, HALT};

Page 3-5, section 3.2.7 has a wrong-word problem in the PSM code.
change:
           <ProducerLogRecordType
to:
           <ProducerLogRecord

Page 3-5, section 3.2.7, the Description box for producerID has
some residual cut-and-paste text from the SCA that needs to be
removed or revised.  The questionable text is:
     "SCA Resource and Core Framework"

Page 3-6, section 3.2.9 has another code-level wrong word problem.
change:
          <LogRecordType
to:
          <LogRecord

Page 3-11, end of section 3.3.1.4, add the missing preposition.
change:
          "signature the equivalent"
to:
          "signature to the equivalent"

Page 3-15, section 3.3.3 contains two kinds of problems at the
code level.
   (1) LogProducerRecord  &  LogProducerRecordSequence
     are word-transposition misnomers for
       ProducerLogRecord  &  ProducerLogRecordSequence
   (2) The desired sequence has already been more properly defined
     in section 3.2.7 earlier.

Page 3-19, section 3.3.4.3 needed to replace all the
full-upper-uppercase references to LOCKED & UNLOCKED by
their full-lower-case equivalents locked & unlocked, as per
section 3.2.2 and per the manner of usage in section 3.3.1.6

Discussion:
The data that can be logged with the Lightweight Log service is an encoding of arbitrary binary data. The type used in the ProducerLogRecord for this data is "string" in both the PIM and the PSM. This is inappropriate, since strings are not considered to be arbitrary encodings. They are associated with particular (and different) character encodings in different technologies. This can be seen even within the CORBA PSM, where the Java language mapping transforms a string to sixteen-bit characters internally.


Proposed Resolution:
Change the type of the logData field in the ProducerLogRecord to OctetSeq

use of the IDL type string for data that is logged is not give cross-language compatible