Explainations of interface/serializations (what is required) (Was: Re: [QUANTITY] Data Model for Quantity v0.5

[Brian Thomas]

	Hi Pierre,

On Monday 10 May 2004 12:11 pm, Pierre Didelon wrote:
> Brian Thomas wrote:
>
>
> The serialization document lays out the
>
> > 	structure, which is fairly simple. Here's a copy :
> >
> > --- begin snippet ----
> >
> >    The components of these types of quantity are given elsewhere, but
> >    summarized here, are:
> >
> >         Basic Quantity
> >                 UCD
> >                 CoordSystem
> >                 Units
> >                 DataType
> >                 Value
> >                 Accuracy
>
> in DM for Quantity V0.2 document  p13. diag show accuracy linked to core
> Quantity but BasicQuantity interface on p.14 give methods to handle
> accuracy... so even doc is contradictory.

	Hmm. I believe that BasicQuantity (BQ) should have accuracy, so that
	is an oversight in the document which should be corrected (thank you).
	The BQ interface should have methods which allow accessing accuracy
	list and figure 1 should be changed.


> XSD files and corresponding schema/diag seems to integrate accuracy at the
> basic level. Finally, at which level is the accuracy related?

	As I said above, the BQ should allow accuracy.

> Moreover in § 7.6 examples are not clear; they use <quantity> without
> always precising basic/core/standard case, at least in part 1. & 3.
> Is this intentionnal to illustrate the polymorphism of the quantity
> inheritance?

	Yes. All the "higher" level interfaces/serializations should be able
	to understand the "lower" ones. This is to say, IF I have an object
	which starts as:

   StandardQuantity myQuantity = new StandQImpl();

	I can "down-cast" it with no problems, e.g.

   BasicQuantity bqRep = (BasicQuantity) myQuantity;

	Again, "realization" relationship between the interfaces makes this possible
	but *doesnt* require that the implementer follow the same class hierarchy for
	inheritance purposes. 

> Any way it is misleading and not precise enough, at least for
> example/illustration clarity. If 7.6.1 illustrates basicQuantity
> serialization, then altValues tag seems not appropriate here, as it is
> relevant only for standardQuantity (p13 diag)?

	That is a good point; they should agree but don't. I personally feel that
	"altValues" is more descriptive of what is going on than the "ValueQuantity"
	methods in the interface. Furthermore, because these things (altValues) are
	intended to allow grouping together of equivalent quantities (for example,
	a "flux" quantity could have an alternative value of "magnitude") I would 
	change the following in the document;

	To "StandardQuantity" interface, add the methods:

   boolean addAlternativeValue(CoreQuantity val);
   boolean removeAlternativeValue(CoreQuantity val);
   List getAlternativeValueList();

	and to "StandardQuantity" remove the following:
  
   addValueQuantity (CoreQ val);
   removeValueQuantity(CoreQ val);
   List getValueQuantityList();

	as well as the methods:

getCurrentCoordsQuantity()
getCurrentValueQuantity()

	which should be in the Locator, not the StandardQuantity interface.

	The serializations and schema should be changed to prevent "altValues"
	from appearing in BQ, CQ's.

>
> So I must admit that I am completly confused, some clarification is needed,
> at least for me.

	I'm happy to try to help.

> Moreover it would be nice to have a clear statement
> of which parts are mandatory and which ones are optionnal, at each level,
> in clear english (understable by non-english mother spoker like me)

	This *is* in the document, but may not be clear. OK, I will take a stab at 
	a summary:

         Basic Quantity [id attribute optional]
                 UCD  -   Optional
                 CoordSystem - Optional
                 Units - Optional (Defaults to "unitless")
                 DataType - Optional (Defaults to "string of arbitrary length")
                 Value - Required
                 Accuracy - Optional
 
         Core Quantity [id, size attributes optional]
                 UCD - Optional
                 CoordSystem - Optional
                 Units - Required (But if absent in serialization it defaults to "unitless")
                 DataType - Required (But if absent in serialization it defaults to "string of arbitrary length")
                 Values - Required
                 Accuracy - Optional

         Std Quantity [id, size attributes optional]
                 UCD - Optional
                 CoordSystem - Optional
                 Units - Required (But if absent in serialization it defaults to "unitless")
                 DataType - Required (But if absent in serialization it defaults to "string of arbitrary length")
                 AxesList (gives coordinate frames for accessing values in Q) - Optional
                 Values - Required
                 AltValues - Optional
                 Accuracy - Optional


   	So you can see that "dataType", "units" and "values" are required at all
	levels. But for the first 2 types of information, we allow for sensible defaults,
	in order that the serialization can be made more compact and to promote 
	use of Q interface in the widest variety of XML nodes.

> outside xsd doc. But then it is more related to data-modelling or
> serialization than to class interface, would you say. Yes... but you can
> then define methods which are allowed to return null values and others who
> are not.

	Correct. The "units", "dataType" and "value(s)" accessor methods must return
	non-null stuff or else sensible information always. The other methods are optional,
	and so the programmer needs to prepare for having null values (or empty lists) 
	returned.

>
> Attempting to clarify my mind on basicQuantity first... at least.
> Does it make any sense?

	Did that explanation help?

	Regards,

	=b.t.


-- 

  * Dr. Brian Thomas 

  * Dept of Astronomy/University of Maryland-College Park 
  * Code 630.1/Goddard Space Flight Center-NASA

  *   fax: (301) 286-1775
  * phone: (301) 286-6128 [GSFC]
           (301) 405-2312 [UMD]