Preview of full latest Java Interface

Thanks Jo. For convenience, the text of all the code minus, the
exceptions, as it looks at this moment in time is pasted below.

---Rotan






package org.w3c.ddr.simple;

/**
 * An interface representing evidence that is to be supplied to
getSimplePropertyValue
 * or getSimplePropertyValues methods of {@link SimpleService}
 *
 * @author jo
 *
 */

public interface SimpleEvidence {
        /**
         * Add a key / value pair
         * @param key The key
         * @param value The value
         */
        public void put(String key, String value);
       
        /**
         * True if a key exists
         * @param key
         * @return
         */
        public Boolean exists(String key);
       
        /**
         * Get the value corresponding to the key
         * @param key
         * @return
         */
        public String getValue(String key);
}



package org.w3c.ddr.simple;

public interface SimplePropertyName {
        /**
         * The name of the property
         *
         * @return
         */
        public String getPropertyName();

        /**
         * The namespace of the property
         *
         * @return
         *
         */
        //TODO Worry about whether an IRI class is needed

        public String getNamespace();

        /**
         * Factory to create a SimplePropertyRef with the specified
aspect referring to this property
         *
         * @param aspect
         * @return
         */
        public SimplePropertyRef newSimplePropertyRef (String aspect);
}



package org.w3c.ddr.simple;

/**
 * Represents a property / aspect combination
 *
 * @author jo
 *
 *
 */
public interface SimplePropertyRef {
       
        public static final String NULL_ASPECT = "__NULL";

        /**
         * The name of the property
         *
         * @return
         */
        public String getPropertyName();

        /**
         * The name of the aspect
         *
         * @return
         */
        public String getAspectName();

        /**
         * The namespace of the property and aspect
         *
         * @return
         *
         */
        //TODO Worry about whether an IRI class is needed
        public String getNamespace();
       
        /**
         * Factory to create a SimplePropertyName referring to the
Property encapsulated
         * by this SimplePropertyRef
         *
         * @return
         */
        public SimplePropertyName newSimplePropertyName ();
}



package org.w3c.ddr.simple;

import org.w3c.ddr.simple.exception.ValueException;

/**
 * Represents the value of a property
 *
 * @author jmcf
 *
 */
public interface SimplePropertyValue {

        /**
         *
         * Returns the value as double in the default units of the
property
         *
         * If the value cannot be represented as a double an exception
will be
         * thrown
         *
         *
         */
        public double getDouble() throws ValueException;

        /**
         *
         * Returns the value as a long in the default units of the
property
         *
         * An exception will be thrown if the value cannot be
represented as a long
         *
         * @return
         * @throws ValueException
         */
        public long getLong() throws ValueException;

        /**
         *
         * Returns the value of the property as a String
         *
         * This method will return
         *
         * @return
         */
        public String getString() throws ValueException;

        /**
         * Returns the actual value as a boolean
         *
         * If the value cannot be represented as a boolean an exception
will be
         * thrown
         *
         * @return
         * @throws SimpleException
         */
        public boolean getBoolean() throws ValueException;

        /**
         *
         * Returns the value as an integer in the default units of the
property
         *
         * An exception will be thrown if the value cannot be
represented as an
         * Integer
         *
         * @return
         * @throws SimpleException
         */
        public int getInteger() throws ValueException;

        /**
         *
         * Returns the value as an enumeration
         *
         * If the value cannot be represented as an enumeration an
exception will be
         * thrown
         *
         *
         * @return
         * @throws SimpleException
         */
        public String[] getEnumeration() throws ValueException;

        /**
         *
         * Returns the value in the specified unit as a float
         *
         * If the value cannot be represented as a float an exception
will be thrown
         *
         *
         *
         */
        public float getFloat() throws ValueException;

        /**
         * @return
         */
        public SimplePropertyRef getPropertyRef();

        /**
         * @return
         */
        public boolean exists();
}



package org.w3c.ddr.simple;

