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 00:07:17 UTC