Final chance, for now, to offer opinion on Simple API [was Continuation of discussion from today's call]

[Jo Rabin-2]

What follows is an edited version of what I sent yesterday. Apologies
for sending it to the wrong list initially.

Aside from Rotan there have been no contributions. For the sake of
getting a document ready for the Face to Face I am going to start work
later this afternoon on a draft. In the absence of response I will take
it as a "+1" to all resolutions except C Alternative 1.

Jo

Contents:

a) what is the signature of the Evidence interface?
b) how are underlying PropertyNames to be supported?
c) Misc renames for consistency

Urgency:

The important thing is to resolve this TODAY [that was yesterday] so we
can have a substantive draft for discussion in Seoul next week,
following which we will issue a First Public Working Draft which "with a
fair wind and a
following sea" (colloq. = with luck) will also be a Last Call working
draft.

Other Tasks

We also need to have debate on this list as to the wording of the
remaining sections of the document - especially Conformance.

---

Let's fix the interface first.

a) Evidence interface

PROPOSED RESOLUTION A: The Evidence interface is

void putHTTPHeader(String headerName, String value)
String getHTTPHeader(String headerName);
Boolean headerExists(String headerName);

A factory method is added to SimpleService:

Evidence newEvidence(HashMap<String, String> httpHeaders)

The reasoning is as follows:

The caller needs a way to put evidence into a known object in a
standardised way. The API must support HTTP Evidence in the form of
(case insensitive) HTTP Header Field name and (case sensitive) HTTP
Header Field value, both strings (ASCII stings, actually, but, er, let's
leave that point aside unless we have to).

The retrieval methods are there so that an object created by some other
instantiation method can still be queried by the any implementation,
although that might not be very efficiently, it does allow inter
working.

It is likely that most Java implementations will want to allow the
passing of a HashMap<String, String> derived directly e.g. from the jsp
infrastructure. However, in general this doesn't work as we can't rely
on support of a HashMap<String, String> structure in other environments
/ languages, so the factory method will probably look different in the
IDL.

It ought also to be a documentation and conformance point that HTTP
Header Field names are treated case insensitively.

I think we should call this SimpleEvidence (or HTTPEvidence) to
distinguish it from any other sort of evidence.

PROPOSED RESOLUTION B: Rename Evidence to SimpleEvidence

b) Support for Property Terms distinct from PropertyRefs

Rotan has discussed this in clear terms that I could not hope to match
[1].

In essence we have 2 proposals, Rotan's which is to overload the
semantic of PropertyRef so it can be aspectless, and mine, which is to
keep the PropertyName class and add a couple of factory methods - one to
PropertyName and the other to SimplePropertyValue, so we don't have to
refer to any inheritance relationships between them.

PROPOSED RESOLUTION C ALERNATIVE 1: Add a method to SimpleService
SimplePropertyValue  getPropertyValue(Evidence e, String aspect,
SimplePropertyRef propertyRef) where the aspect parameter overrides
whatever aspect is present in the propertyRef and throw exceptions
appropriately

PROPOSED RESOLUTION C ALTERNATIVE 2: PropertyName remains in the API and
can be constructed from a PropertyRef by a factory method. A PropertyRef
can be created from a PropertyName by a factory method naming the
aspect.


c) Additional proposed resolutions

PROPOSED RESOLUTION D: In SimplePropertyRef rename getName to
getPropertyName

PROPOSED RESOLUTION E: In SimplePropertyRef rename getAspect to
getAspectName

PROPOSED RESOLUTION F: In SimpleService rename newPropertyRef methods to
newSimplePropertyRef  


That's it folks - pls send +1s etc. to this list asap

Jo

[Rotan Hanrahan]

a)

  Res.A   +1 to factory method for evidence objects

  Res.B   +1 to Simple API having SimpleEvidence object (instead of
generic Evidence)

b)

  Res.C(1) -1 as the proposal was only made as a backup if we decided to
remove PropertyName

  Res.C(2) +1 to keep PropertyName, factory method, and use in
SimplePropertyRef constructor.

c)

  +1 to all renamings


---Rotan

-----Original Message-----
From: public-ddwg-request@... [mailto:public-ddwg-request@...] On
Behalf Of Jo Rabin
Sent: 26 February 2008 07:53
To: public-ddwg@...
Subject: Final chance, for now, to offer opinion on Simple API [was
Continuation of discussion from today's call]


What follows is an edited version of what I sent yesterday. Apologies
for sending it to the wrong list initially.

Aside from Rotan there have been no contributions. For the sake of
getting a document ready for the Face to Face I am going to start work
later this afternoon on a draft. In the absence of response I will take
it as a "+1" to all resolutions except C Alternative 1.

Jo

Contents:

a) what is the signature of the Evidence interface?
b) how are underlying PropertyNames to be supported?
c) Misc renames for consistency

Urgency:

The important thing is to resolve this TODAY [that was yesterday] so we
can have a substantive draft for discussion in Seoul next week,
following which we will issue a First Public Working Draft which "with a
fair wind and a
following sea" (colloq. = with luck) will also be a Last Call working
draft.

Other Tasks

We also need to have debate on this list as to the wording of the
remaining sections of the document - especially Conformance.

---

Let's fix the interface first.

a) Evidence interface

PROPOSED RESOLUTION A: The Evidence interface is

void putHTTPHeader(String headerName, String value)
String getHTTPHeader(String headerName);
Boolean headerExists(String headerName);

A factory method is added to SimpleService:

Evidence newEvidence(HashMap<String, String> httpHeaders)

The reasoning is as follows:

The caller needs a way to put evidence into a known object in a
standardised way. The API must support HTTP Evidence in the form of
(case insensitive) HTTP Header Field name and (case sensitive) HTTP
Header Field value, both strings (ASCII stings, actually, but, er, let's
leave that point aside unless we have to).

The retrieval methods are there so that an object created by some other
instantiation method can still be queried by the any implementation,
although that might not be very efficiently, it does allow inter
working.

It is likely that most Java implementations will want to allow the
passing of a HashMap<String, String> derived directly e.g. from the jsp
infrastructure. However, in general this doesn't work as we can't rely
on support of a HashMap<String, String> structure in other environments
/ languages, so the factory method will probably look different in the
IDL.

It ought also to be a documentation and conformance point that HTTP
Header Field names are treated case insensitively.

I think we should call this SimpleEvidence (or HTTPEvidence) to
distinguish it from any other sort of evidence.

PROPOSED RESOLUTION B: Rename Evidence to SimpleEvidence

b) Support for Property Terms distinct from PropertyRefs

Rotan has discussed this in clear terms that I could not hope to match
[1].

In essence we have 2 proposals, Rotan's which is to overload the
semantic of PropertyRef so it can be aspectless, and mine, which is to
keep the PropertyName class and add a couple of factory methods - one to
PropertyName and the other to SimplePropertyValue, so we don't have to
refer to any inheritance relationships between them.

PROPOSED RESOLUTION C ALERNATIVE 1: Add a method to SimpleService
SimplePropertyValue  getPropertyValue(Evidence e, String aspect,
SimplePropertyRef propertyRef) where the aspect parameter overrides
whatever aspect is present in the propertyRef and throw exceptions
appropriately

PROPOSED RESOLUTION C ALTERNATIVE 2: PropertyName remains in the API and
can be constructed from a PropertyRef by a factory method. A PropertyRef
can be created from a PropertyName by a factory method naming the
aspect.


c) Additional proposed resolutions

PROPOSED RESOLUTION D: In SimplePropertyRef rename getName to
getPropertyName

PROPOSED RESOLUTION E: In SimplePropertyRef rename getAspect to
getAspectName

PROPOSED RESOLUTION F: In SimpleService rename newPropertyRef methods to
newSimplePropertyRef  


That's it folks - pls send +1s etc. to this list asap

Jo

[Pontus Carlsson-2]

a:
PROPOSED RESOLUTION A: +1

PROPOSED RESOLUTION B: +1

b:
PROPOSED RESOLUTION C ALERNATIVE 1: -1

PROPOSED RESOLUTION C ALTERNATIVE 2: +1

c:
  +1 for all

/Pontus
 

-----Original Message-----
From: public-ddwg-request@... [mailto:public-ddwg-request@...] On
Behalf Of Jo Rabin
Sent: den 26 februari 2008 08:53
To: public-ddwg@...
Subject: Final chance, for now, to offer opinion on Simple API [was
Continuation of discussion from today's call]


What follows is an edited version of what I sent yesterday. Apologies
for sending it to the wrong list initially.

Aside from Rotan there have been no contributions. For the sake of
getting a document ready for the Face to Face I am going to start work
later this afternoon on a draft. In the absence of response I will take
it as a "+1" to all resolutions except C Alternative 1.

Jo

Contents:

a) what is the signature of the Evidence interface?
b) how are underlying PropertyNames to be supported?
c) Misc renames for consistency

Urgency:

The important thing is to resolve this TODAY [that was yesterday] so we
can have a substantive draft for discussion in Seoul next week,
following which we will issue a First Public Working Draft which "with a
fair wind and a following sea" (colloq. = with luck) will also be a Last
Call working draft.

Other Tasks

We also need to have debate on this list as to the wording of the
remaining sections of the document - especially Conformance.

---

Let's fix the interface first.

a) Evidence interface

PROPOSED RESOLUTION A: The Evidence interface is

void putHTTPHeader(String headerName, String value) String
getHTTPHeader(String headerName); Boolean headerExists(String
headerName);

A factory method is added to SimpleService:

Evidence newEvidence(HashMap<String, String> httpHeaders)

The reasoning is as follows:

The caller needs a way to put evidence into a known object in a
standardised way. The API must support HTTP Evidence in the form of
(case insensitive) HTTP Header Field name and (case sensitive) HTTP
Header Field value, both strings (ASCII stings, actually, but, er, let's
leave that point aside unless we have to).

The retrieval methods are there so that an object created by some other
instantiation method can still be queried by the any implementation,
although that might not be very efficiently, it does allow inter
working.

It is likely that most Java implementations will want to allow the
passing of a HashMap<String, String> derived directly e.g. from the jsp
infrastructure. However, in general this doesn't work as we can't rely
on support of a HashMap<String, String> structure in other environments
/ languages, so the factory method will probably look different in the
IDL.

It ought also to be a documentation and conformance point that HTTP
Header Field names are treated case insensitively.

I think we should call this SimpleEvidence (or HTTPEvidence) to
distinguish it from any other sort of evidence.

PROPOSED RESOLUTION B: Rename Evidence to SimpleEvidence

b) Support for Property Terms distinct from PropertyRefs

Rotan has discussed this in clear terms that I could not hope to match
[1].

In essence we have 2 proposals, Rotan's which is to overload the
semantic of PropertyRef so it can be aspectless, and mine, which is to
keep the PropertyName class and add a couple of factory methods - one to
PropertyName and the other to SimplePropertyValue, so we don't have to
refer to any inheritance relationships between them.

PROPOSED RESOLUTION C ALERNATIVE 1: Add a method to SimpleService
SimplePropertyValue  getPropertyValue(Evidence e, String aspect,
SimplePropertyRef propertyRef) where the aspect parameter overrides
whatever aspect is present in the propertyRef and throw exceptions
appropriately

PROPOSED RESOLUTION C ALTERNATIVE 2: PropertyName remains in the API and
can be constructed from a PropertyRef by a factory method. A PropertyRef
can be created from a PropertyName by a factory method naming the
aspect.


c) Additional proposed resolutions

PROPOSED RESOLUTION D: In SimplePropertyRef rename getName to
getPropertyName