import org.w3c.ddr.simple.exception.NameException;
import org.w3c.ddr.simple.exception.SystemException;

public interface SimplePropertyValues  {
               
        public SimplePropertyValue[] getAll() throws SystemException;
       
        public SimplePropertyValue getValue(SimplePropertyRef prop)
throws SystemException, NameException;
}



package org.w3c.ddr.simple;

import java.util.Map;
import java.util.Properties;

import org.w3c.ddr.simple.exception.NameException;
import org.w3c.ddr.simple.exception.SystemException;

public interface SimpleService {
        /**
         * Called by {@link SimpleServiceFactory} to initialize the API
following construction
         *
         * @param defaultVocabularyIRI the IRI of the default vocabulary
namespace
         * @param props Implementation dependent properties
         * @throws SystemException
         */
        public void initialize(String defaultVocabularyIRI, Properties
props)
                        throws SystemException;

        /**
         *
         * @return A string indicating the revision level of the API
         */
        public String getAPIVersion();

        /**
         *
         * @return A String indicating the revision level of the data
         */
        public String getDataVersion();

        /**
         * List all the PropertyRefs the API knows about
         * @return
         * @throws SystemException
         */
        public SimplePropertyRef[] listSimplePropertyRefs() throws
SystemException;
       
       
       
        public SimplePropertyValue getSimplePropertyValue(SimpleEvidence
evidence,
                        SimplePropertyRef propertyRef) throws
NameException,
                        SystemException;

        public SimplePropertyValue getSimplePropertyValue(SimpleEvidence
evidence,
                        String propertyName) throws NameException,
SystemException;

        public SimplePropertyValue getSimplePropertyValue(SimpleEvidence
evidence,
                        String aspect, String propertyName) throws
NameException,
                        SystemException;
       
        public SimplePropertyValue getSimplePropertyValue
(SimpleEvidence evidence,
                        SimplePropertyName simplePropertyName) throws
NameException,
                        SystemException;
       

        public SimplePropertyValues
getSimplePropertyValues(SimpleEvidence evidence)
                        throws SystemException;

        public SimplePropertyValues
getSimplePropertyValues(SimpleEvidence evidence,
                        SimplePropertyRef[] properties) throws
NameException,
                        SystemException;

        public SimplePropertyValues
getSimplePropertyValues(SimpleEvidence evidence,
                        String aspectName) throws NameException,
SystemException;

        public SimplePropertyValues
getSimplePropertyValues(SimpleEvidence evidence,
                        String aspectIRI, String aspectName) throws
NameException,
                        SystemException;


        public SimplePropertyRef newSimplePropertyRef(String
localPropertyName)
                        throws NameException, SystemException;

        public SimplePropertyRef newSimplePropertyRef(String
localAspectName,
                        String localPropertyName) throws NameException,
SystemException;

        public SimplePropertyRef newSimplePropertyRef(String
vocabularyIRI,
                        String localAspectName, String
localPropertyName)
                        throws NameException, SystemException;
       
        public SimplePropertyRef newSimplePropertyRef(String
localAspectName,
                        SimplePropertyName simplePropertyName)
                        throws NameException, SystemException;

        /**
         * Create a SimpleEvidence using the Map consisting of HTTP
Header Names and Values
         * @param map
         * @return
         */
        public SimpleEvidence newHTTPEvidence(Map map);

}




package org.w3c.ddr.simple;

import java.util.Properties;

import org.w3c.ddr.simple.exception.NameException;
import org.w3c.ddr.simple.exception.SystemException;

public class SimpleServiceFactory {
        public static SimpleService newSimpleService(String clazz,
                        String defaultVocabulary, Properties
configuration)
                        throws SystemException, NameException {
                SimpleService theService = null;
                try {
                        // Instantiation
                        theService = (SimpleService)
Class.forName(clazz).newInstance();

                        // Initialization
                        theService.initialize(defaultVocabulary,
configuration);
                } catch (Throwable thr) {
                        // TODO: Capture the exceptions properly
                        throw new
SystemException(SystemException.INITIALIZATION, thr);
                }

                return theService;
        }

