org.w3c.ddr.simple
Interface Service

public interface Service

This is the 'simple' interface to a DDR service, via which you retrieve properties of the delivery context based on available (HTTP) evidence.

Author:

Jo Rabin (dotMobi),
Jose Manuel Cantera Fonseca (Telefonica I+D),
Rotan Hanrahan (MobileAware),
Ignacio Marin (Fundacion CTIC)
Copyright © 2008 W3C^® (MIT, ERCIM, Keio), All Rights Reserved.
W3C liability, trademark and document use rules apply.

Field Summary

static java.lang.String

NOT_SUPPORTED This constant value is used to indicate that a feature is not supported, when returned by a String method.

Method Summary

java.lang.String	getDataVersion() An informative implementation-specific method to indicate the revision level of the underlying data, if known.
java.lang.String	getImplementationVersion() A informative implementation-specific method to determine the version of the implementation of the API.
PropertyValue	getPropertyValue(Evidence evidence, PropertyName propertyName) Use the evidence provided to get the PropertyValue of the property named by the propertyName in the vocabulary given by the propertyName and in the default aspect of the property according to the property's vocabulary.
PropertyValue	getPropertyValue(Evidence evidence, PropertyRef propertyRef) Use the evidence provided to get the PropertyValue of the property named by the propertyRef, in the property vocabulary given by the propertyRef and in the aspect also given by the propertyRef.
PropertyValue	getPropertyValue(Evidence evidence, java.lang.String localPropertyName) Use the evidence provided to get the value of the property named by the localPropertyName, which is a term in the default property vocabulary defined during initialization and in the default aspect for the property as defined in the default property vocabulary.
PropertyValue	getPropertyValue(Evidence evidence, java.lang.String localPropertyName, java.lang.String localAspectName, java.lang.String vocabularyIRI) Use the evidence provided to get the value of the property named by the localPropertyName, which is a term in the given vocabulary of properties identified by a namespace IRI and in the given aspect for the property.
PropertyValues	getPropertyValues(Evidence evidence) Use the evidence provided to get all of the available values of properties in the default property vocabulary.
PropertyValues	getPropertyValues(Evidence evidence, PropertyRef[] propertyRefs) Use the evidence provided to get the value of each property in the array of PropertyRef instances.
PropertyValues	getPropertyValues(Evidence evidence, java.lang.String localAspectName) Use the evidence provided to get all of the available values for all properties in the default vocabulary whose aspect is the localAspectName.
PropertyValues	getPropertyValues(Evidence evidence, java.lang.String localAspectName, java.lang.String vocabularyIRI) Use the evidence provided to get all of the available values for all properties in the given vocabulary whose aspect is the localAspectName.
void	initialize(java.lang.String defaultVocabularyIRI, java.util.Properties props) Called to initialize the API following construction.
PropertyRef[]	listPropertyRefs() List all the PropertyRefs the implementation knows about.
Evidence	newHTTPEvidence() Factory method to create an object supporting the Evidence interface, intended to represent HTTP headers.
Evidence	newHTTPEvidence(java.util.Map<java.lang.String,java.lang.String> map) Factory method to create an object supporting the Evidence interface, using name/value pairs from the Map parameter, representing evidence from HTTP headers.
PropertyName	newPropertyName(java.lang.String localPropertyName) Factory method to create a new PropertyName instance in the default property vocabulary.
PropertyName	newPropertyName(java.lang.String localPropertyName, java.lang.String vocabularyIRI) Factory method to create a new PropertyName instance in the given property vocabulary.
PropertyRef	newPropertyRef(PropertyName propertyName) Factory method to create a PropertyRef instance using the name and vocabulary of the PropertyName parameter.
PropertyRef	newPropertyRef(PropertyName propertyName, java.lang.String localAspectName) Factory method to create a PropertyRef instance using the name and vocabulary of the PropertyName parameter.
PropertyRef	newPropertyRef(java.lang.String localPropertyName) Factory method to create a PropertyRef instance in the default vocabulary.

Field Detail

NOT_SUPPORTED

static final java.lang.String NOT_SUPPORTED

This constant value is used to indicate that a feature is not supported, when returned by a String method.