PROPOSED RESOLUTION E: In SimplePropertyRef rename getAspect to
getAspectName

PROPOSED RESOLUTION F: In SimpleService rename newPropertyRef methods to
newSimplePropertyRef  


That's it folks - pls send +1s etc. to this list asap

Jo

[JOSE MANUEL CANTERA FONSECA]

a)

 Res.A   "conditioned +1" to factory method for evidence objects with the following punctualizations / amendments:

+ the methods should be called putHeader and getHeader to avoid binding it to explictly to HTTP (why it cannot be used with WSP, for example)
+ the factory method in IDL should not receive any parameter i.e.

Evidence = SimpleService.newEvidence()

In the "possible normative" Java binding We could have a

SimpleService.newEvidence(Map) that will allow to create an Evidence object that it is a copy of the key-value pairs of that Map, making key.toString() and value.toString()

Note that I'm not in favour of using Map<String,String> as it would bound us to Java 1.5 and up and I would like to mantain compatibility with at least Java 1.4

Res.B +1 to Simple API having SimpleEvidence object (instead of generic
Evidence)

b)Res.C(1) -1 as the proposal was only made as a backup if we decided to
remove PropertyName

  Res.C(2) +1 to keep PropertyName, factory method, and use in
SimplePropertyRef constructor.

c)

  D +1
  E +1
  F +1

Best Wishes

Jo Rabin escribió:

> What follows is an edited version of what I sent yesterday. Apologies
> for sending it to the wrong list initially.
>
> Aside from Rotan there have been no contributions. For the sake of
> getting a document ready for the Face to Face I am going to start work
> later this afternoon on a draft. In the absence of response I will take
> it as a "+1" to all resolutions except C Alternative 1.
>
> Jo
>
> Contents:
>
> a) what is the signature of the Evidence interface?
> b) how are underlying PropertyNames to be supported?
> c) Misc renames for consistency
>
> Urgency:
>
> The important thing is to resolve this TODAY [that was yesterday] so we
> can have a substantive draft for discussion in Seoul next week,
> following which we will issue a First Public Working Draft which "with a
> fair wind and a
> following sea" (colloq. = with luck) will also be a Last Call working
> draft.
>
> Other Tasks
>
> We also need to have debate on this list as to the wording of the
> remaining sections of the document - especially Conformance.
>
> ---
>
> Let's fix the interface first.
>
> a) Evidence interface
>
> PROPOSED RESOLUTION A: The Evidence interface is
>
> void putHTTPHeader(String headerName, String value)
> String getHTTPHeader(String headerName);
> Boolean headerExists(String headerName);
>
> A factory method is added to SimpleService:
>
> Evidence newEvidence(HashMap<String, String> httpHeaders)
>
> The reasoning is as follows:
>
> The caller needs a way to put evidence into a known object in a
> standardised way. The API must support HTTP Evidence in the form of
> (case insensitive) HTTP Header Field name and (case sensitive) HTTP
> Header Field value, both strings (ASCII stings, actually, but, er, let's
> leave that point aside unless we have to).
>
> The retrieval methods are there so that an object created by some other
> instantiation method can still be queried by the any implementation,
> although that might not be very efficiently, it does allow inter
> working.
>
> It is likely that most Java implementations will want to allow the
> passing of a HashMap<String, String> derived directly e.g. from the jsp
> infrastructure. However, in general this doesn't work as we can't rely
> on support of a HashMap<String, String> structure in other environments
> / languages, so the factory method will probably look different in the
> IDL.
>
> It ought also to be a documentation and conformance point that HTTP
> Header Field names are treated case insensitively.
>
> I think we should call this SimpleEvidence (or HTTPEvidence) to
> distinguish it from any other sort of evidence.
>
> PROPOSED RESOLUTION B: Rename Evidence to SimpleEvidence
>
> b) Support for Property Terms distinct from PropertyRefs
>
> Rotan has discussed this in clear terms that I could not hope to match
> [1].
>
> In essence we have 2 proposals, Rotan's which is to overload the
> semantic of PropertyRef so it can be aspectless, and mine, which is to
> keep the PropertyName class and add a couple of factory methods - one to
> PropertyName and the other to SimplePropertyValue, so we don't have to
> refer to any inheritance relationships between them.
>
> PROPOSED RESOLUTION C ALERNATIVE 1: Add a method to SimpleService
> SimplePropertyValue  getPropertyValue(Evidence e, String aspect,
> SimplePropertyRef propertyRef) where the aspect parameter overrides
> whatever aspect is present in the propertyRef and throw exceptions
> appropriately
>
> PROPOSED RESOLUTION C ALTERNATIVE 2: PropertyName remains in the API and
> can be constructed from a PropertyRef by a factory method. A PropertyRef
> can be created from a PropertyName by a factory method naming the
> aspect.
>
>
> c) Additional proposed resolutions
>
> PROPOSED RESOLUTION D: In SimplePropertyRef rename getName to
> getPropertyName
>
> PROPOSED RESOLUTION E: In SimplePropertyRef rename getAspect to
> getAspectName
>
> PROPOSED RESOLUTION F: In SimpleService rename newPropertyRef methods to
> newSimplePropertyRef
>
>
> That's it folks - pls send +1s etc. to this list asap
>
> Jo
>
>
>
> .
>
>  

[Jo Rabin-2]

I see that both Rotan and you are looking for and elaboration of Resolution C(2):

Res.C(2) +1 to keep PropertyName, factory method, and use in SimplePropertyRef constructor.

For the sake of clarity, are you saying that the only constructor should be of this form or are you saying that you'd like that in addition. The first interpretation is inconsistent with the decision to provide overloaded methods that have only Strings.

Also,

> + the methods should be called putHeader and getHeader to avoid binding it
> to explictly to HTTP (why it cannot be used with WSP, for example)
> + the factory method in IDL should not receive any parameter i.e.
>

I thought that our intention was to provide normative means of using HTTP headers as evidence. I don't quite understand how one would implement something that allowed any Name / Value pair unless one knew what domain the name / value pair came from. For example, the name / value pairs might be property names and values. However, that's beyond the scope of what we agreed for the simple API. Implementations might choose to implement that sort of evidence but that's not our concern.

It seems to me that the intention is that ALL conforming implementations implement HTTP headers. We can certainly add to the list of name value pair types that must be supported but better make that suggestion very soon. Also make suggestion as to how to disambiguate HTTP headers as evdience from anything else.

> In the "possible normative" Java binding We could have a
>
> SimpleService.newEvidence(Map) that will allow to create an Evidence
> object that it is a copy of the key-value pairs of that Map, making
> key.toString() and value.toString()
>
> Note that I'm not in favour of using Map<String,String> as it would bound
> us to Java 1.5 and up and I would like to mantain compatibility with at
> least Java 1.4
>

Thanks for pointing that out. I agree. The proposed change is

HashMap<String, String> => Map

Jo

> -----Original Message-----
> From: jmcf@... [mailto:jmcf@...]
> Sent: 26 February 2008 10:21
> To: Jo Rabin
> Cc: public-ddwg@...
> Subject: Re: Final chance, for now, to offer opinion on Simple API [was
> Continuation of discussion from today's call]
>
> a)
>
>  Res.A   "conditioned +1" to factory method for evidence objects with the
> following punctualizations / amendments:
>
> + the methods should be called putHeader and getHeader to avoid binding it
> to explictly to HTTP (why it cannot be used with WSP, for example)
> + the factory method in IDL should not receive any parameter i.e.
>
> Evidence = SimpleService.newEvidence()
>
> In the "possible normative" Java binding We could have a
>
> SimpleService.newEvidence(Map) that will allow to create an Evidence
> object that it is a copy of the key-value pairs of that Map, making
> key.toString() and value.toString()
>
> Note that I'm not in favour of using Map<String,String> as it would bound
> us to Java 1.5 and up and I would like to mantain compatibility with at
> least Java 1.4
>
> Res.B +1 to Simple API having SimpleEvidence object (instead of generic
> Evidence)
>
> b)Res.C(1) -1 as the proposal was only made as a backup if we decided to
> remove PropertyName
>
>   Res.C(2) +1 to keep PropertyName, factory method, and use in
> SimplePropertyRef constructor.
>
> c)
>
>   D +1
>   E +1
>   F +1
>
> Best Wishes
>
> Jo Rabin escribió:
> > What follows is an edited version of what I sent yesterday. Apologies
> > for sending it to the wrong list initially.
> >
> > Aside from Rotan there have been no contributions. For the sake of
> > getting a document ready for the Face to Face I am going to start work
> > later this afternoon on a draft. In the absence of response I will take
> > it as a "+1" to all resolutions except C Alternative 1.
> >
> > Jo
> >
> > Contents:
> >
> > a) what is the signature of the Evidence interface?
> > b) how are underlying PropertyNames to be supported?
> > c) Misc renames for consistency
> >
> > Urgency:
> >
> > The important thing is to resolve this TODAY [that was yesterday] so we
> > can have a substantive draft for discussion in Seoul next week,
> > following which we will issue a First Public Working Draft which "with a
> > fair wind and a
> > following sea" (colloq. = with luck) will also be a Last Call working
> > draft.
> >
> > Other Tasks
> >
> > We also need to have debate on this list as to the wording of the
> > remaining sections of the document - especially Conformance.
> >
> > ---
> >
> > Let's fix the interface first.
> >
> > a) Evidence interface
> >
> > PROPOSED RESOLUTION A: The Evidence interface is
> >
> > void putHTTPHeader(String headerName, String value)
> > String getHTTPHeader(String headerName);
> > Boolean headerExists(String headerName);
> >
> > A factory method is added to SimpleService:
> >
> > Evidence newEvidence(HashMap<String, String> httpHeaders)
> >
> > The reasoning is as follows:
> >
> > The caller needs a way to put evidence into a known object in a
> > standardised way. The API must support HTTP Evidence in the form of
> > (case insensitive) HTTP Header Field name and (case sensitive) HTTP
> > Header Field value, both strings (ASCII stings, actually, but, er, let's
> > leave that point aside unless we have to).
> >
> > The retrieval methods are there so that an object created by some other
> > instantiation method can still be queried by the any implementation,
> > although that might not be very efficiently, it does allow inter
> > working.
> >
> > It is likely that most Java implementations will want to allow the
> > passing of a HashMap<String, String> derived directly e.g. from the jsp
> > infrastructure. However, in general this doesn't work as we can't rely
> > on support of a HashMap<String, String> structure in other environments
> > / languages, so the factory method will probably look different in the
> > IDL.
> >
> > It ought also to be a documentation and conformance point that HTTP
> > Header Field names are treated case insensitively.
> >
> > I think we should call this SimpleEvidence (or HTTPEvidence) to
> > distinguish it from any other sort of evidence.
> >
> > PROPOSED RESOLUTION B: Rename Evidence to SimpleEvidence
> >
> > b) Support for Property Terms distinct from PropertyRefs
> >
> > Rotan has discussed this in clear terms that I could not hope to match
> > [1].
> >
> > In essence we have 2 proposals, Rotan's which is to overload the
> > semantic of PropertyRef so it can be aspectless, and mine, which is to
> > keep the PropertyName class and add a couple of factory methods - one to
> > PropertyName and the other to SimplePropertyValue, so we don't have to
> > refer to any inheritance relationships between them.
> >
> > PROPOSED RESOLUTION C ALERNATIVE 1: Add a method to SimpleService
> > SimplePropertyValue  getPropertyValue(Evidence e, String aspect,
> > SimplePropertyRef propertyRef) where the aspect parameter overrides
> > whatever aspect is present in the propertyRef and throw exceptions
> > appropriately
> >
> > PROPOSED RESOLUTION C ALTERNATIVE 2: PropertyName remains in the API and
> > can be constructed from a PropertyRef by a factory method. A PropertyRef
> > can be created from a PropertyName by a factory method naming the
> > aspect.
> >
> >
> > c) Additional proposed resolutions
> >
> > PROPOSED RESOLUTION D: In SimplePropertyRef rename getName to
> > getPropertyName
> >
> > PROPOSED RESOLUTION E: In SimplePropertyRef rename getAspect to
> > getAspectName
> >
> > PROPOSED RESOLUTION F: In SimpleService rename newPropertyRef methods to
> > newSimplePropertyRef
> >
> >
> > That's it folks - pls send +1s etc. to this list asap
> >
> > Jo
> >
> >
> >
> > .
> >
> >