        public static SimpleService newSimpleService(String
defaultVocabulary,
                        Properties configuration) throws
SystemException, NameException {

                return null;
        }
}

Thanks Rotan

In the course of responding to Jose's comment I noticed that the naming
of the parameters was inconsistent in the SimpleService interface and
have renamed them consistently.

So if you wish to review and comment please refer to

http://www.w3.org/2005/MWI/DDWG/drafts/api/simple/java/org/w3c/ddr/simpl
e/

Jo


Copied as text below

import java.util.Map;
import java.util.Properties;

import org.w3c.ddr.simple.exception.NameException;
import org.w3c.ddr.simple.exception.SystemException;

public interface SimpleService {
        /**
         * Called by {@link SimpleServiceFactory} to initialize the API
following construction
         *
         * @param defaultVocabularyIRI the IRI of the default vocabulary
namespace
         * @param props Implementation dependent properties
         * @throws SystemException
         */
        public void initialize(String defaultVocabularyIRI, Properties
props)
                        throws SystemException;

        /**
         *
         * @return A string indicating the revision level of the API
         */
        public String getAPIVersion();

        /**
         *
         * @return A String indicating the revision level of the data
         */
        public String getDataVersion();

        /**
         * List all the PropertyRefs the API knows about
         * @return
         * @throws SystemException
         */
        public SimplePropertyRef[] listSimplePropertyRefs() throws
SystemException;
       
       
       
        public SimplePropertyValue getSimplePropertyValue(SimpleEvidence
evidence,
                        SimplePropertyRef simplePropertyRef) throws
NameException,
                        SystemException;

        public SimplePropertyValue getSimplePropertyValue(SimpleEvidence
evidence,
                        String localPropertyName) throws NameException,
SystemException;

        public SimplePropertyValue getSimplePropertyValue(SimpleEvidence
evidence,
                        String localAspectName, String
localPropertyName) throws NameException,
                        SystemException;
       
        public SimplePropertyValue getSimplePropertyValue
(SimpleEvidence evidence,
                        SimplePropertyName simplePropertyName) throws
NameException,
                        SystemException;
       

        public SimplePropertyValues
getSimplePropertyValues(SimpleEvidence evidence)
                        throws SystemException;

        public SimplePropertyValues
getSimplePropertyValues(SimpleEvidence evidence,
                        SimplePropertyRef[] simplePropertyRefs) throws
NameException,
                        SystemException;

        public SimplePropertyValues
getSimplePropertyValues(SimpleEvidence evidence,
                        String localAspectName) throws NameException,
SystemException;

        public SimplePropertyValues
getSimplePropertyValues(SimpleEvidence evidence,
                        String aspectIRI, String localAspectName) throws
NameException,
                        SystemException;


        public SimplePropertyRef newSimplePropertyRef(String
localPropertyName)
                        throws NameException, SystemException;

        public SimplePropertyRef newSimplePropertyRef(String
localAspectName,
                        String localPropertyName) throws NameException,
SystemException;

        public SimplePropertyRef newSimplePropertyRef(String
vocabularyIRI,
                        String localAspectName, String
localPropertyName)
                        throws NameException, SystemException;
       
        public SimplePropertyRef newSimplePropertyRef(String
localAspectName,
                        SimplePropertyName simplePropertyName)
                        throws NameException, SystemException;

        /**
         * Create a SimpleEvidence using the Map consisting of HTTP
Header Names and Values
         * @param map
         * @return
         */
        public SimpleEvidence newHTTPEvidence(Map map);

}