The value of this constant shall be "__NOT_SUPPORTED".

See Also:

Constant Field Values

Method Detail

initialize

void initialize(java.lang.String defaultVocabularyIRI,
                java.util.Properties props)
                throws NameException,
                       InitializationException

Called to initialize the API following construction.

Parameters:

defaultVocabularyIRI - The IRI of the default vocabulary namespace

props - Implementation dependent properties

Throws:

NameException - MUST be thrown if the implementation cannot apply the parameter data.

InitializationException - MUST be thrown in any situation that implies a failure while initializing the DDR (including the case of not being able to instantiate the class).

getImplementationVersion

java.lang.String getImplementationVersion()

A informative implementation-specific method to determine the version of the implementation of the API. This is for use in cases where the service has been constructed via a factory, or similarly determined at run-time, and supports diagnostic use-cases.

Returns:

A human-readable string containing information about the implementation of the API including the current version

getDataVersion

java.lang.String getDataVersion()

An informative implementation-specific method to indicate the revision level of the underlying data, if known. The information provided by this method, where information is returned, shall not be required to reveal any details of the nature of the underlying data, including any source(s). Whether or not the underlying implementation combines more than one source of data is opaque to the user of the API which makes no assumptions about the number of sources of data

Returns:

A String indicating the revision level of the data, which will be different to any previously returned value if the underlying implementation cannot guarantee that the data has not changed since the last time this method was called.
Note: the NOT_SUPPORTED constant is returned if the implementation does not support data versioning.

listPropertyRefs

PropertyRef[] listPropertyRefs()

List all the PropertyRefs the implementation knows about.

Returns:

A list of all the PropertyRefs that are known to the implementation.

getPropertyValue

PropertyValue getPropertyValue(Evidence evidence,
                               PropertyRef propertyRef)
                               throws NameException

Use the evidence provided to get the PropertyValue of the property named by the propertyRef, in the property vocabulary given by the propertyRef and in the aspect also given by the propertyRef. The aspect IRI is determined by the propertyRef (which means it is the same as the property vocabulary IRI). If no aspect term is defined by the propertyRef, use the default aspect term for the property as defined in the property vocabulary.

Parameters:

evidence - Evidence with which to identify the delivery context.

propertyRef - Identification of the property whose value is being queried.

Returns:

the PropertyValue of the identified property.

Throws:

NameException - MUST be thrown (with codes NameException.VOCABULARY_NOT_RECOGNIZED or NameException.PROPERTY_NOT_RECOGNIZED) if the name data in the propertyRef parameter is invalid.

getPropertyValue

PropertyValue getPropertyValue(Evidence evidence,
                               PropertyName propertyName)
                               throws NameException

Use the evidence provided to get the PropertyValue of the property named by the propertyName in the vocabulary given by the propertyName and in the default aspect of the property according to the property's vocabulary.

Parameters:

evidence - Evidence with which to identify the delivery context.

propertyName - Identification of the property whose value is being queried.

Returns:

the PropertyValue of the identified property.

Throws:

NameException - MUST be thrown (with codes NameException.VOCABULARY_NOT_RECOGNIZED or NameException.PROPERTY_NOT_RECOGNIZED) if the name data in the propertyName parameter is invalid.

getPropertyValue

PropertyValue getPropertyValue(Evidence evidence,
                               java.lang.String localPropertyName)
                               throws NameException

Use the evidence provided to get the value of the property named by the localPropertyName, which is a term in the default property vocabulary defined during initialization and in the default aspect for the property as defined in the default property vocabulary. The namespace IRI of the aspect is the same as the IRI for the default vocabulary og properties.

Parameters:

evidence - Evidence with which to identify the delivery context.

localPropertyName - The local name (identifier) of the property as per the default vocabulary of properties.

Returns:

the PropertyValue of the identified property.

Throws:

NameException - MUST be thrown (with code NameException.PROPERTY_NOT_RECOGNIZED) if the localPropertyName parameter is invalid.

getPropertyValue

PropertyValue getPropertyValue(Evidence evidence,
                               java.lang.String localPropertyName,
                               java.lang.String localAspectName,
                               java.lang.String vocabularyIRI)
                               throws NameException