[Rafael Casero]

PROPOSED RESOLUTION A: +1

PROPOSED RESOLUTION B: +1

PROPOSED RESOLUTION C ALTERNATIVE 1: -1
PROPOSED RESOLUTION C ALTERNATIVE 2: +1

PROPOSED RESOLUTION D: +1
PROPOSED RESOLUTION E: +1
PROPOSED RESOLUTION F: +1



Rafa


-------- Mensaje Original --------

What follows is an edited version of what I sent yesterday. Apologies
for sending it to the wrong list initially.

Aside from Rotan there have been no contributions. For the sake of
getting a document ready for the Face to Face I am going to start work
later this afternoon on a draft. In the absence of response I will take
it as a "+1" to all resolutions except C Alternative 1.

Jo

Contents:

a) what is the signature of the Evidence interface?
b) how are underlying PropertyNames to be supported?
c) Misc renames for consistency

Urgency:

The important thing is to resolve this TODAY [that was yesterday] so we
can have a substantive draft for discussion in Seoul next week,
following which we will issue a First Public Working Draft which "with a
fair wind and a
following sea" (colloq. = with luck) will also be a Last Call working
draft.

Other Tasks

We also need to have debate on this list as to the wording of the
remaining sections of the document - especially Conformance.

---

Let's fix the interface first.

a) Evidence interface

PROPOSED RESOLUTION A: The Evidence interface is 

void putHTTPHeader(String headerName, String value) 
String getHTTPHeader(String headerName);
Boolean headerExists(String headerName);

A factory method is added to SimpleService:

Evidence newEvidence(HashMap<String, String> httpHeaders)

The reasoning is as follows:

The caller needs a way to put evidence into a known object in a
standardised way. The API must support HTTP Evidence in the form of
(case insensitive) HTTP Header Field name and (case sensitive) HTTP
Header Field value, both strings (ASCII stings, actually, but, er, let's
leave that point aside unless we have to).

The retrieval methods are there so that an object created by some other
instantiation method can still be queried by the any implementation,
although that might not be very efficiently, it does allow inter
working.

It is likely that most Java implementations will want to allow the
passing of a HashMap<String, String> derived directly e.g. from the jsp
infrastructure. However, in general this doesn't work as we can't rely
on support of a HashMap<String, String> structure in other environments
/ languages, so the factory method will probably look different in the
IDL.

It ought also to be a documentation and conformance point that HTTP
Header Field names are treated case insensitively.

I think we should call this SimpleEvidence (or HTTPEvidence) to
distinguish it from any other sort of evidence.

PROPOSED RESOLUTION B: Rename Evidence to SimpleEvidence

b) Support for Property Terms distinct from PropertyRefs

Rotan has discussed this in clear terms that I could not hope to match
[1].

In essence we have 2 proposals, Rotan's which is to overload the
semantic of PropertyRef so it can be aspectless, and mine, which is to
keep the PropertyName class and add a couple of factory methods - one to
PropertyName and the other to SimplePropertyValue, so we don't have to
refer to any inheritance relationships between them.

PROPOSED RESOLUTION C ALERNATIVE 1: Add a method to SimpleService
SimplePropertyValue  getPropertyValue(Evidence e, String aspect,
SimplePropertyRef propertyRef) where the aspect parameter overrides
whatever aspect is present in the propertyRef and throw exceptions
appropriately

PROPOSED RESOLUTION C ALTERNATIVE 2: PropertyName remains in the API and
can be constructed from a PropertyRef by a factory method. A PropertyRef
can be created from a PropertyName by a factory method naming the
aspect.


c) Additional proposed resolutions

PROPOSED RESOLUTION D: In SimplePropertyRef rename getName to
getPropertyName

PROPOSED RESOLUTION E: In SimplePropertyRef rename getAspect to
getAspectName 

PROPOSED RESOLUTION F: In SimpleService rename newPropertyRef methods to
newSimplePropertyRef   


That's it folks - pls send +1s etc. to this list asap

Jo




  

[Rotan Hanrahan]

Res.C(2) : For clarity, I would like it in addition. This would be
consistent with the provision of overloaded methods that only have
strings and would be used conveniently in some simple use cases.

---R

-----Original Message-----
From: public-ddwg-request@... [mailto:public-ddwg-request@...] On
Behalf Of Jo Rabin
Sent: 26 February 2008 10:45
To: jmcf@...
Cc: public-ddwg@...
Subject: RE: Final chance, for now, to offer opinion on Simple API [was
Continuation of discussion from today's call]


I see that both Rotan and you are looking for and elaboration of
Resolution C(2):

Res.C(2) +1 to keep PropertyName, factory method, and use in
SimplePropertyRef constructor.

For the sake of clarity, are you saying that the only constructor should
be of this form or are you saying that you'd like that in addition. The
first interpretation is inconsistent with the decision to provide
overloaded methods that have only Strings.



[...]

[Rotan Hanrahan]

We're back to the extensibility question surrounding the use of the
Evidence interface. Let me see if I can summarise:

1. We want the Simple API to support out-of-the-box the use of HTTP
headers as contextual evidence.

2. Some of us want to be able to extend the evidence to support more
complex data, while having a minimal impact on the Simple API.

3. It is possible that we could have general support for message
headers, rather than insisting that the headers must come from a HTTP
interaction with a client. But in this case we would need a way in the
evidence to indicate that we were dealing with HTTP or something else.

4. Even if we limit ourselves to just HTTP, individual implementations
will probably want to extend the support for evidence to other sources
with minimal impact on the API.

So, let's suppose that the Simple API only supports HTTP headers. Let's
also suppose that the SimpleEvidence class has putHeader/getHeader
methods (rather than putHTTPHeader/getHTTPHeader).

Now le'ts suppose that a custom implementation wants to provide more
than the Simple API, so that WSP can be supported. This custom
implementation is free to provide an additional evidence factory:
  Evidence newWSPEvidence(Map)

Note that it still provides an Evidence result, but also note that
hidden inside the returned instance is a flag that says "these headers
are WSP".

Later, the evidence instance is passed as a parameter in one of the
query methods. As this is all happening in the same implementation, we
can assume that the query knows to look inside the evidence for the
hidden "these headers are WSP".

So, with this extra custom factory, we have extended the Simple API to
support WSP and none of the rest of the Simple API has been affected in
any way.

Because of this non-destructive possibility of extending the Simple API
in custom solutions, I'd agree to the suggested names of putHeader and
getHeader. Of course, it would be quite reasonable to demand that if the
Simple API factory "newSimpleEvidence(Map)" is used, then these
putHeader/getHeader methods *must* be interpreted to mean HTTP headers.
If you choose to use a custom factory, those methods can refer to
anything you like.

In a nutshell: off-the-shelf, Evidence supports HTTP headers, and if an
instance of Evidence is produced via the
SimpleService.newSimpleEvidence(Map) then the instance must only deal
with HTTP headers.

This leads me to think perhaps that the name of the factory needs to be
changed to newHTTPEvidence(Map), while the interface name itself can
still be SimpleEvidence.

---Rotan.



-----Original Message-----
From: public-ddwg-request@... [mailto:public-ddwg-request@...] On
Behalf Of Jo Rabin
Sent: 26 February 2008 10:45
To: jmcf@...
Cc: public-ddwg@...
Subject: RE: Final chance, for now, to offer opinion on Simple API [was
Continuation of discussion from today's call]

[...]

Also,

> + the methods should be called putHeader and getHeader to avoid
binding it
> to explictly to HTTP (why it cannot be used with WSP, for example)
> + the factory method in IDL should not receive any parameter i.e.
>

I thought that our intention was to provide normative means of using
HTTP headers as evidence. I don't quite understand how one would
implement something that allowed any Name / Value pair unless one knew
what domain the name / value pair came from. For example, the name /
value pairs might be property names and values. However, that's beyond
the scope of what we agreed for the simple API. Implementations might
choose to implement that sort of evidence but that's not our concern.

It seems to me that the intention is that ALL conforming implementations
implement HTTP headers. We can certainly add to the list of name value
pair types that must be supported but better make that suggestion very
soon. Also make suggestion as to how to disambiguate HTTP headers as
evdience from anything else.

[...]

[Rotan Hanrahan]

Minor typo correction:

= = = =
Now let's suppose that a custom implementation wants to provide more
than the Simple API, so that WSP can be supported. This custom
implementation is free to provide an additional evidence factory:
  SimpleEvidence newWSPEvidence(Map)

Note that it still provides a SimpleEvidence result, but also note that
hidden inside the returned instance is a flag that says "these headers
are WSP".
= = = =

---Rotan



-----Original Message-----
From: public-ddwg-request@... [mailto:public-ddwg-request@...] On
Behalf Of Rotan Hanrahan
Sent: 26 February 2008 12:11
To: public-ddwg@...
Subject: RE: Final chance, for now, to offer opinion on Simple API [was
Continuation of discussion from today's call]


We're back to the extensibility question surrounding the use of the
Evidence interface. Let me see if I can summarise:

1. We want the Simple API to support out-of-the-box the use of HTTP
headers as contextual evidence.

2. Some of us want to be able to extend the evidence to support more
complex data, while having a minimal impact on the Simple API.

3. It is possible that we could have general support for message
headers, rather than insisting that the headers must come from a HTTP
interaction with a client. But in this case we would need a way in the
evidence to indicate that we were dealing with HTTP or something else.

4. Even if we limit ourselves to just HTTP, individual implementations
will probably want to extend the support for evidence to other sources
with minimal impact on the API.

So, let's suppose that the Simple API only supports HTTP headers. Let's
also suppose that the SimpleEvidence class has putHeader/getHeader
methods (rather than putHTTPHeader/getHTTPHeader).

Now le'ts suppose that a custom implementation wants to provide more
than the Simple API, so that WSP can be supported. This custom
implementation is free to provide an additional evidence factory:
  Evidence newWSPEvidence(Map)

Note that it still provides an Evidence result, but also note that
hidden inside the returned instance is a flag that says "these headers
are WSP".

Later, the evidence instance is passed as a parameter in one of the
query methods. As this is all happening in the same implementation, we
can assume that the query knows to look inside the evidence for the
hidden "these headers are WSP".

So, with this extra custom factory, we have extended the Simple API to
support WSP and none of the rest of the Simple API has been affected in
any way.

Because of this non-destructive possibility of extending the Simple API
in custom solutions, I'd agree to the suggested names of putHeader and
getHeader. Of course, it would be quite reasonable to demand that if the
Simple API factory "newSimpleEvidence(Map)" is used, then these
putHeader/getHeader methods *must* be interpreted to mean HTTP headers.
If you choose to use a custom factory, those methods can refer to
anything you like.

In a nutshell: off-the-shelf, Evidence supports HTTP headers, and if an
instance of Evidence is produced via the
SimpleService.newSimpleEvidence(Map) then the instance must only deal
with HTTP headers.

This leads me to think perhaps that the name of the factory needs to be
changed to newHTTPEvidence(Map), while the interface name itself can
still be SimpleEvidence.

---Rotan.



-----Original Message-----
From: public-ddwg-request@... [mailto:public-ddwg-request@...] On
Behalf Of Jo Rabin
Sent: 26 February 2008 10:45
To: jmcf@...
Cc: public-ddwg@...
Subject: RE: Final chance, for now, to offer opinion on Simple API [was
Continuation of discussion from today's call]

[...]

Also,

> + the methods should be called putHeader and getHeader to avoid
binding it
> to explictly to HTTP (why it cannot be used with WSP, for example)
> + the factory method in IDL should not receive any parameter i.e.
>

I thought that our intention was to provide normative means of using
HTTP headers as evidence. I don't quite understand how one would
implement something that allowed any Name / Value pair unless one knew
what domain the name / value pair came from. For example, the name /
value pairs might be property names and values. However, that's beyond
the scope of what we agreed for the simple API. Implementations might
choose to implement that sort of evidence but that's not our concern.

It seems to me that the intention is that ALL conforming implementations
implement HTTP headers. We can certainly add to the list of name value
pair types that must be supported but better make that suggestion very
soon. Also make suggestion as to how to disambiguate HTTP headers as
evdience from anything else.

[...]

[Ignacio Marin]

I shall answer this tonite.
I have barely had the chance to be connected since I left yesterday's
teleconference and my opinion will take some time to be expressed (it
will not be only +/-1 or 0).

I'll respond in some hours (4 hours more or less, as I will be in a
meeting outside CTIC and then in the University doing some teaching) and
I hope you'll accept it as being sent today O:-)

Regards,

Nacho


-----Mensaje original-----
De: public-ddwg-request@... [mailto:public-ddwg-request@...] En
nombre de Jo Rabin
Enviado el: martes, 26 de febrero de 2008 8:53
Para: public-ddwg@...
Asunto: Final chance, for now, to offer opinion on Simple API [was
Continuation of discussion from today's call]


What follows is an edited version of what I sent yesterday. Apologies
for sending it to the wrong list initially.

Aside from Rotan there have been no contributions. For the sake of
getting a document ready for the Face to Face I am going to start work
later this afternoon on a draft. In the absence of response I will take
it as a "+1" to all resolutions except C Alternative 1.

Jo

Contents:

a) what is the signature of the Evidence interface?
b) how are underlying PropertyNames to be supported?
c) Misc renames for consistency

Urgency:

The important thing is to resolve this TODAY [that was yesterday] so we
can have a substantive draft for discussion in Seoul next week,
following which we will issue a First Public Working Draft which "with a
fair wind and a
following sea" (colloq. = with luck) will also be a Last Call working
draft.

Other Tasks

We also need to have debate on this list as to the wording of the
remaining sections of the document - especially Conformance.

---

Let's fix the interface first.

a) Evidence interface

