DPF Section 4.2 exception text muddle

section 4.2
Exception text muddle

There seems to have been a number of editorial errors
with the text defining the conditions leading to exceptions.

A glaring copy/paste one is last sentence of 4.2.5 the property
in question has no previous parent, this text seems to have been
miscopied from 4.2.4

A large number of exceptions have no text describing when they
happen in a particular method.

I suggest significant effort to clarify here. I would like to see,
under each method, a table, with one column with the exception,
and a second with a description of the exception condition as it
occurs in this method.

While such text would be boring (both to write and to read) and
would duplicate (to some extent) section 4.8, I think it would
be helpful and clear.

I also have a number of substantive issues (s8, s9, s10, s14, s15)
to do with exceptions, which I believe stem partly from the lack
of clarity of the current text leading to mistakes.


The DPF Working Group agrees and have been working through the  
document to address exceptions more comprehensively.  Below is an  
example of the new document layout for Methods, including the request  
for a more explicit exception section.  As a result, the overall  
document structure has also been changed to accommodate these  
modifications.

     5.1.2.1 appendDPFProperty

DPFProperty appendDPFProperty(in DPFProperty newChild)
             raises(DPFException);

         This method is used to append a new child property to the  
list of children of the current property at which this method is  
called. The current property is set as the parent property to the  
newly added child property.

         Parameters

             newChild

                 The new child property that is to be appended.

         Return Value
             DPFProperty The property that was appended.

         Exceptions

             DPFException

                 NO_MODIFICATIONS_ALLOWED_ERR: This exception is  
raised if the current parent property is read only and cannot be  
modified.

                 HIERARCHY_REQUEST_ERR: This exception is raised if  
the child property being appended does not belong to the property  
type supported by the parent, if the child property being appended is  
an ancestor of the current parent property or a replica of the  
current property itself.

                 TYPE_MISMATCH_ERR: This exception is raised when  
there is a DPF object type mismatch between the parent and child. For  
example, adding a DPFPropertyList when a DPFProperty is expected.

-Keith Waters

Received on Wednesday, 1 June 2005 21:32:15 UTC