---
Jo Rabin
mTLD (http://dotmobi.mobi)

mTLD Top Level Domain Limited is a private limited company incorporated
and registered in the Republic of Ireland with registered number 398040
and registered office at Arthur Cox Building, Earlsfort Terrace, Dublin
2.


> -----Original Message-----
> From: public-ddwg-request@... [mailto:public-ddwg-request@...]
On

+ I'm missing a newHttpEvidence() method. We agree that the Java binding
is gonna also have a newHttpEvidence(Map) but the method with no
parameters is also needed as it is the only method present in IDL and in
every language binding

+ The methods that only receive a property and not an aspect, Are they
going to return the property value for the default aspect of the property?

+ The getPropertyValues method should have at least one more overloaded
method:

    public SimplePropertyValues getSimplePropertyValues(SimpleEvidence
evidence,
            PropertyName property) throws NameException, SystemException;

which will return all the property values for that property in all the
aspects of that property

+ I'm a bit worried about the complexity of the overloading that we are
putting in place We should think of what is gonna be the most common use
case and model it in a convenience function and leave the other cases
behind the SimplePropertyRef and SimpleProperty interfaces

So perhaps it only makes sense to mantain the getPropertyValue(Evidence,
String localPropertyName) as the only fast food method ...with the
possible addition of the methods that allow to retrieve all the
properties of an aspect

Also I'm not very convinced that we need to have in everyplace the word
'Simple', that could be left in the package name ...

Best Regards

Jo Rabin escribió:

I share your concerns on most of this. In particular I think the method names are unmanageable (and actually self contradictory - did I mention that this is the "Simple" interface, maybe better stick the word Simple in again just in case). I think we could banish the word Simple from the interfaces as Jose suggests and leave it in the package name as a clue.

We have a frighteningly large number of overloaded methods. One for every day of the week, two for Sunday, and a spare for leap years.

We have also a SimpleService.newSimplePropertyRef(String aspect, SimplePropertyName) method that appears to duplicate the SimplePropertyName.newSimplePropertyRef(String aspect) method. So I think we should take the factories out of SimplePropertyRef and SimplePropertyName interfaces as being redundant.

All that aside, my biggest concern is that we are in a process of taking two steps forward and one step back. I can see the pages of the calendar blowing away, like in those old movies, and I am planning to be on a plane, Saturday, to attend a meeting that will resolve this document as at least a FPWD and preferably a LCWD. So in short, this process needs to come to a conclusion.

Jo

> + I'm missing a newHttpEvidence() method. We agree that the Java binding
> is gonna also have a newHttpEvidence(Map) but the method with no
> parameters is also needed as it is the only method present in IDL and in
> every language binding

+1, per my previous email last night. I had not developed this part enough. A no-parameter version is needed.

> + I'm a bit worried about the complexity of the overloading that we are
> putting in place We should think of what is gonna be the most common use
> case and model it in a convenience function and leave the other cases
> behind the SimplePropertyRef and SimpleProperty interfaces

+1, per my last email about convenience functions vs complexity.

> Also I'm not very convinced that we need to have in everyplace the word
> 'Simple', that could be left in the package name ...

If Simple is spread everywhere, I guess you might be right

Nacho

Best Regards

Jo Rabin escribió:

+1 to removing the word Simple and streamlining the overloaded methods, for the same reasons given...
Kevin

-----Original Message-----
From: public-ddwg-request@... [mailto:public-ddwg-request@...] On Behalf Of Jo Rabin
Sent: 27 February 2008 09:00
To: public-ddwg@...
Subject: RE: Preview of full latest Java Interface : Comments on SimpleService interface



I share your concerns on most of this. In particular I think the method names are unmanageable (and actually self contradictory - did I mention that this is the "Simple" interface, maybe better stick the word Simple in again just in case). I think we could banish the word Simple from the interfaces as Jose suggests and leave it in the package name as a clue.

We have a frighteningly large number of overloaded methods. One for every day of the week, two for Sunday, and a spare for leap years.

We have also a SimpleService.newSimplePropertyRef(String aspect, SimplePropertyName) method that appears to duplicate the SimplePropertyName.newSimplePropertyRef(String aspect) method. So I think we should take the factories out of SimplePropertyRef and SimplePropertyName interfaces as being redundant.

All that aside, my biggest concern is that we are in a process of taking two steps forward and one step back. I can see the pages of the calendar blowing away, like in those old movies, and I am planning to be on a plane, Saturday, to attend a meeting that will resolve this document as at least a FPWD and preferably a LCWD. So in short, this process needs to come to a conclusion.

Jo

As there may be some interest in seeing what the API might look like if "simple" was just part of the package names and not part of the class names, here is a summary of the API based on the most recent complete version that I've seen. (It does not, for example, have a factory for an evidence instance that takes no parameters in the constructor, though apparantly this may be needed.)
 
Changes to the names are not really material to the API itself, though the names can have an effect on the understanding that new developers will have when they encounter the API for the first time. The substantive discussions are really about the nature of the interfaces, their relationships to each other, their semantics and the signatures of methods.
 
So, here's the insubstantive name changing exercise to see what happens if "simple" is just part of the package name:
 
org.w3c.ddr.simple.Service
  void initialize(
    String defaultVocabularyIRI,
    Properties props
  )
  String getAPIVersion()
  String getDataVersion()
  PropertyRef[] listPropertyRefs()
  PropertyValue getPropertyValue(
    Evidence evidence,
    PropertyRef propertyRef
  )
  PropertyValue getPropertyValue(
    Evidence evidence,
    String localPropertyName
  )
  PropertyValue getPropertyValue(
    Evidence evidence,
    String localAspectName,
    String localPropertyName
  )
  PropertyValue getPropertyValue(
    Evidence evidence,
    PropertyName propertyName
  )
  PropertyValues getPropertyValues(
    Evidence evidence
  )
  PropertyValues getPropertyValues(
    Evidence evidence,
    PropertyRef[] propertyRefs
  )
  PropertyValues getPropertyValues(
    Evidence evidence,
    String localAspectName
  )
  PropertyValues getPropertyValues(
    Evidence evidence,
    String aspectIRI,
    String localAspectName
  )
  PropertyRef newPropertyRef(
    String localPropertyName
  )
  PropertyRef newPropertyRef(
    String localAspectName,
    String localPropertyName
  )
  PropertyRef newPropertyRef(
    String vocabularyIRI,
    String localAspectName,
    String localPropertyName
  )
  PropertyRef newPropertyRef(
    String localAspectName,
    PropertyName propertyName
  )
  Evidence newHTTPEvidence(Map map)
 
org.w3c.ddr.simple.Evidence
  void put(
    String key,
    String value
  )
  Boolean exists(
    String key
  )
  String getValue(
    String key
  )
 
org.w3c.ddr.simple.PropertyName
  String getPropertyName()
  String getNamespace()
  PropertyRef newPropertyRef(
    String aspect
  )
 
org.w3c.ddr.simple.PropertyRef
  static final String NULL_ASPECT = "__NULL"
  String getPropertyName()
  String getAspectName()
  String getNamespace()
  PropertyName newPropertyName()
 
org.w3c.ddr.simple.PropertyValue
  double getDouble()
  long getLong()
  String getString()
  boolean getBoolean()
  int getInteger()
  String[] getEnumeration()
  float getFloat()
  boolean exists()
 
org.w3c.ddr.simple.PropertyValues
  PropertyValue[] getAll()
  PropertyValue getValue(PropertyRef prop)
 
org.w3c.ddr.simple.ServiceFactory  // Class
  static Service newService(
    String clazz,
    String defaultVocabulary,
    Properties configuration
  )
  public static Service newService(
    String defaultVocabulary,
    Properties configuration
  )
 
 
 
---Rotan
 

________________________________

From: public-ddwg-request@... on behalf of Smith, Kevin, VF-Group
Sent: Wed 27/02/2008 09:19
To: Jo Rabin; public-ddwg@...
Subject: RE: Preview of full latest Java Interface : Comments on SimpleService interface




+1 to removing the word Simple and streamlining the overloaded methods, for the same reasons given...
Kevin

[...]