PROPOSED RESOLUTION A: The Evidence interface is

void putHTTPHeader(String headerName, String value)
String getHTTPHeader(String headerName);
Boolean headerExists(String headerName);

A factory method is added to SimpleService:

Evidence newEvidence(HashMap<String, String> httpHeaders)

The reasoning is as follows:

The caller needs a way to put evidence into a known object in a
standardised way. The API must support HTTP Evidence in the form of
(case insensitive) HTTP Header Field name and (case sensitive) HTTP
Header Field value, both strings (ASCII stings, actually, but, er, let's
leave that point aside unless we have to).

The retrieval methods are there so that an object created by some other
instantiation method can still be queried by the any implementation,
although that might not be very efficiently, it does allow inter
working.

It is likely that most Java implementations will want to allow the
passing of a HashMap<String, String> derived directly e.g. from the jsp
infrastructure. However, in general this doesn't work as we can't rely
on support of a HashMap<String, String> structure in other environments
/ languages, so the factory method will probably look different in the
IDL.

It ought also to be a documentation and conformance point that HTTP
Header Field names are treated case insensitively.

I think we should call this SimpleEvidence (or HTTPEvidence) to
distinguish it from any other sort of evidence.

PROPOSED RESOLUTION B: Rename Evidence to SimpleEvidence

b) Support for Property Terms distinct from PropertyRefs

Rotan has discussed this in clear terms that I could not hope to match
[1].

In essence we have 2 proposals, Rotan's which is to overload the
semantic of PropertyRef so it can be aspectless, and mine, which is to
keep the PropertyName class and add a couple of factory methods - one to
PropertyName and the other to SimplePropertyValue, so we don't have to
refer to any inheritance relationships between them.

PROPOSED RESOLUTION C ALERNATIVE 1: Add a method to SimpleService
SimplePropertyValue  getPropertyValue(Evidence e, String aspect,
SimplePropertyRef propertyRef) where the aspect parameter overrides
whatever aspect is present in the propertyRef and throw exceptions
appropriately

PROPOSED RESOLUTION C ALTERNATIVE 2: PropertyName remains in the API and
can be constructed from a PropertyRef by a factory method. A PropertyRef
can be created from a PropertyName by a factory method naming the
aspect.


c) Additional proposed resolutions

PROPOSED RESOLUTION D: In SimplePropertyRef rename getName to
getPropertyName

PROPOSED RESOLUTION E: In SimplePropertyRef rename getAspect to
getAspectName

PROPOSED RESOLUTION F: In SimpleService rename newPropertyRef methods to
newSimplePropertyRef  


That's it folks - pls send +1s etc. to this list asap

Jo

[Jo Rabin-2]

I'm about to post a link to some Java which I think represents group
consensus, so if you could give your comments on that, that would be
great.

Thanks


> -----Original Message-----
> From: Ignacio Marin [mailto:ignacio.marin@...]
> Sent: 26 February 2008 14:45
> To: Jo Rabin; public-ddwg@...
> Subject: RE: Final chance, for now, to offer opinion on Simple API
[was
> Continuation of discussion from today's call]
>
> I shall answer this tonite.
> I have barely had the chance to be connected since I left yesterday's
> teleconference and my opinion will take some time to be expressed (it
> will not be only +/-1 or 0).
>
> I'll respond in some hours (4 hours more or less, as I will be in a
> meeting outside CTIC and then in the University doing some teaching)
and

> I hope you'll accept it as being sent today O:-)
>
> Regards,
>
> Nacho
>
>
> -----Mensaje original-----
> De: public-ddwg-request@... [mailto:public-ddwg-request@...] En
> nombre de Jo Rabin
> Enviado el: martes, 26 de febrero de 2008 8:53
> Para: public-ddwg@...
> Asunto: Final chance, for now, to offer opinion on Simple API [was
> Continuation of discussion from today's call]
>
>
> What follows is an edited version of what I sent yesterday. Apologies
> for sending it to the wrong list initially.
>
> Aside from Rotan there have been no contributions. For the sake of
> getting a document ready for the Face to Face I am going to start work
> later this afternoon on a draft. In the absence of response I will

take

> it as a "+1" to all resolutions except C Alternative 1.
>
> Jo
>
> Contents:
>
> a) what is the signature of the Evidence interface?
> b) how are underlying PropertyNames to be supported?
> c) Misc renames for consistency
>
> Urgency:
>
> The important thing is to resolve this TODAY [that was yesterday] so

we
> can have a substantive draft for discussion in Seoul next week,
> following which we will issue a First Public Working Draft which "with
a

> fair wind and a
> following sea" (colloq. = with luck) will also be a Last Call working
> draft.
>
> Other Tasks
>
> We also need to have debate on this list as to the wording of the
> remaining sections of the document - especially Conformance.
>
> ---
>
> Let's fix the interface first.
>
> a) Evidence interface
>
> PROPOSED RESOLUTION A: The Evidence interface is
>
> void putHTTPHeader(String headerName, String value)
> String getHTTPHeader(String headerName);
> Boolean headerExists(String headerName);
>
> A factory method is added to SimpleService:
>
> Evidence newEvidence(HashMap<String, String> httpHeaders)
>
> The reasoning is as follows:
>
> The caller needs a way to put evidence into a known object in a
> standardised way. The API must support HTTP Evidence in the form of
> (case insensitive) HTTP Header Field name and (case sensitive) HTTP
> Header Field value, both strings (ASCII stings, actually, but, er,

let's
> leave that point aside unless we have to).
>
> The retrieval methods are there so that an object created by some
other
> instantiation method can still be queried by the any implementation,
> although that might not be very efficiently, it does allow inter
> working.
>
> It is likely that most Java implementations will want to allow the
> passing of a HashMap<String, String> derived directly e.g. from the
jsp
> infrastructure. However, in general this doesn't work as we can't rely
> on support of a HashMap<String, String> structure in other
environments

> / languages, so the factory method will probably look different in the
> IDL.
>
> It ought also to be a documentation and conformance point that HTTP
> Header Field names are treated case insensitively.
>
> I think we should call this SimpleEvidence (or HTTPEvidence) to
> distinguish it from any other sort of evidence.
>
> PROPOSED RESOLUTION B: Rename Evidence to SimpleEvidence
>
> b) Support for Property Terms distinct from PropertyRefs
>
> Rotan has discussed this in clear terms that I could not hope to match
> [1].
>
> In essence we have 2 proposals, Rotan's which is to overload the
> semantic of PropertyRef so it can be aspectless, and mine, which is to
> keep the PropertyName class and add a couple of factory methods - one

to

> PropertyName and the other to SimplePropertyValue, so we don't have to
> refer to any inheritance relationships between them.
>
> PROPOSED RESOLUTION C ALERNATIVE 1: Add a method to SimpleService
> SimplePropertyValue  getPropertyValue(Evidence e, String aspect,
> SimplePropertyRef propertyRef) where the aspect parameter overrides
> whatever aspect is present in the propertyRef and throw exceptions
> appropriately
>
> PROPOSED RESOLUTION C ALTERNATIVE 2: PropertyName remains in the API

and
> can be constructed from a PropertyRef by a factory method. A
PropertyRef

> can be created from a PropertyName by a factory method naming the
> aspect.
>
>
> c) Additional proposed resolutions
>
> PROPOSED RESOLUTION D: In SimplePropertyRef rename getName to
> getPropertyName
>
> PROPOSED RESOLUTION E: In SimplePropertyRef rename getAspect to
> getAspectName
>
> PROPOSED RESOLUTION F: In SimpleService rename newPropertyRef methods

to
> newSimplePropertyRef
>
>
> That's it folks - pls send +1s etc. to this list asap
>
> Jo
>
>

[Ignacio Marin]

Here I go with my response which is shorter than I promised, as I was going to comment about stuff already solved this afternoon like the naming inconsistency in the SimpleService interface.

My response is sometimes not just a +1 or -1, sorry

a) Evidence interface:

For me, although it may sound like breaking our Simple... naming approach, the interface should be called HTTPEvidence in order to make it clearer to developers.

I'm OK with...
> void putHTTPHeader(String headerName, String value)
> String getHTTPHeader(String headerName);
> Boolean headerExists(String headerName);

... although if the interface was HTTPEvidence, we might avoid so many HTTP in the names of the methods. By the way, for naming consistency, headerExists should be HTTPHeaderExists.

This is clearer to me than the alternative of having newHTTPEvidence(Map map) and leave it up to the implementation on how to build the Map.

I'd create a new HTTPEvidence() -no args- and then I would putHTTPHeader(name, value) as many times as I want. It may be uglier than the newHTTPEvidence(Map map), but it is easier to understand for programmers and more language agnostic.