Use the evidence provided to get the value of the property named by the localPropertyName, which is a term in the given vocabulary of properties identified by a namespace IRI and in the given aspect for the property. The namespace IRI of the aspect is the same as the namespace for the given vocabulary of properties.

Parameters:

evidence - Evidence with which to identify the delivery context.

localPropertyName - The local name (identifier) of the property as per the vocabulary of properties whose namespace is given.

localAspectName - The local name (identifier) of the aspect, whose namespace is the same as that of the vocabulary of properties.

vocabularyIRI - The namesapce IRI for the vocabulary of properties.

Returns:

the PropertyValue of the identified property.

Throws:

NameException - MUST be thrown (with codes NameException.VOCABULARY_NOT_RECOGNIZED or NameException.PROPERTY_NOT_RECOGNIZED or NameException.ASPECT_NOT_RECOGNIZED) if any of the name data in the String parameters is invalid.

getPropertyValues

PropertyValues getPropertyValues(Evidence evidence)
                                 throws NameException

Use the evidence provided to get all of the available values of properties in the default property vocabulary. This includes all property terms from all supported vocabularies, and in each of the aspects supported by the property vocabularies, and for every aspect IRI that is supported. Combinations of property/aspect that are not supported are not returned in the PropertyValues collections.

Parameters:

evidence - Evidence with which to identify the delivery context.

Returns:

an instance of PropertyValues containing PropertyValue objects representing all available values for the evidence supplied.

Throws:

NameException - for consistency with other versions of this method, but if this method does throw a NameException then it should be treated as an implementation error because there are no circumstances when this method could actually throw a NameException

getPropertyValues

PropertyValues getPropertyValues(Evidence evidence,
                                 PropertyRef[] propertyRefs)
                                 throws NameException

Use the evidence provided to get the value of each property in the array of PropertyRef instances. The aspect term is determined by the individual PropertyRef instances. Where the aspect term is undefined, use the default aspect term in the property's vocabulary. As the order of elements obtained via PropertyValues.getAll() is implementation-specific it is not correct to assume that the order of elements in propertyRefs will influence the order of the array returned by PropertyValues.getAll(). The PropertyValues.getValue(PropertyRef) method provides a more direct and interoperable means of inspecting the return value.

Parameters:

evidence - Evidence with which to identify the delivery context.

propertyRefs - Identification of the properties whose values are being queried.

Returns:

an instance of PropertyValues containing PropertyValue objects identified by the supplied evidence.

Throws:

NameException - MUST be thrown (with codes NameException.VOCABULARY_NOT_RECOGNIZED or NameException.PROPERTY_NOT_RECOGNIZED or NameException.ASPECT_NOT_RECOGNIZED) if any name data in the propertyRefs parameter is invalid.

getPropertyValues

PropertyValues getPropertyValues(Evidence evidence,
                                 java.lang.String localAspectName)
                                 throws NameException

Use the evidence provided to get all of the available values for all properties in the default vocabulary whose aspect is the localAspectName. The namespace of the aspect is the same as the default vocabulary IRI.

Parameters:

evidence - Evidence with which to identify the delivery context.

localAspectName - The name of the aspect, whose namespace is the same as the default vocabulary of properties.

Returns:

an instance of PropertyValues containing PropertyValue objects identified by the supplied evidence in the given aspect.

Throws:

NameException - MUST be thrown (with code NameException.ASPECT_NOT_RECOGNIZED) if the localAspectName parameter is invalid.

getPropertyValues

PropertyValues getPropertyValues(Evidence evidence,
                                 java.lang.String localAspectName,
                                 java.lang.String vocabularyIRI)
                                 throws NameException

Use the evidence provided to get all of the available values for all properties in the given vocabulary whose aspect is the localAspectName. The namespace of the aspect is the same as the given vocabulary IRI.

Parameters:

evidence - Evidence with which to identify the delivery context.

localAspectName - The name of the aspect, whose namespace is the same as the vocabulary of properties.

vocabularyIRI - The namespace of the vocabulary of properties.

Returns:

an instance of PropertyValues containing PropertyValue objects in the given vocabulary and aspect, identified by the supplied evidence.

Throws:

NameException - MUST be thrown (with codes NameException.VOCABULARY_NOT_RECOGNIZED or NameException.ASPECT_NOT_RECOGNIZED) if any name data in the String parameters is invalid.

newPropertyName

PropertyName newPropertyName(java.lang.String localPropertyName)
                             throws NameException

Factory method to create a new PropertyName instance in the default property vocabulary.

Parameters:

localPropertyName - The local name (identifier) of the property as given in the default vocabulary.

Returns:

a new PropertyName instance.

Throws:

NameException - MUST be thrown (with code NameException.PROPERTY_NOT_RECOGNIZED ) if the localPropertyName parameter is invalid.

newPropertyName

PropertyName newPropertyName(java.lang.String localPropertyName,
                             java.lang.String vocabularyIRI)
                             throws NameException

Factory method to create a new PropertyName instance in the given property vocabulary.

Parameters:

localPropertyName - The local name (identifier) of the property as given in its vocabulary.

vocabularyIRI - The namespace of the property.

Returns:

a new PropertyName instance.

Throws:

NameException - MUST be thrown (with codes NameException.VOCABULARY_NOT_RECOGNIZED or NameException.PROPERTY_NOT_RECOGNIZED) if any of the parameters is invalid.

newPropertyRef

PropertyRef newPropertyRef(java.lang.String localPropertyName)
                           throws NameException

Factory method to create a PropertyRef instance in the default vocabulary. The aspect is determined by the default aspect according to the vocabulary of the property. If the property has no default aspect defined in the vocabulary, the PropertyRef.NULL_ASPECT is used.

Parameters:

localPropertyName - The name of the property as given in the default vocabulary.

Returns:

a new PropertyRef instance.

Throws:

NameException - MUST be thrown (with code NameException.PROPERTY_NOT_RECOGNIZED) if the localPropertyName parameter is invalid.

newPropertyRef

PropertyRef newPropertyRef(PropertyName propertyName)
                           throws NameException

Factory method to create a PropertyRef instance using the name and vocabulary of the PropertyName parameter. The aspect is determined by the default aspect according to the vocabulary of the property. If the property has no default aspect defined in the vocabulary, the PropertyRef.NULL_ASPECT is used.

Parameters:

propertyName - A property belonging to a specific vocabulary.

Returns:

a new PropertyRef instance.

Throws:

NameException - MUST be thrown (with codes NameException.VOCABULARY_NOT_RECOGNIZED or NameException.PROPERTY_NOT_RECOGNIZED) if the name data in the propertyName parameter is invalid.

newPropertyRef

PropertyRef newPropertyRef(PropertyName propertyName,
                           java.lang.String localAspectName)
                           throws NameException

Factory method to create a PropertyRef instance using the name and vocabulary of the PropertyName parameter. The aspect name is given, and the namespace IRI of the aspect is the same as the IRI of the vocabulary of the PropertyName parameter.

Parameters:

propertyName - A property belonging to a specific vocabulary.

localAspectName - The name of the aspect as given in the default vocabulary.

Returns:

a new PropertyRef instance.

Throws:

NameException - MUST be thrown (with codes NameException.VOCABULARY_NOT_RECOGNIZED or NameException.PROPERTY_NOT_RECOGNIZED or NameException.ASPECT_NOT_RECOGNIZED) if any name data in the parameters is invalid.

newHTTPEvidence

Evidence newHTTPEvidence()

Factory method to create an object supporting the Evidence interface, intended to represent HTTP headers. The object constructed by this factory is assumed to be aware of the case-insensitivity of HTTP headers.

Returns:

an empty Evidence instance, suitable for population with HTTP headers.

newHTTPEvidence

Evidence newHTTPEvidence(java.util.Map<java.lang.String,java.lang.String> map)

Factory method to create an object supporting the Evidence interface, using name/value pairs from the Map parameter, representing evidence from HTTP headers. The object constructed by this factory is assumed to be aware of the case-insensitivity of HTTP headers.

NOTE: Versions of this interface pre-Java1.5 replace java.util.Map<String,String> with java.util.Map

Parameters:

map - Mapping of names to values, assumed to represent HTTP headers.

Returns:

an Evidence instance populated with HTTP headers.