RE: New Draft API Document 1e - and discussion of PropertyName and a couple of other things

Thanks for your detailed explanation Rotan.

There is a difference, I think, between NULL_ASPECT (meaning, to my ear,
the vocabulary supports the idea of properties attached to an unnamed
aspect), and UNSPECIFIED_ASPECT, which would mean that the caller of the
interface doesn't mind what aspect the property is attached to, it might
be NULL it might not be.

So the additional call

  getPropertyValue(Evidence e, String aspect, SimplePropertyRef spr)


Either has the meaning 

a) "replace whatever aspect is referred to in spr with aspect, throw an
exception if that combination is invalid" 

or it means 

b) "if spr.getAspectName() returns UNSPECIFIED_ASPECT combine aspect
with it and proceeed, throw an exception otherwise" 

or of course it may mean other things I hadn't thought of.

Jo
> -----Original Message-----
> From: public-ddwg-request@w3.org [mailto:public-ddwg-request@w3.org]
On
> Behalf Of Rotan Hanrahan
> Sent: 25 February 2008 00:07
> To: public-ddwg@w3.org
> Subject: RE: New Draft API Document 1e - and discussion of
PropertyName
> and a couple of other things
> 
> 
> Thank you for the update Jo.
> 
> The revised Simple API is certainly an excellent entry-point for
> developers who want to start using context-adaptive techniques in
> content generation for the mobile Web.
> 
> In discussions among the group members over the past week, the issue
of
> the proposed PropertyName class remained unresolved. (To avoid
> confusion, I'm going to refer to this class by an alternative moniker:
> QualifiedPropertyName.) It had already been agreed that the further
> simplification of removing the AspectName class could be accepted if
the
> Simple API made an assumption that the definitions of the aspects
could
> be found via reference to the vocabulary of the property term(s) being
> queried. With such an assumption, an unqualified aspect name could be
> used, and a string would suffice to represent the aspect.
> 
> In the case of properties, we retained the idea that a property should
> really be identified by the name/identifier associated with the term,
> and the identifier of the vocabulary to which the term belongs. Of
> course, we could have also bound the Simple API to only use a default
> vocabulary (perhaps identified in the initialize() method) but this
> would have prevented the use of the Simple API in a multi-vocabulary
> situation. Such lack of scalability/extensibility would not be good
for
> the future of the API.
> 
> So the notion of a property being identified by a Name, a Vocabulary
> identifier and an Aspect, is central to the underlying model.
> 
> It is an easy extension from here to say that Aspect is further
divided
> into a Name and a vocabulary identifier, which means that in a future
> advanced API we could instantiate an unambiguous reference to a
property
> via 4 parameters. By using appropriate defaulting mechanisms, we can
> remain backward compatible with the Simple API.
> 
> There is a hierarchy of concepts in this approach, which is not
captured
> in a simple list of three or four strings. It is not:
>    ("PN", "PV", "AN", "AV")
> It is more like this:
>    (("PN", "PV"), ("AN", "AV"))  ==  (QualifiedPropertyName,
> QualifiedAspectName)
> 
> In the Simple API, the Aspect Vocabulary has been declared to be
derived
> data. The Aspect Vocabulary is not exposed in the Simple API. So the
> conceptual identification of a property of interest is like this:
>    (("PN", "PV"), ("AN"))
> 
> It is clear that the concept of aspect in the Simple API would not be
> affected if it were just a string and not a class in its own right.
> Hence the acceptance of removing AspectName as a class dedicated to
> representing aspect. We now get:
>    (("PN", "PV"), "AN")
> 
> The SimplePropertyRef class is constructed from these data, but does
not
> explicitly represent the structured nature of the data. The most
general
> instance is obtained via this construction:
>    ("V", "AN", "PN")
> 
> Meanwhile, the corresponding general getter method of the
SimpleService
> uses this:
>    (E, SPR)
> And
>    (E, "AN", "PN")   -- this uses the default vocabulary
> 
> So, one may ask: if you can construct queries using only strings, why
do
> we need a SimplePropertyRef class at all? Could we not just get rid of
> SimplePropertyClass, just like we got rid of the PropertyName and
> AspectName classes?
> 
> Part of the answer lies in some of the advantages of using typed data.
> Two in particular come to mind.
> 
> 1/  There is an advantage in using types in the source of a compiled
> language, where the calls can be validated in advance, and certain
> contracts therefore give the compiler the freedom to make certain
> assumptions and thus make certain optimisations. The use of typed data
> thus helps prevent malformed code, while improving performance.
> 
> 2/  There are run-time optimisations that can be used when
interactions
> are based on interface contracts and where the typed data within those
> contracts are independent of other contracts.
> 
> Benefit 1/ is well known, and of course these benefits don't apply in
> all languages. But the implementer of the Simple API can make direct
use
> of this technique for those methods that include data types from the
> Simple API itself, and not just generic types like String.
> 
> Benefit 2/ needs a bit of explanation. Suppose I have a system that
> processes a some records, and that each record contains a date. Now
also
> suppose that date is being represented in the record by a large
integer,
> counting hours since 1 January, 1855. These records can be used many
> times during calculations, and each time it is necessary to know the
> month in which the date occurred. Obviously, if I represent the record
> as a class, it makes sense to me to also calculate the month once
based
> on the integer, and to cache that result in the class. However, if I
am
> forced to pass the date around as an integer, this calculation must be
> performed every time. Better to wrap the integer in a class that can
> also hold that cached result, and use that class in all subsequent
> calculations.
> 
> This approach can also apply to SimplePropertyRef, because the class
can
> wrap implementation-specific data for use in optimal calculations. For
> example, when an instance is constructed, it can be validated (i.e.
> checked to see that it is an actual term in a supported vocabulary)
and
> the strings of the constructor augmented with more efficient
> indices/keys with which to retrieve data.
> 
> The Simple API currently contains method signatures that do not afford
> certain optimisation benefits, but nevertheless avoid much complexity,
> which would make it appealing to novices. It also contains classes and
> method signatures that permit some compile and run-time efficiencies,
> and would be encouraged for use in more sophisticated developments.
> Meanwhile, a PropertyName (i.e. QualifiedProperty) class could be
> introduced without affecting any of the existing Simple API.
> 
> So the question is this: is there a need for a separate PropertyName /
> QualifiedProperty class?
> 
> I believe there will be for the advanced API, but for now we can make
> another observation about the use of types in the Simple API: A
> PropertyName (aka QualifiedProperty) is a SimplePropertyRef with an
> unspecified aspect. So perhaps it's only a matter of terminology,
rather
> than a necessity to have a separate class in the Simple API.
> 
> The factory to create a SimplePropertyRef is as follows:
>    newPropertyRef("V", "AN", "PN")
> so to create an instance of a SimplePropertyRef that can be treated as
a
> ProeprtyName one needs a way to indicate that the aspect is
unspecified.
> 
> This is why I think that Jo's suggestion of a NULL_ASPECT is a good
> idea. It would mean that to construct a PropertyName
(QualifiedProperty)
> we mere use the following factory:
>    newPropertyRef("V", NULL_ASPECT, "PN")
> 
> However, now that we have a way of creating an object that is
> essentially the PropertyName we had in a previous version of the
Simple
> API, we should consider how we can use such an object in the other
> methods.
> 
> We already have:
>    getPropertyValue(Evidence, SimplePropertyRef)
> which would be equivalent to:
>    getPropertyValue(Evidence, PropertyName)
> and because the aspect is unspecified, this query should interpret
> NULL_ASPECT to mean a deference to whatever aspect is recommended in
the
> term definition within the corresponding vocabulary.
> 
> But can we also make a query using a pseudo-PropertyName (SPR with
> NULL_ASPECT) object and an aspect? Unfortunately no. The closest we
have
> is:
>    getPropertyValue(Evidence e, String aspect, String propertyName)
> when what we also need is:
>    getPropertyValue(Evidence e, String aspect, PropertyName pn)
> which (thanks to NULL_ASPECT) is:
>    getPropertyValue(Evidence e, String aspect, SimplePropertyRef spr)
> 
> I would interpret this method to mean that whatever aspect is in the
spr
> object should be overridden by the aspect given in the second
parameter.
> When the spr has a NULL_ASPECT, this is exactly the behaviour we need.
> 
> To conclude...
> 
> I believe we have a Simple API that is both simple and extensible. It
> also provides opportunities for compile time and run time
optimisations.
> Finally, regarding the issue of PropertyName, I believe the concept of
a
> ProeprtyName (i.e. QualifiedProperty) can be supported if we have a
> NULL_ASPECT constant and we add the following query method:
>    getPropertyValue(Evidence e, String aspect, SimplePropertyRef spr)
> 
> 
> ---Rotan.
> 
> 
> -----Original Message-----
> From: public-ddwg-request@w3.org [mailto:public-ddwg-request@w3.org]
On
> Behalf Of Jo Rabin
> Sent: 23 February 2008 10:51
> To: public-ddwg@w3.org
> Subject: New Draft API Document 1e - and discussion of PropertyName
and
> a couple of other things
> 
> 
> Rotan pointed out to me a number of typos relating to PropertyName
which
> I have corrected in this draft. Sorry about the earlier lapse,
"festina
> lente".
> 
> http://www.w3.org/2005/MWI/DDWG/drafts/api/080223
> 
> Rotan also points out to me that removal of the PropertyName class was
> not what he expected in this draft. I don't have any strong objection
to
> putting PropertyName back in - equally I'd prefer to leave it out on
the
> basis that it serves a rather limited use case that can be addressed
in
> a different way, and introduces a number of complications:
> 
> I am unclear about the relationship between PropertyName and
> SimplePropertyRef and whether and how they sub-class each other. I
can't
> figure out a model that makes this consistent with our agreement on
list
> that both property names and aspect names live in the same namespace.
I
> believe that I might be missing the point here, so if we are to
include
> it I need some help on text for this.
> 
> I am also unsure how this changes the method signatures of
> SimpleProperty and I don't know how this would affect the constructors
> for SimplePropertyRef.
> 
> With suitable clarification of these points I will try to crank out a
> new draft.
> 
> Since I am writing, I'd also like to bring your attention to the
> following method of SimpleService,
> 
> 	public SimplePropertyValues getPropertyValues(Evidence evidence,
> 			String aspectIRI, String aspectName) throws
> NameException,
> 			SystemException;
> 
> Which allows you to list known property values from an aspect in a non
> default namespace. It seemed to me at the time I put this in to be
> logically necessary, but I am not sure now.
> 
> I'd also like you to ponder the following:
> 
> 	public static String ANY_ASPECT = "__ANY";
> 	public static String ANY_PROPERTY = "__ANY";
> 	public static String DEFAULT_VOCABULARY =
> "__DEFAULT_VOCABULARY";
> 	public static String DEFAULT_ASPECT = "__DEFAULT_ASPECT";
> 	public static final String NULL_ASPECT = "__NULL";
> 	public static final String NULL_NAMESPACE = "__NULL";
> 
> Ignoring the fact, for a moment, that they should all be final, do we
> think these should be there? I feel strongly that NULL is needed for
> both aspect and namespace - to accommodate vocabularies that are
"aspect
> unaware" and which haven't defined a namespace.
> 
> I am less sure that ANY is needed, though it might be handy and, for
> example, would allow you to refer to a property independently of its
> aspect. I think this is a bit of a kludge, even more so the DEFAULT
> VOCABULARY bit, less so the DEFAULT_ASPECT.
> 
> On the subject of DEFAULT_ASPECT my expectation had been that it is
> something the Vocabulary defines. I have a sneaking feeling that
> SimpleService should have methods to reveal the default vocabulary and
> the default aspect for a vocabulary e.g.
> 
> String getDefaultNamespace();
> String getDefaultAspect(String namespace);
> 
> In which case the DEFAULT consts are definitely not needed.
> 
> I stop there for now.
> 
> Jo
> 
>

Received on Monday, 25 February 2008 07:53:06 UTC