José commented: "Note that I'm not in favour of using Map<String,String> as it would bind us to Java 1.5 and up and I would like to mantain compatibility with at least Java 1.4"... In general, I am in favour of doing things as general as possible and avoid shortcuts for a specific language, although it may create a given language binding of the API a bit more complex than it would have been by using shortcuts. I am worried about these shortcuts stopping interoperability (Perl software consuming information from a Java implementation of the DDR API).

So...

PROPOSED RESOLUTION A: I'd like a newEvidence method with no args and putHeader, getHeader and headerExists.

PROPOSED RESOLUTION B: +0.5 to Evidence-->SimpleEvidence. Let's be more direct by changing Evidence to HTTPEvidence (although we break our Simple... naming convention, as there is a more well known name than Simple).

b) Support for Property Terms distinct from PropertyRefs

PROPOSED RESOLUTION C ALERNATIVE 1: It sounds interesting.. it can be understood quickly and it is easy to use but

PROPOSED RESOLUTION C ALERNATIVE 2: we should be consistent to the PropertyName and PropertyRef concepts, so +1 to this and -1 to the latter.

> c) Additional proposed resolutions
>
> PROPOSED RESOLUTION D: In SimplePropertyRef rename getName to
> getPropertyName
>
> PROPOSED RESOLUTION E: In SimplePropertyRef rename getAspect to
> getAspectName
>
> PROPOSED RESOLUTION F: In SimpleService rename newPropertyRef methods
to
> newSimplePropertyRef

Res D: +1, it is easier to understand the purpose of the method.
Res E: +1, for the same reason
Res F: I concur, although it might make sense in order to be consequent with other naming decisions. Particularly, I find the PropertyRef name a bit cryptic but no other good options come to my mind (PropertyAspectBinding sounds too long, but it is a bit more clear).

I must say that sometimes it is difficult for me to balance between the ease-of-use and formality when choosing alternatives in the design of the API and I find myself voting for easiness in a situation while trying to keep things formal in another :-(

Regards and sorry for the delay on my answer,

Nacho

-----Mensaje original-----
De: Jo Rabin [mailto:jrabin@...]
Enviado el: martes, 26 de febrero de 2008 15:47
Para: Ignacio Marin; public-ddwg@...
Asunto: RE: Final chance, for now, to offer opinion on Simple API [was Continuation of discussion from today's call]

I'm about to post a link to some Java which I think represents group
consensus, so if you could give your comments on that, that would be
great.

Thanks


> -----Original Message-----
> From: Ignacio Marin [mailto:ignacio.marin@...]
> Sent: 26 February 2008 14:45
> To: Jo Rabin; public-ddwg@...
> Subject: RE: Final chance, for now, to offer opinion on Simple API
[was
> Continuation of discussion from today's call]
>
> I shall answer this tonite.
> I have barely had the chance to be connected since I left yesterday's
> teleconference and my opinion will take some time to be expressed (it
> will not be only +/-1 or 0).
>
> I'll respond in some hours (4 hours more or less, as I will be in a
> meeting outside CTIC and then in the University doing some teaching)
and

> I hope you'll accept it as being sent today O:-)
>
> Regards,
>
> Nacho
>
>
> -----Mensaje original-----
> De: public-ddwg-request@... [mailto:public-ddwg-request@...] En
> nombre de Jo Rabin
> Enviado el: martes, 26 de febrero de 2008 8:53
> Para: public-ddwg@...
> Asunto: Final chance, for now, to offer opinion on Simple API [was
> Continuation of discussion from today's call]
>
>
> What follows is an edited version of what I sent yesterday. Apologies
> for sending it to the wrong list initially.
>
> Aside from Rotan there have been no contributions. For the sake of
> getting a document ready for the Face to Face I am going to start work
> later this afternoon on a draft. In the absence of response I will

take

> it as a "+1" to all resolutions except C Alternative 1.
>
> Jo
>
> Contents:
>
> a) what is the signature of the Evidence interface?
> b) how are underlying PropertyNames to be supported?
> c) Misc renames for consistency
>
> Urgency:
>
> The important thing is to resolve this TODAY [that was yesterday] so

we
> can have a substantive draft for discussion in Seoul next week,
> following which we will issue a First Public Working Draft which "with
a

> fair wind and a
> following sea" (colloq. = with luck) will also be a Last Call working
> draft.
>
> Other Tasks
>
> We also need to have debate on this list as to the wording of the
> remaining sections of the document - especially Conformance.
>
> ---
>
> Let's fix the interface first.
>
> a) Evidence interface
>
> PROPOSED RESOLUTION A: The Evidence interface is
>
> void putHTTPHeader(String headerName, String value)
> String getHTTPHeader(String headerName);
> Boolean headerExists(String headerName);
>
> A factory method is added to SimpleService:
>
> Evidence newEvidence(HashMap<String, String> httpHeaders)
>
> The reasoning is as follows:
>
> The caller needs a way to put evidence into a known object in a
> standardised way. The API must support HTTP Evidence in the form of
> (case insensitive) HTTP Header Field name and (case sensitive) HTTP
> Header Field value, both strings (ASCII stings, actually, but, er,

let's
> leave that point aside unless we have to).
>
> The retrieval methods are there so that an object created by some
other
> instantiation method can still be queried by the any implementation,
> although that might not be very efficiently, it does allow inter
> working.
>
> It is likely that most Java implementations will want to allow the
> passing of a HashMap<String, String> derived directly e.g. from the
jsp
> infrastructure. However, in general this doesn't work as we can't rely
> on support of a HashMap<String, String> structure in other
environments

> / languages, so the factory method will probably look different in the
> IDL.
>
> It ought also to be a documentation and conformance point that HTTP
> Header Field names are treated case insensitively.
>
> I think we should call this SimpleEvidence (or HTTPEvidence) to
> distinguish it from any other sort of evidence.
>
> PROPOSED RESOLUTION B: Rename Evidence to SimpleEvidence
>
> b) Support for Property Terms distinct from PropertyRefs
>
> Rotan has discussed this in clear terms that I could not hope to match
> [1].
>
> In essence we have 2 proposals, Rotan's which is to overload the
> semantic of PropertyRef so it can be aspectless, and mine, which is to
> keep the PropertyName class and add a couple of factory methods - one

to

> PropertyName and the other to SimplePropertyValue, so we don't have to
> refer to any inheritance relationships between them.
>
> PROPOSED RESOLUTION C ALERNATIVE 1: Add a method to SimpleService
> SimplePropertyValue  getPropertyValue(Evidence e, String aspect,
> SimplePropertyRef propertyRef) where the aspect parameter overrides
> whatever aspect is present in the propertyRef and throw exceptions
> appropriately
>
> PROPOSED RESOLUTION C ALTERNATIVE 2: PropertyName remains in the API

and
> can be constructed from a PropertyRef by a factory method. A
PropertyRef

> can be created from a PropertyName by a factory method naming the
> aspect.
>
>
> c) Additional proposed resolutions
>
> PROPOSED RESOLUTION D: In SimplePropertyRef rename getName to
> getPropertyName
>
> PROPOSED RESOLUTION E: In SimplePropertyRef rename getAspect to
> getAspectName
>
> PROPOSED RESOLUTION F: In SimpleService rename newPropertyRef methods

to
> newSimplePropertyRef
>
>
> That's it folks - pls send +1s etc. to this list asap
>
> Jo
>
>

[Rotan Hanrahan]

The Evidence/SimpleEvidence/HTTPEvidence naming question continues...
 
I will use Java as an example to do some exploration of the issue, which might help other people who are thinking about this too.
 
In Java, the TreeMap class [1] supports the Map interface [2]. The Map interface has a size() method. The method is not called sizeOfTree() because then the interface would be locked to a particular class and would lose its generality.
 
In Java, the Hashtable class [3] supports the Map interface [2]. The Map interface has a size() method. The method is not called sizeOfHashtable() because then the interface would be locked to a particular class and would lose its generality.
 
In Java, the Attributes class [4] supports the Map interface.... ok you get the picture by now.
 
The interface is supposed to be general if there is a possibility of re-use. In the case of the Simple API we have already had discussion where we recognise that some implementations are likely to want to support better forms of evidence. So it seems that, like the Java Map interface, there should be a general interface for Evidence. Even if this is just to identify what can be passed as a parameter in a query method.
 
Separate factory methods can produce instances of classes that implement the Evidence class, and these can be instances of things that represent HTTP headers, or things that represent other identifying data.
 
But, I hear you say, this is surely just the "Simple" API, so why does it matter if its called Evidence, SimpleEvidence or HTTPEvidence?
 
It might matter because any implementation that tries to offer anything more than HTTP header evidence will still have to pass the evidence objects to the query methods as if they were supporting "HTTPEvidence", when in fact they are not HTTP evidence at all. They are just "evidence". So a generic interface name would be better.
 
However, there is an alternative view.
 
If a custom implementation provides a custom factory in the SimpleService to produce an instance of a custom SuperEvidence class, then it should be possible for this implementation to also provide custom overloaded query methods that take a SuperEvidence object instead of an instance of some class that implements the HTTPEvidence interface. Given that the SuperEvidence class is not dealing with HTTP headers, there's no reason for it to implement the HTTPEvidence interface, so we don't cause any polymorphic ambiguity. Plus, the Simple API is now a proper subset of the enhanced custom implementation, so the custom implemention can still claim to be conformant (so long as nobody uses the enhanced features).
 
So, my position is that I don't really mind if the Simple API uses an interface called Evidence or one called HTTPEvidence. If the former, then any enhancements I offer will also implement Evidence though I'll add a few more interfaces for good measure. If we decide to call the interface HTTPEvidence, then any enhancements I offer will implement their own evidence interfaces and I'll overload the getPropertyValue* methods. In both cases, I'll also be providing custom factories.
 
So I'm now "0" on this question :)
 
 
---Rotan
 
 
[1] http://java.sun.com/j2se/1.4.2/docs/api/java/util/TreeMap.html
[2] http://java.sun.com/j2se/1.4.2/docs/api/java/util/Map.html
[3] http://java.sun.com/j2se/1.4.2/docs/api/java/util/Hashtable.html
[4] http://java.sun.com/j2se/1.4.2/docs/api/java/util/jar/Attributes.html
 
 

________________________________

From: public-ddwg-request@... on behalf of Ignacio Marin
Sent: Tue 26/02/2008 22:57
To: Jo Rabin; public-ddwg@...
Subject: RE: Final chance, for now, to offer opinion on Simple API [was Continuation of discussion from today's call]




Here I go with my response which is shorter than I promised, as I was going to comment about stuff already solved this afternoon like the naming inconsistency in the SimpleService interface.

My response is sometimes not just a +1 or -1, sorry

a) Evidence interface:

For me, although it may sound like breaking our Simple... naming approach, the interface should be called HTTPEvidence in order to make it clearer to developers.

I'm OK with...
> void putHTTPHeader(String headerName, String value)
> String getHTTPHeader(String headerName);
> Boolean headerExists(String headerName);

... although if the interface was HTTPEvidence, we might avoid so many HTTP in the names of the methods. By the way, for naming consistency, headerExists should be HTTPHeaderExists.

This is clearer to me than the alternative of having newHTTPEvidence(Map map) and leave it up to the implementation on how to build the Map.

I'd create a new HTTPEvidence() -no args- and then I would putHTTPHeader(name, value) as many times as I want. It may be uglier than the newHTTPEvidence(Map map), but it is easier to understand for programmers and more language agnostic.

