RE: Admissible Evidence

Further clarification. If the Simple API just wants to support HTTP
headers as evidence, and no more, then you just need an Admissible
interface and a HTTPEvidence interface. You don't need the generic
Evidence interface. A custom implementation can introduce its own
Evidence interfaces without affecting the Simple API because the queries
all use instances that provide the Admissible interface. And that
interface makes no demands on implementations whatsoever. Simple.

 

---Rotan.

 

From: Rotan Hanrahan 
Sent: 25 February 2008 16:14
To: Rotan Hanrahan; public-ddwg@w3.org
Subject: RE: Admissible Evidence

 

Actually, on reflection, neither of the Evidence interfaces have to
extend the Admissible interface in order to work, but certainly the
object into which you place your evidence has to support both the
appropriate Evidence interface *and* the Admissible interface. How to
capture that in a pure interface specification (rather than a
specification of classes) is not completely clear. Using interface
inheritance does this for me, which is why I originally proposed it.

 

As we want to get closure on the Evidence issue asap (today if possible)
can we get some feedback?

 

---Rotan.

 

From: public-ddwg-request@w3.org [mailto:public-ddwg-request@w3.org] On
Behalf Of Rotan Hanrahan
Sent: 25 February 2008 15:51
To: public-ddwg@w3.org
Subject: Admissible Evidence

 

Some thoughts about Evidence.

We only need a "put" method. How the implementation decides to extract
the data from the object is down to the implementation. The API doesn't
care.

OK. That keeps the Evidence interface very simple.

We want to be able to put HTTP headers into the Evidence. That's a
minimum requirement. Headers are naturally a name/value pair. Such pairs
do very well to capture generic information.

We could use put(string name, string value). That would work for HTTP
headers.

It could also extend to implementations that wanted things other than
headers to be part of the evidence, without having to change the API.
But how would such an implementation know that the extra data wasn't
just more HTTP headers?

I suppose the implementation would have to have keys that are obviously
not HTTP header names, but at least this approach would still be able to
use put(string key, string value).

Alternatively, we could observe that the key could be something other
than a HTTP header. For that, we'd need a Key class.

   Put(Key key, string value)

Oh, the value might not be a string. So we need something generic.
There's already something that is completely generic, and we call it
Object. That gives me:

   Put(Key key, Object value)

Is this getting too complex for something that will almost always just
involve name/string pairs?

One more time, then...

The general case is that Evidence is a collection of pairs, matching a
general key to a general value. In reality this is just:

   Put(Object key, Object value)

So let this general case be handled by a base class Evidence.

Now, for the Simple API we have a simple use case, HTTP headers. This
can be handled by:

   Put(String headerName, String headerValue)

We could make this a method of a SimpleEvidence class.

So what about the query methods that need an evidence parameter? Do they
take Evidence or SimpleEvidence? In fact, they should not care, because
these interfaces define only put() which presumably the query methods
are not concerned with. In fact, because the extraction and use of
evidence data happens behind the scenes in the DDR implementation, we
don't actually have to say anything at all about the getter interface of
the object that is passed in as evidence.

In fact, from the point of view of the queries, the evidence parameter
only has to be flagged as being valid for use as evidence. This can be
done via a UsableAsEvidence interface that has *no required methods at
all* !

We call that "void".

But for implementation efficiency, it's better to define this empty
interface with a name, such as UsableAsEvidence (or Admissible).

This suggests a hierarchy:

At the top is the Admissible interface, which has no methods (or at
least none exposed to the public).

Then we have Evidence which extends Admissible and has a
put(object,object) method.

There is also HTTPEvidence which also extends Admissible and has a
put(headerName,headerValue) method.

Finally, the query methods all take Admissible as the first parameter
representing the evidence to be used to identify the context.

Admissible

  [This interface is empty]

Evidence (extends Admissible)

  Void                put(Object key, Object value)

HTTPEvidence (extends Admissible)

  Void                put(String headerName, String headerValue)

SimpleService

  SimplePropertyValue  getPropertyValue(Admissible e, SimplePropertyRef
propertyRef)

  SimplePropertyValue  getPropertyValue(Admissible e, String aspect,
String propertyName)

  SimplePropertyValues getPropertyValues(Admissible e,
SimplePropertyRef[] properties)

Etc.

Does this make sense?

---Rotan.