José commented: "Note that I'm not in favour of using Map<String,String> as it would bind us to Java 1.5 and up and I would like to mantain compatibility with at least Java 1.4"... In general, I am in favour of doing things as general as possible and avoid shortcuts for a specific language, although it may create a given language binding of the API a bit more complex than it would have been by using shortcuts. I am worried about these shortcuts stopping interoperability (Perl software consuming information from a Java implementation of the DDR API).

So...

PROPOSED RESOLUTION A: I'd like a newEvidence method with no args and putHeader, getHeader and headerExists.

PROPOSED RESOLUTION B: +0.5 to Evidence-->SimpleEvidence. Let's be more direct by changing Evidence to HTTPEvidence (although we break our Simple... naming convention, as there is a more well known name than Simple).

b) Support for Property Terms distinct from PropertyRefs

PROPOSED RESOLUTION C ALERNATIVE 1: It sounds interesting.. it can be understood quickly and it is easy to use but

PROPOSED RESOLUTION C ALERNATIVE 2: we should be consistent to the PropertyName and PropertyRef concepts, so +1 to this and -1 to the latter.

> c) Additional proposed resolutions
>
> PROPOSED RESOLUTION D: In SimplePropertyRef rename getName to
> getPropertyName
>
> PROPOSED RESOLUTION E: In SimplePropertyRef rename getAspect to
> getAspectName
>
> PROPOSED RESOLUTION F: In SimpleService rename newPropertyRef methods
to
> newSimplePropertyRef

Res D: +1, it is easier to understand the purpose of the method.
Res E: +1, for the same reason
Res F: I concur, although it might make sense in order to be consequent with other naming decisions. Particularly, I find the PropertyRef name a bit cryptic but no other good options come to my mind (PropertyAspectBinding sounds too long, but it is a bit more clear).

I must say that sometimes it is difficult for me to balance between the ease-of-use and formality when choosing alternatives in the design of the API and I find myself voting for easiness in a situation while trying to keep things formal in another :-(

Regards and sorry for the delay on my answer,

Nacho

-----Mensaje original-----
De: Jo Rabin [mailto:jrabin@...]
Enviado el: martes, 26 de febrero de 2008 15:47
Para: Ignacio Marin; public-ddwg@...
Asunto: RE: Final chance, for now, to offer opinion on Simple API [was Continuation of discussion from today's call]

I'm about to post a link to some Java which I think represents group
consensus, so if you could give your comments on that, that would be
great.

Thanks


> -----Original Message-----
> From: Ignacio Marin [mailto:ignacio.marin@...]
> Sent: 26 February 2008 14:45
> To: Jo Rabin; public-ddwg@...
> Subject: RE: Final chance, for now, to offer opinion on Simple API
[was
> Continuation of discussion from today's call]
>
> I shall answer this tonite.
> I have barely had the chance to be connected since I left yesterday's
> teleconference and my opinion will take some time to be expressed (it
> will not be only +/-1 or 0).
>
> I'll respond in some hours (4 hours more or less, as I will be in a
> meeting outside CTIC and then in the University doing some teaching)
and

> I hope you'll accept it as being sent today O:-)
>
> Regards,
>
> Nacho
>
>
> -----Mensaje original-----
> De: public-ddwg-request@... [mailto:public-ddwg-request@...] En
> nombre de Jo Rabin
> Enviado el: martes, 26 de febrero de 2008 8:53
> Para: public-ddwg@...
> Asunto: Final chance, for now, to offer opinion on Simple API [was
> Continuation of discussion from today's call]
>
>
> What follows is an edited version of what I sent yesterday. Apologies
> for sending it to the wrong list initially.
>
> Aside from Rotan there have been no contributions. For the sake of
> getting a document ready for the Face to Face I am going to start work
> later this afternoon on a draft. In the absence of response I will

take

> it as a "+1" to all resolutions except C Alternative 1.
>
> Jo
>
> Contents:
>
> a) what is the signature of the Evidence interface?
> b) how are underlying PropertyNames to be supported?
> c) Misc renames for consistency
>
> Urgency:
>
> The important thing is to resolve this TODAY [that was yesterday] so

we
> can have a substantive draft for discussion in Seoul next week,
> following which we will issue a First Public Working Draft which "with
a

> fair wind and a
> following sea" (colloq. = with luck) will also be a Last Call working
> draft.
>
> Other Tasks
>
> We also need to have debate on this list as to the wording of the
> remaining sections of the document - especially Conformance.
>
> ---
>
> Let's fix the interface first.
>
> a) Evidence interface
>
> PROPOSED RESOLUTION A: The Evidence interface is
>
> void putHTTPHeader(String headerName, String value)
> String getHTTPHeader(String headerName);
> Boolean headerExists(String headerName);
>
> A factory method is added to SimpleService:
>
> Evidence newEvidence(HashMap<String, String> httpHeaders)
>
> The reasoning is as follows:
>
> The caller needs a way to put evidence into a known object in a
> standardised way. The API must support HTTP Evidence in the form of
> (case insensitive) HTTP Header Field name and (case sensitive) HTTP
> Header Field value, both strings (ASCII stings, actually, but, er,

let's
> leave that point aside unless we have to).
>
> The retrieval methods are there so that an object created by some
other
> instantiation method can still be queried by the any implementation,
> although that might not be very efficiently, it does allow inter
> working.
>
> It is likely that most Java implementations will want to allow the
> passing of a HashMap<String, String> derived directly e.g. from the
jsp
> infrastructure. However, in general this doesn't work as we can't rely
> on support of a HashMap<String, String> structure in other
environments

> / languages, so the factory method will probably look different in the
> IDL.
>
> It ought also to be a documentation and conformance point that HTTP
> Header Field names are treated case insensitively.
>
> I think we should call this SimpleEvidence (or HTTPEvidence) to
> distinguish it from any other sort of evidence.
>
> PROPOSED RESOLUTION B: Rename Evidence to SimpleEvidence
>
> b) Support for Property Terms distinct from PropertyRefs
>
> Rotan has discussed this in clear terms that I could not hope to match
> [1].
>
> In essence we have 2 proposals, Rotan's which is to overload the
> semantic of PropertyRef so it can be aspectless, and mine, which is to
> keep the PropertyName class and add a couple of factory methods - one

to

> PropertyName and the other to SimplePropertyValue, so we don't have to
> refer to any inheritance relationships between them.
>
> PROPOSED RESOLUTION C ALERNATIVE 1: Add a method to SimpleService
> SimplePropertyValue  getPropertyValue(Evidence e, String aspect,
> SimplePropertyRef propertyRef) where the aspect parameter overrides
> whatever aspect is present in the propertyRef and throw exceptions
> appropriately
>
> PROPOSED RESOLUTION C ALTERNATIVE 2: PropertyName remains in the API

and
> can be constructed from a PropertyRef by a factory method. A
PropertyRef

> can be created from a PropertyName by a factory method naming the
> aspect.
>
>
> c) Additional proposed resolutions
>
> PROPOSED RESOLUTION D: In SimplePropertyRef rename getName to
> getPropertyName
>
> PROPOSED RESOLUTION E: In SimplePropertyRef rename getAspect to
> getAspectName
>
> PROPOSED RESOLUTION F: In SimpleService rename newPropertyRef methods

to
> newSimplePropertyRef
>
>
> That's it folks - pls send +1s etc. to this list asap
>
> Jo
>
>

[JOSE MANUEL CANTERA FONSECA]

One of our duties, and in general W3C's, is to create technologies that
can be used in scenarios not previously envisaged, so I think that our
SimpleEvidence interface should not name HTTP at all while at the same
time stating in conformance statements that implementation must deal
with evidence that represents HTTP headers

The schema of name-value pairs is a very flexible one and allows to be
used in different adaptation scenarios not only the typical Mobile Web,
so let's create flexible technology and interfaces

Best Regards

Rotan Hanrahan escribió:

> The Evidence/SimpleEvidence/HTTPEvidence naming question continues...
>
> I will use Java as an example to do some exploration of the issue, which might help other people who are thinking about this too.
>
> In Java, the TreeMap class [1] supports the Map interface [2]. The Map interface has a size() method. The method is not called sizeOfTree() because then the interface would be locked to a particular class and would lose its generality.
>
> In Java, the Hashtable class [3] supports the Map interface [2]. The Map interface has a size() method. The method is not called sizeOfHashtable() because then the interface would be locked to a particular class and would lose its generality.
>
> In Java, the Attributes class [4] supports the Map interface.... ok you get the picture by now.
>
> The interface is supposed to be general if there is a possibility of re-use. In the case of the Simple API we have already had discussion where we recognise that some implementations are likely to want to support better forms of evidence. So it seems that, like the Java Map interface, there should be a general interface for Evidence. Even if this is just to identify what can be passed as a parameter in a query method.
>
> Separate factory methods can produce instances of classes that implement the Evidence class, and these can be instances of things that represent HTTP headers, or things that represent other identifying data.
>
> But, I hear you say, this is surely just the "Simple" API, so why does it matter if its called Evidence, SimpleEvidence or HTTPEvidence?
>
> It might matter because any implementation that tries to offer anything more than HTTP header evidence will still have to pass the evidence objects to the query methods as if they were supporting "HTTPEvidence", when in fact they are not HTTP evidence at all. They are just "evidence". So a generic interface name would be better.
>
> However, there is an alternative view.
>
> If a custom implementation provides a custom factory in the SimpleService to produce an instance of a custom SuperEvidence class, then it should be possible for this implementation to also provide custom overloaded query methods that take a SuperEvidence object instead of an instance of some class that implements the HTTPEvidence interface. Given that the SuperEvidence class is not dealing with HTTP headers, there's no reason for it to implement the HTTPEvidence interface, so we don't cause any polymorphic ambiguity. Plus, the Simple API is now a proper subset of the enhanced custom implementation, so the custom implemention can still claim to be conformant (so long as nobody uses the enhanced features).
>
> So, my position is that I don't really mind if the Simple API uses an interface called Evidence or one called HTTPEvidence. If the former, then any enhancements I offer will also implement Evidence though I'll add a few more interfaces for good measure. If we decide to call the interface HTTPEvidence, then any enhancements I offer will implement their own evidence interfaces and I'll overload the getPropertyValue* methods. In both cases, I'll also be providing custom factories.
>
> So I'm now "0" on this question :)
>
>
> ---Rotan
>
>
> [1] http://java.sun.com/j2se/1.4.2/docs/api/java/util/TreeMap.html
> [2] http://java.sun.com/j2se/1.4.2/docs/api/java/util/Map.html
> [3] http://java.sun.com/j2se/1.4.2/docs/api/java/util/Hashtable.html
> [4] http://java.sun.com/j2se/1.4.2/docs/api/java/util/jar/Attributes.html
>
>
>
> ________________________________
>
> From: public-ddwg-request@... on behalf of Ignacio Marin
> Sent: Tue 26/02/2008 22:57
> To: Jo Rabin; public-ddwg@...
> Subject: RE: Final chance, for now, to offer opinion on Simple API [was Continuation of discussion from today's call]
>
>
>
>
> Here I go with my response which is shorter than I promised, as I was going to comment about stuff already solved this afternoon like the naming inconsistency in the SimpleService interface.
>
> My response is sometimes not just a +1 or -1, sorry
>
> a) Evidence interface:
>
> For me, although it may sound like breaking our Simple... naming approach, the interface should be called HTTPEvidence in order to make it clearer to developers.
>
> I'm OK with...
>  
>> void putHTTPHeader(String headerName, String value)
>> String getHTTPHeader(String headerName);
>> Boolean headerExists(String headerName);
>>    
>
> ... although if the interface was HTTPEvidence, we might avoid so many HTTP in the names of the methods. By the way, for naming consistency, headerExists should be HTTPHeaderExists.
>
> This is clearer to me than the alternative of having newHTTPEvidence(Map map) and leave it up to the implementation on how to build the Map.
>
> I'd create a new HTTPEvidence() -no args- and then I would putHTTPHeader(name, value) as many times as I want. It may be uglier than the newHTTPEvidence(Map map), but it is easier to understand for programmers and more language agnostic.
>
> José commented: "Note that I'm not in favour of using Map<String,String> as it would bind us to Java 1.5 and up and I would like to mantain compatibility with at least Java 1.4"... In general, I am in favour of doing things as general as possible and avoid shortcuts for a specific language, although it may create a given language binding of the API a bit more complex than it would have been by using shortcuts. I am worried about these shortcuts stopping interoperability (Perl software consuming information from a Java implementation of the DDR API).
>
> So...
>
> PROPOSED RESOLUTION A: I'd like a newEvidence method with no args and putHeader, getHeader and headerExists.
>
> PROPOSED RESOLUTION B: +0.5 to Evidence-->SimpleEvidence. Let's be more direct by changing Evidence to HTTPEvidence (although we break our Simple... naming convention, as there is a more well known name than Simple).
>
> b) Support for Property Terms distinct from PropertyRefs
>
> PROPOSED RESOLUTION C ALERNATIVE 1: It sounds interesting.. it can be understood quickly and it is easy to use but
>
> PROPOSED RESOLUTION C ALERNATIVE 2: we should be consistent to the PropertyName and PropertyRef concepts, so +1 to this and -1 to the latter.
>
>  
>> c) Additional proposed resolutions
>>
>> PROPOSED RESOLUTION D: In SimplePropertyRef rename getName to
>> getPropertyName
>>
>> PROPOSED RESOLUTION E: In SimplePropertyRef rename getAspect to
>> getAspectName
>>
>> PROPOSED RESOLUTION F: In SimpleService rename newPropertyRef methods
>>    
> to
>  
>> newSimplePropertyRef
>>    
>
> Res D: +1, it is easier to understand the purpose of the method.
> Res E: +1, for the same reason
> Res F: I concur, although it might make sense in order to be consequent with other naming decisions. Particularly, I find the PropertyRef name a bit cryptic but no other good options come to my mind (PropertyAspectBinding sounds too long, but it is a bit more clear).
>
> I must say that sometimes it is difficult for me to balance between the ease-of-use and formality when choosing alternatives in the design of the API and I find myself voting for easiness in a situation while trying to keep things formal in another :-(
>
> Regards and sorry for the delay on my answer,
>
> Nacho
>
> -----Mensaje original-----
> De: Jo Rabin [mailto:jrabin@...]
> Enviado el: martes, 26 de febrero de 2008 15:47
> Para: Ignacio Marin; public-ddwg@...
> Asunto: RE: Final chance, for now, to offer opinion on Simple API [was Continuation of discussion from today's call]
>
> I'm about to post a link to some Java which I think represents group
> consensus, so if you could give your comments on that, that would be
> great.
>
> Thanks
>
>
>  
>> -----Original Message-----
>> From: Ignacio Marin [mailto:ignacio.marin@...]
>> Sent: 26 February 2008 14:45
>> To: Jo Rabin; public-ddwg@...
>> Subject: RE: Final chance, for now, to offer opinion on Simple API
>>    
> [was
>  
>> Continuation of discussion from today's call]
>>
>> I shall answer this tonite.
>> I have barely had the chance to be connected since I left yesterday's
>> teleconference and my opinion will take some time to be expressed (it
>> will not be only +/-1 or 0).
>>
>> I'll respond in some hours (4 hours more or less, as I will be in a
>> meeting outside CTIC and then in the University doing some teaching)
>>    
> and
>  
>> I hope you'll accept it as being sent today O:-)
>>
>> Regards,
>>
>> Nacho
>>
>>
>> -----Mensaje original-----
>> De: public-ddwg-request@... [mailto:public-ddwg-request@...] En
>> nombre de Jo Rabin
>> Enviado el: martes, 26 de febrero de 2008 8:53
>> Para: public-ddwg@...
>> Asunto: Final chance, for now, to offer opinion on Simple API [was
>> Continuation of discussion from today's call]
>>
>>
>> What follows is an edited version of what I sent yesterday. Apologies
>> for sending it to the wrong list initially.
>>
>> Aside from Rotan there have been no contributions. For the sake of
>> getting a document ready for the Face to Face I am going to start work
>> later this afternoon on a draft. In the absence of response I will
>>    
> take
>  
>> it as a "+1" to all resolutions except C Alternative 1.
>>
>> Jo
>>
>> Contents:
>>
>> a) what is the signature of the Evidence interface?
>> b) how are underlying PropertyNames to be supported?
>> c) Misc renames for consistency
>>
>> Urgency:
>>
>> The important thing is to resolve this TODAY [that was yesterday] so
>>    
> we
>  
>> can have a substantive draft for discussion in Seoul next week,
>> following which we will issue a First Public Working Draft which "with
>>    
> a
>  
>> fair wind and a
>> following sea" (colloq. = with luck) will also be a Last Call working
>> draft.
>>
>> Other Tasks
>>
>> We also need to have debate on this list as to the wording of the
>> remaining sections of the document - especially Conformance.
>>
>> ---
>>
>> Let's fix the interface first.
>>
>> a) Evidence interface
>>
>> PROPOSED RESOLUTION A: The Evidence interface is
>>
>> void putHTTPHeader(String headerName, String value)
>> String getHTTPHeader(String headerName);
>> Boolean headerExists(String headerName);
>>
>> A factory method is added to SimpleService:
>>
>> Evidence newEvidence(HashMap<String, String> httpHeaders)
>>
>> The reasoning is as follows:
>>
>> The caller needs a way to put evidence into a known object in a
>> standardised way. The API must support HTTP Evidence in the form of
>> (case insensitive) HTTP Header Field name and (case sensitive) HTTP
>> Header Field value, both strings (ASCII stings, actually, but, er,
>>    
> let's
>  
>> leave that point aside unless we have to).
>>
>> The retrieval methods are there so that an object created by some
>>    
> other
>  
>> instantiation method can still be queried by the any implementation,
>> although that might not be very efficiently, it does allow inter
>> working.
>>
>> It is likely that most Java implementations will want to allow the
>> passing of a HashMap<String, String> derived directly e.g. from the
>>    
> jsp
>  
>> infrastructure. However, in general this doesn't work as we can't rely
>> on support of a HashMap<String, String> structure in other
>>    
> environments
>  
>> / languages, so the factory method will probably look different in the
>> IDL.
>>
>> It ought also to be a documentation and conformance point that HTTP
>> Header Field names are treated case insensitively.
>>
>> I think we should call this SimpleEvidence (or HTTPEvidence) to
>> distinguish it from any other sort of evidence.
>>
>> PROPOSED RESOLUTION B: Rename Evidence to SimpleEvidence
>>
>> b) Support for Property Terms distinct from PropertyRefs
>>
>> Rotan has discussed this in clear terms that I could not hope to match
>> [1].
>>
>> In essence we have 2 proposals, Rotan's which is to overload the
>> semantic of PropertyRef so it can be aspectless, and mine, which is to
>> keep the PropertyName class and add a couple of factory methods - one
>>    
> to
>  
>> PropertyName and the other to SimplePropertyValue, so we don't have to
>> refer to any inheritance relationships between them.
>>
>> PROPOSED RESOLUTION C ALERNATIVE 1: Add a method to SimpleService
>> SimplePropertyValue  getPropertyValue(Evidence e, String aspect,
>> SimplePropertyRef propertyRef) where the aspect parameter overrides
>> whatever aspect is present in the propertyRef and throw exceptions
>> appropriately
>>
>> PROPOSED RESOLUTION C ALTERNATIVE 2: PropertyName remains in the API
>>    
> and
>  
>> can be constructed from a PropertyRef by a factory method. A
>>    
> PropertyRef
>  
>> can be created from a PropertyName by a factory method naming the
>> aspect.
>>
>>
>> c) Additional proposed resolutions
>>
>> PROPOSED RESOLUTION D: In SimplePropertyRef rename getName to
>> getPropertyName
>>
>> PROPOSED RESOLUTION E: In SimplePropertyRef rename getAspect to
>> getAspectName
>>
>> PROPOSED RESOLUTION F: In SimpleService rename newPropertyRef methods
>>    
> to
>  
>> newSimplePropertyRef
>>
>>
>> That's it folks - pls send +1s etc. to this list asap
>>
>> Jo
>>
>>
>>    
>
>
>
>
>
> .
>
>  

[Ignacio Marin]

Hi Jose and Rotan,

You are right. But I also think that, if someone wants to improve the Simple API a lot, what they might need is an Advanced API.

I am not meaning that we do not have to do it as extensible as possible, but the API has also to be clear enough for basic developers (as it has been commented within the group) and in this line it was my doubt/comment.

The HTTPEvidence name would be chosen for informational purposes. I said that SimpleEvidence with a newHTTPEvidence is OK for me. In terms of extensibility, Jose's proposal (be more general and talk about keys/values in general and not binding the API only to HTTP) is great in terms of extensibility, although writing HTTP in methods and/or args might help developers understanding. This can be achieved anyway by a correct documentation of the API, which I am sure we shall generate and I volunteer to write the text explaining the API.

My main concern is that sometimes, for instance, we use strings as parameters instead of "more strongly typed" kind of parameters -I do not think that any developer dealing with a DDR API would be against strong typing, but it is only a personal opinion-; some other times, I think we are making a Simple API that is extensible but not so clear for the kind of developer who needs a convenience function using strings.

Just thinking out loud. I am OK with any of the alternatives and will not object, as they are all reasonable (so far :-) ).

Regards,

Nacho


-----Mensaje original-----
De: jmcf@... [mailto:jmcf@...]
Enviado el: miércoles, 27 de febrero de 2008 7:57
Para: Rotan Hanrahan
CC: Ignacio Marin; Jo Rabin; public-ddwg@...
Asunto: Re: Final chance, for now, to offer opinion on Simple API [was Continuation of discussion from today's call]

One of our duties, and in general W3C's, is to create technologies that
can be used in scenarios not previously envisaged, so I think that our
SimpleEvidence interface should not name HTTP at all while at the same
time stating in conformance statements that implementation must deal
with evidence that represents HTTP headers

The schema of name-value pairs is a very flexible one and allows to be
used in different adaptation scenarios not only the typical Mobile Web,
so let's create flexible technology and interfaces

Best Regards

Rotan Hanrahan escribió:

> The Evidence/SimpleEvidence/HTTPEvidence naming question continues...
>
> I will use Java as an example to do some exploration of the issue, which might help other people who are thinking about this too.
>
> In Java, the TreeMap class [1] supports the Map interface [2]. The Map interface has a size() method. The method is not called sizeOfTree() because then the interface would be locked to a particular class and would lose its generality.
>
> In Java, the Hashtable class [3] supports the Map interface [2]. The Map interface has a size() method. The method is not called sizeOfHashtable() because then the interface would be locked to a particular class and would lose its generality.
>
> In Java, the Attributes class [4] supports the Map interface.... ok you get the picture by now.
>
> The interface is supposed to be general if there is a possibility of re-use. In the case of the Simple API we have already had discussion where we recognise that some implementations are likely to want to support better forms of evidence. So it seems that, like the Java Map interface, there should be a general interface for Evidence. Even if this is just to identify what can be passed as a parameter in a query method.
>
> Separate factory methods can produce instances of classes that implement the Evidence class, and these can be instances of things that represent HTTP headers, or things that represent other identifying data.
>
> But, I hear you say, this is surely just the "Simple" API, so why does it matter if its called Evidence, SimpleEvidence or HTTPEvidence?
>
> It might matter because any implementation that tries to offer anything more than HTTP header evidence will still have to pass the evidence objects to the query methods as if they were supporting "HTTPEvidence", when in fact they are not HTTP evidence at all. They are just "evidence". So a generic interface name would be better.
>
> However, there is an alternative view.
>
> If a custom implementation provides a custom factory in the SimpleService to produce an instance of a custom SuperEvidence class, then it should be possible for this implementation to also provide custom overloaded query methods that take a SuperEvidence object instead of an instance of some class that implements the HTTPEvidence interface. Given that the SuperEvidence class is not dealing with HTTP headers, there's no reason for it to implement the HTTPEvidence interface, so we don't cause any polymorphic ambiguity. Plus, the Simple API is now a proper subset of the enhanced custom implementation, so the custom implemention can still claim to be conformant (so long as nobody uses the enhanced features).
>
> So, my position is that I don't really mind if the Simple API uses an interface called Evidence or one called HTTPEvidence. If the former, then any enhancements I offer will also implement Evidence though I'll add a few more interfaces for good measure. If we decide to call the interface HTTPEvidence, then any enhancements I offer will implement their own evidence interfaces and I'll overload the getPropertyValue* methods. In both cases, I'll also be providing custom factories.
>
> So I'm now "0" on this question :)
>
>
> ---Rotan
>
>
> [1] http://java.sun.com/j2se/1.4.2/docs/api/java/util/TreeMap.html
> [2] http://java.sun.com/j2se/1.4.2/docs/api/java/util/Map.html
> [3] http://java.sun.com/j2se/1.4.2/docs/api/java/util/Hashtable.html
> [4] http://java.sun.com/j2se/1.4.2/docs/api/java/util/jar/Attributes.html
>
>
>
> ________________________________
>
> From: public-ddwg-request@... on behalf of Ignacio Marin
> Sent: Tue 26/02/2008 22:57
> To: Jo Rabin; public-ddwg@...
> Subject: RE: Final chance, for now, to offer opinion on Simple API [was Continuation of discussion from today's call]
>
>
>
>
> Here I go with my response which is shorter than I promised, as I was going to comment about stuff already solved this afternoon like the naming inconsistency in the SimpleService interface.
>
> My response is sometimes not just a +1 or -1, sorry
>
> a) Evidence interface:
>
> For me, although it may sound like breaking our Simple... naming approach, the interface should be called HTTPEvidence in order to make it clearer to developers.
>
> I'm OK with...
>  
>> void putHTTPHeader(String headerName, String value)
>> String getHTTPHeader(String headerName);
>> Boolean headerExists(String headerName);
>>    
>
> ... although if the interface was HTTPEvidence, we might avoid so many HTTP in the names of the methods. By the way, for naming consistency, headerExists should be HTTPHeaderExists.
>
> This is clearer to me than the alternative of having newHTTPEvidence(Map map) and leave it up to the implementation on how to build the Map.
>
> I'd create a new HTTPEvidence() -no args- and then I would putHTTPHeader(name, value) as many times as I want. It may be uglier than the newHTTPEvidence(Map map), but it is easier to understand for programmers and more language agnostic.
>
> José commented: "Note that I'm not in favour of using Map<String,String> as it would bind us to Java 1.5 and up and I would like to mantain compatibility with at least Java 1.4"... In general, I am in favour of doing things as general as possible and avoid shortcuts for a specific language, although it may create a given language binding of the API a bit more complex than it would have been by using shortcuts. I am worried about these shortcuts stopping interoperability (Perl software consuming information from a Java implementation of the DDR API).
>
> So...
>
> PROPOSED RESOLUTION A: I'd like a newEvidence method with no args and putHeader, getHeader and headerExists.
>
> PROPOSED RESOLUTION B: +0.5 to Evidence-->SimpleEvidence. Let's be more direct by changing Evidence to HTTPEvidence (although we break our Simple... naming convention, as there is a more well known name than Simple).
>
> b) Support for Property Terms distinct from PropertyRefs
>
> PROPOSED RESOLUTION C ALERNATIVE 1: It sounds interesting.. it can be understood quickly and it is easy to use but
>
> PROPOSED RESOLUTION C ALERNATIVE 2: we should be consistent to the PropertyName and PropertyRef concepts, so +1 to this and -1 to the latter.
>
>  
>> c) Additional proposed resolutions
>>
>> PROPOSED RESOLUTION D: In SimplePropertyRef rename getName to
>> getPropertyName
>>
>> PROPOSED RESOLUTION E: In SimplePropertyRef rename getAspect to
>> getAspectName
>>
>> PROPOSED RESOLUTION F: In SimpleService rename newPropertyRef methods
>>    
> to
>  
>> newSimplePropertyRef
>>    
>
> Res D: +1, it is easier to understand the purpose of the method.
> Res E: +1, for the same reason
> Res F: I concur, although it might make sense in order to be consequent with other naming decisions. Particularly, I find the PropertyRef name a bit cryptic but no other good options come to my mind (PropertyAspectBinding sounds too long, but it is a bit more clear).
>
> I must say that sometimes it is difficult for me to balance between the ease-of-use and formality when choosing alternatives in the design of the API and I find myself voting for easiness in a situation while trying to keep things formal in another :-(
>
> Regards and sorry for the delay on my answer,
>
> Nacho
>
> -----Mensaje original-----
> De: Jo Rabin [mailto:jrabin@...]
> Enviado el: martes, 26 de febrero de 2008 15:47
> Para: Ignacio Marin; public-ddwg@...
> Asunto: RE: Final chance, for now, to offer opinion on Simple API [was Continuation of discussion from today's call]
>
> I'm about to post a link to some Java which I think represents group
> consensus, so if you could give your comments on that, that would be
> great.
>
> Thanks
>
>
>  
>> -----Original Message-----
>> From: Ignacio Marin [mailto:ignacio.marin@...]
>> Sent: 26 February 2008 14:45
>> To: Jo Rabin; public-ddwg@...
>> Subject: RE: Final chance, for now, to offer opinion on Simple API
>>    
> [was
>  
>> Continuation of discussion from today's call]
>>
>> I shall answer this tonite.
>> I have barely had the chance to be connected since I left yesterday's
>> teleconference and my opinion will take some time to be expressed (it
>> will not be only +/-1 or 0).
>>
>> I'll respond in some hours (4 hours more or less, as I will be in a
>> meeting outside CTIC and then in the University doing some teaching)
>>    
> and
>  
>> I hope you'll accept it as being sent today O:-)
>>
>> Regards,
>>
>> Nacho
>>
>>
>> -----Mensaje original-----
>> De: public-ddwg-request@... [mailto:public-ddwg-request@...] En
>> nombre de Jo Rabin
>> Enviado el: martes, 26 de febrero de 2008 8:53
>> Para: public-ddwg@...
>> Asunto: Final chance, for now, to offer opinion on Simple API [was
>> Continuation of discussion from today's call]
>>
>>
>> What follows is an edited version of what I sent yesterday. Apologies
>> for sending it to the wrong list initially.
>>
>> Aside from Rotan there have been no contributions. For the sake of
>> getting a document ready for the Face to Face I am going to start work
>> later this afternoon on a draft. In the absence of response I will
>>    
> take
>  
>> it as a "+1" to all resolutions except C Alternative 1.
>>
>> Jo
>>
>> Contents:
>>
>> a) what is the signature of the Evidence interface?
>> b) how are underlying PropertyNames to be supported?
>> c) Misc renames for consistency
>>
>> Urgency:
>>
>> The important thing is to resolve this TODAY [that was yesterday] so
>>    
> we
>  
>> can have a substantive draft for discussion in Seoul next week,
>> following which we will issue a First Public Working Draft which "with
>>    
> a
>  
>> fair wind and a
>> following sea" (colloq. = with luck) will also be a Last Call working
>> draft.
>>
>> Other Tasks
>>
>> We also need to have debate on this list as to the wording of the
>> remaining sections of the document - especially Conformance.
>>
>> ---
>>
>> Let's fix the interface first.
>>
>> a) Evidence interface
>>
>> PROPOSED RESOLUTION A: The Evidence interface is
>>
>> void putHTTPHeader(String headerName, String value)
>> String getHTTPHeader(String headerName);
>> Boolean headerExists(String headerName);
>>
>> A factory method is added to SimpleService:
>>
>> Evidence newEvidence(HashMap<String, String> httpHeaders)
>>
>> The reasoning is as follows:
>>
>> The caller needs a way to put evidence into a known object in a
>> standardised way. The API must support HTTP Evidence in the form of
>> (case insensitive) HTTP Header Field name and (case sensitive) HTTP
>> Header Field value, both strings (ASCII stings, actually, but, er,
>>    
> let's
>  
>> leave that point aside unless we have to).
>>
>> The retrieval methods are there so that an object created by some
>>    
> other
>  
>> instantiation method can still be queried by the any implementation,
>> although that might not be very efficiently, it does allow inter
>> working.
>>
>> It is likely that most Java implementations will want to allow the
>> passing of a HashMap<String, String> derived directly e.g. from the
>>    
> jsp
>  
>> infrastructure. However, in general this doesn't work as we can't rely
>> on support of a HashMap<String, String> structure in other
>>    
> environments
>  
>> / languages, so the factory method will probably look different in the
>> IDL.
>>
>> It ought also to be a documentation and conformance point that HTTP
>> Header Field names are treated case insensitively.
>>
>> I think we should call this SimpleEvidence (or HTTPEvidence) to
>> distinguish it from any other sort of evidence.
>>
>> PROPOSED RESOLUTION B: Rename Evidence to SimpleEvidence
>>
>> b) Support for Property Terms distinct from PropertyRefs
>>
>> Rotan has discussed this in clear terms that I could not hope to match
>> [1].
>>
>> In essence we have 2 proposals, Rotan's which is to overload the
>> semantic of PropertyRef so it can be aspectless, and mine, which is to
>> keep the PropertyName class and add a couple of factory methods - one
>>    
> to
>  
>> PropertyName and the other to SimplePropertyValue, so we don't have to
>> refer to any inheritance relationships between them.
>>
>> PROPOSED RESOLUTION C ALERNATIVE 1: Add a method to SimpleService
>> SimplePropertyValue  getPropertyValue(Evidence e, String aspect,
>> SimplePropertyRef propertyRef) where the aspect parameter overrides
>> whatever aspect is present in the propertyRef and throw exceptions
>> appropriately
>>
>> PROPOSED RESOLUTION C ALTERNATIVE 2: PropertyName remains in the API
>>    
> and
>  
>> can be constructed from a PropertyRef by a factory method. A
>>    
> PropertyRef
>  
>> can be created from a PropertyName by a factory method naming the
>> aspect.
>>
>>
>> c) Additional proposed resolutions
>>
>> PROPOSED RESOLUTION D: In SimplePropertyRef rename getName to
>> getPropertyName
>>
>> PROPOSED RESOLUTION E: In SimplePropertyRef rename getAspect to
>> getAspectName
>>
>> PROPOSED RESOLUTION F: In SimpleService rename newPropertyRef methods
>>    
> to
>  
>> newSimplePropertyRef
>>
>>
>> That's it folks - pls send +1s etc. to this list asap
>>
>> Jo
>>
>>
>>    
>
>
>
>
>
> .
>
>