Device Description Repository Simple API 1o

Interface / Class	Method
Evidence	String get(String key)
boolean exists(String key)
void put(String key, String value)
PropertyName	String getLocalPropertyName()
String getNamespace()
PropertyRef	String getLocalPropertyName()
String getAspectName()
String getNamespace()
PropertyValue	double getDouble() long getLong() String getString() boolean getBoolean() int getInteger() String[] getEnumeration() float getFloat()
boolean exists()
PropertyRef getPropertyRef()
PropertyValues	PropertyValue[] getAll()
PropertyValue getValue(PropertyRef prop)
Service	Evidence newHTTPEvidence()
Evidence newHTTPEvidence(java.util.Map<String,String> map)
PropertyName newPropertyName(String localPropertyName)
PropertyName newPropertyName(String localPropertyName, String vocabularyIRI)
PropertyRef newPropertyRef(String localPropertyName)
PropertyRef newPropertyRef(PropertyName propertyName)
PropertyRef newPropertyRef(PropertyName propertyName, String localAspectName)
PropertyValues getPropertyValues(Evidence evidence)
PropertyValues getPropertyValues(Evidence evidence, String localAspectName)
PropertyValues getPropertyValues(Evidence evidence, String localAspectName, String vocabularyIRI)
PropertyValues getPropertyValues(Evidence evidence, PropertyRef[] propertyRefs)
PropertyValue getPropertyValue(Evidence evidence, PropertyRef propertyRef)
PropertyValue getPropertyValue(Evidence evidence, PropertyName propertyName)
PropertyValue getPropertyValue(Evidence evidence, String localPropertyName)
PropertyValue getPropertyValue(Evidence evidence, String localPropertyName, String localAspectName, String vocabularyIRI)
String getImplementationVersion()
String getDataVersion()
PropertyRef[] listPropertyRefs()
void initialize(String defaultVocabularyIRI, java.util.Properties props)
ServiceFactory	Service newService(String clazz, String defaultVocabulary, Properties configuration)

1 Introduction

1.1 Background to the need for Device Description Repositories

The need for Device Descriptions (information about the Properties [definition] of various Aspects [definition] of the Delivery Context [definition]) is not confined to the mobile Delivery Context. It is common practice for Web sites to detect the type of user agent ("browser sniffing") to determine possibly small but important differences between various desktop Web browsers and adapt content to accommodate those differences.

In the desktop Delivery Context, the number of different Properties that affect the usability of the resulting content is limited, when compared with the number of different Properties of the mobile Delivery Context that affect usability of content. Examples of such Properties include screen dimensions, input methods, memory and CPU constraints. There are also differences between mobile Web browsers including markup languages supported and image formats supported.

As discussed in [Landscape] and [Ecosystem], historically, it has been difficult or impossible to upgrade Web browser software on mobile devices or to add support for features not present in the Web browser originally shipped with the device. This leads to a very wide variation not only of hardware related features but also of features determined by software and firmware. Although the need for content adaptation is a general requirement of the Web as a whole, the need for a more systematic approach is seen as being most urgent in the mobile Delivery Context.

As a result, Device Description Repositories (DDRs) have become essential components of development of content targeted at the mobile Delivery Context. A number of proprietary implementations exist, each with its own API and method of describing the Properties of the Delivery Context.

The Device Descriptions Working Group (DDWG), a Working Group of the W3C Mobile Web Initiative, was chartered to create a single API though which Property values can be retrieved, and a "Core" Vocabulary [Core Vocabulary] that identifies a small number of such Properties.

1.2 Scope

Various use cases for DDRs are detailed in [Requirements]. In summary, the uses fall into two main classes: design time and run time. The design time use case relates to the activities of the planning, UI prototyping, market research and so on for mobile Web applications. By contrast, the run time use case involves determining the actual values of properties that are relevant to a particular application for the delivery of Web content.

The W3C DDR Simple API is designed to support the run time use case. It provides read-only functionality to allow an adapting application to provide Evidence, in the form of HTTP headers, that identifies the Delivery Context and allows it to query the DDR for values of properties of the Delivery Context identified. In addition, it provides access to basic catalog information that allows an application to find out which properties are supported.

The run-time use case consists, in general, of two logically (though not necessarily in practice) distinct activities: Device Recognition and Property Value Retrieval. The DDR Simple API does not expose these two activities as distinct to the user of the API.

There are many different types of components that compose a specific Delivery Context, which are known as its Aspects. Different Vocabularies, or sets of Properties, recognize different Aspects of the Delivery Context that are "essential" to implementing adaptive mobile content. For example, the Core Vocabulary [Core Vocabulary] recognises the Aspects of "device" and "webBrowser". Other Aspects of the Delivery Context may be supported by other Vocabularies.

An indefinite number of possible Properties are descriptive of the Delivery Context. The DDR Simple API does not define any Properties and does not mandate the use of any particular Vocabulary of such Properties. The DDWG strongly recommends that its Core Vocabulary is supported by all implementations of the DDR Simple API.

The requirements of Vocabularies supported by the DDR Simple API are documented in 3 Vocabularies.

This Recommendation provides a normative definition of the DDR Simple API in Java [Java] and provides informative IDL and WSDL versions derived from the Java definition.

2 Reading the Recommendation

This section is normative.

2.1 Normative and Informative Parts

The normative and informative parts of this Recommendation are identified by use of labels within various sections.

2.2 Normative Language for Conformance Requirements

Individual conformance requirements or testable statements are identified in this document by the use of specific key words. In particular, the key words must, must not, required, shall, shall not, should, should not, recommended, may, and optional in this Recommendation are to be interpreted as described in [RFC 2119] .

3 Vocabularies

This section is normative.

From the point of view of the DDR Simple API:

[Definition: An Aspect of the Delivery Context typically represents a category of hardware or software that participates in delivering a Web experience.] "Browser", "proxy" and "device" are all examples of Aspects. Aspects can also represent things other than hardware and software, such as end-users and mobile network operators.

[Definition: A Property is a characteristic of an Aspect that can affect the Web experience.] "Screen Width", "Image Formats Supported", "Color Depth" and "Audio Codecs Supported" are all Properties. Properties have names and data types for their values (boolean, int and so on). A Property may have an "unknown value" when the actual value is not known to the DDR implementation, and in this case the exists() method of the PropertyValue interface must return false.

Property names and Aspect names are namespaced to allow independent naming and evolution of sets of Properties. In the DDR Simple API, Aspects share the same namespace as the properties with which they are associated.

[Definition: A Vocabulary is a set of Properties and the Aspects with which the Properties are associated.] Vocabularies should declare a default Aspect for each Property (the Aspect to be used when using the Vocabulary in an abbreviated convention that does not specify the Aspect).

Note:

This Recommendation does not specify a standard representation (such as an XML serialization) for Vocabularies.

Vocabularies are identified by an IRI and provide a namespace for the Property Names and Aspect Names that compose them. The IRI that identifies the vocabulary also identifies its namespace. Property and Aspect names must be unique in their namespace and must conform to the syntax defined in "Namespaces in XML" [XML Namespaces]. The value __NULL ('_','_','N','U','L','L') is reserved as the null Aspect, to be employed where a vocabulary does not use or distinguish Aspects of the properties it defines.

Vocabularies also define the data types of values associated with their Properties. The data types supported are boolean, int, long, float, double, String and for enumeration, String[], the meanings of which are as defined in [Java]. Where necessary, Vocabularies specify the units of measure of their properties.

The DDWG has published a suggested "Core" Vocabulary for essential Properties for Web content adaptation [Core Vocabulary]. It is anticipated that implementations will extend the Core Vocabulary, which may be used as an example for such extensions. Properties that extend the Core Vocabulary must be in a different namespace to the Core Vocabulary. As mentioned in 1.2 Scope, the DDWG strongly recommends that its Core Vocabulary is supported by all implementations of the DDR Simple API.

The DDWG anticipates that further work on standardization of Properties and Aspects will take place alongside development of the Delivery Context Ontology (see [Delivery Context Ontology]).

4 Interfaces

This section is normative.

4.1 Interface Definitions

This Recommendation defines the DDR Simple API in Java [Java].

Methods are identified in the text in the following way:

public Example exampleMethod();

A normative Java representation of the interfaces and classes of the API is linked from Appendix A Java Representation, together with a link to Javadoc for the representation. Informative IDL and WSDL representations are also provided (see C Other Representations of the DDR Simple API).

4.2 Supporting Interfaces

A number of supporting interfaces are defined for various types of data that are used in the DDR Simple API. They are described in the following sections.

The principal interface of the DDR Simple API, Service, is defined in 4.3 Service Interface, it is this interface that contains the factory methods for creating instances of the interfaces discussed here.

4.2.1 Evidence Interface

When querying Property values (see 4.3.2 Query Methods), Evidence is the general term applied to providing information to the DDR to allow it to determine the Delivery Context. In the DDR Simple API implementations must support Evidence consisting of HTTP Header name and value pairs. Implementations must treat HTTP Header names in a case insensitive manner. HTTP Header values may be case sensitive, depending on the header concerned. Other types of Evidence may be supported by implementations. They are not defined in this Recommendation.

4.2.1.1 Methods

Add Evidence (Header name, Header value)

public void put(String key, String value);

Query Evidence (Header name)
```
public boolean exists(String key);
```
Retrieve Evidence (Header name)
```
public String get(String key);
```

4.2.2 `PropertyName` Interface

The name of a Property together with its namespace. See 3 Vocabularies for a discussion of Properties and namespaces.

4.2.2.1 Methods

Get Property Name
```
public String getLocalPropertyName();
```
Get Namespace
```
public String getNamespace();
```

4.2.3 `PropertyRef` Interface

The name of a Property together with its Aspect together with the namespace they are in. See 3 Vocabularies for a discussion of Properties, Aspects and namespaces. Note that the value __NULL may be used where a Vocabulary does not support the concept of Aspect.

public double getDouble() throws ValueException;
public long getLong() throws ValueException;
public String getString() throws ValueException;
public boolean getBoolean() throws ValueException;
public int getInteger() throws ValueException;	
public String[] getEnumeration() throws ValueException;	
public float getFloat() throws ValueException;

Existence
```
public boolean exists();
```
True if a value is available, false otherwise.
Property Reference
```
public PropertyRef getPropertyRef();
```
The PropertyRef that this PropertyValue refers to.

4.2.5 PropertyValues

A set of PropertyValues.

4.2.5.1 Methods

Get All Properties in the Set
```
public PropertyValue[] getAll();
```

Get the Named Property

public PropertyValue getValue(PropertyRef prop) throws NameException;

4.3 `Service` Interface

The Service interface is the core of the DDR Simple API. Using methods of Service the caller supplies Evidence representing the Delivery Context and an indication of the Properties of interest. These methods return PropertyValue objects which can then be queried to reveal the values of the Properties of interest.

The Service may be instantiated by a supplied factory class (see 4.5 ServiceFactory Class). The class invokes the initialize method to establish a Default Vocabulary and to pass implementation specific settings.

Whether or not the underlying implementation combines more than one source of data is opaque to the user of the API. The API makes no assumptions about the number of sources of data.

All implementations are required to support Evidence consisting of name/value pairs of HTTP headers.

The methods of the Service interface fall into the following categories, which are discussed in the subsequent sections:

4.3.1 Factory Methods
4.3.2 Query Methods
4.3.3 Information Methods
4.3.4 Initialization

4.3.1 Factory Methods

The "Factory" methods defined here provide a means of instantiating objects that support the interfaces defined in this Recommendation that is consistent between implementations. Implementations may provide other means of instantiating the interfaces.

4.3.1.1 Create HTTP Evidence

Create Empty HTTP Evidence
```
public Evidence newHTTPEvidence();
```
Create HTTP Evidence from Map
```
public Evidence newHTTPEvidence(java.util.Map<String,String> map);
```
The Map parameter contains name/value pairs representing HTTP Header names and values. In the case of implementation environments where the default Map is from Object to Object (e.g. Java 1.4) the key and value parameters should be cast to String types.

4.3.1.2 Create `PropertyName`

Create PropertyName using Default Vocabulary

public PropertyName newPropertyName(String localPropertyName)
	throws NameException;

Create PropertyName with specified Vocabulary

public PropertyName newPropertyName(String localPropertyName, String vocabularyIRI)
	throws NameException;

4.3.1.3 Create `PropertyRef`

Create PropertyRef using Default Vocabulary and Aspect
```
public PropertyRef newPropertyRef(String localPropertyName)
	throws NameException;
```
The PropertyRef created is in the default Vocabulary and the Aspect is the default Aspect for the Property in that Vocabulary.
Create PropertyRef from PropertyName using Default Aspect
```
public PropertyRef newPropertyRef(PropertyName propertyName)
	throws NameException;
```
The Aspect of the PropertyRef created is the default Aspect of the Property in the Vocabulary determined by the propertyName parameter.
Create PropertyRef from PropertyName in Named Aspect
```
public PropertyRef newPropertyRef(PropertyName propertyName, String localAspectName)
	throws NameException;
```
The namespace associated with the Aspect localAspectName is associated with the namespace of the propertyName parameter.

4.3.2 Query Methods

Query methods return values for Properties of the Delivery Context represented by the supplied Evidence.

The following types of query method exist:

4.3.2.1 Return Known Values
4.3.2.2 Return the Values of a Specific List
4.3.2.3 Return the Value of a Single Property

4.3.2.1 Return Known Values

Return all available Property values for all the Aspects and Vocabularies known by an implementation of the DDR Simple API
```
public PropertyValues getPropertyValues(Evidence evidence)
	throws NameException;
```

Return all known values for the given Aspect of the Default Vocabulary

public PropertyValues getPropertyValues(Evidence evidence,
	String localAspectName) 
	throws NameException;

Return all known values for an Aspect of a specified Vocabulary

public PropertyValues getPropertyValues(Evidence evidence,
	String localAspectName, String vocabularyIRI) 
	throws NameException;

4.3.2.2 Return the Values of a Specific List

Return values for all the supplied Properties, returning empty values for those that are not known. An "unknown value" is distinguished by the PropertyValue exists() method returning false.
```
public PropertyValues getPropertyValues(Evidence evidence,
	PropertyRef[] propertyRefs)
	throws NameException;
									
```

4.3.2.3 Return the Value of a Single Property

Return the value of a specific Property

public PropertyValue getPropertyValue(Evidence evidence,
	PropertyRef propertyRef) 
	throws NameException;

Return the value of a specific Property in its Default Aspect in the Vocabulary specified by propertyName

public PropertyValue getPropertyValue(Evidence evidence,
	PropertyName propertyName)
	throws NameException;

Return the value of a specific Property in its Default Aspect in the Default Vocabulary

public PropertyValue getPropertyValue(Evidence evidence,
	String localPropertyName) 
	throws NameException;

Return the value of a specific Property with a specific Aspect in a specific Vocabulary.

public PropertyValue getPropertyValue(Evidence evidence,
	String localPropertyName, String localAspectName, String vocabularyIRI) 
	throws NameException;

4.3.3 Information Methods

4.3.3.1 Get Version Information

Get Implementation Version
```
public String getImplementationVersion();
```
Returns information about the implementation of the API including the current version. This may be used for diagnostic purposes, particularly where the implementation language does not already provide a means for obtaining such information.
Get Data Version
```
public String getDataVersion();
```
Returns information about the underlying data (values for Properties) if the implementation has a versioning system for that information. If it does have a versioning system for data then this value must change between calls if the implementation can not guarantee that the data is the same. If the implementation does not have a versioning system, the value __NOT_SUPPORTED ('_','_','N','O','T','_','S','U','P','P','O','R','T','E','D') is returned.

4.3.3.2 List Available Properties

List Properties
```
public PropertyRef[] listPropertyRefs();
```
Lists the combination of all known Properties and Aspects in all Vocabularies that can be used without causing a NameException to be thrown. The order in which Properties are listed is not significant.

4.3.4 Initialization

Initialize the Library
```
public void initialize(String defaultVocabularyIRI, 
	java.util.Properties props)
	throws NameException, InitializationException;
```
Called by the instantiation class (see 4.5 ServiceFactory Class) to initialize the implementation. Implementation specific initialization parameters may be passed using the props parameter.
Note:
Note that the props parameter is of the class java.util.Properties and is not related to Properties of Vocabularies discussed in this document.

4.4 Exceptions

DDR Simple API exceptions can be thrown as a consequence of error conditions that can occur during the execution of API calls. For each exception Class there is an associated set of numeric codes that detail particular error situations. Implementations may create new exceptions and exception codes when needed.

The following sections describe each exception, its methods, associated codes and the conditions under they must be thrown. Implementations should add additional information in the form of messages to assist with diagnosis of the condition that caused the exception to be thrown.

4.4.1 SystemException Class

This exception, a subclass of java.lang.Runtime, is thrown by DDR Simple API implementations when they encounter unrecoverable errors.

Note:

Being a run time exception, SystemException does not require specification as part of a method's throws clause.

Implementations in other languages that do not have the concept of run time exceptions will need to use a different technique. See, for example, the non-normative IDL Definition (C Other Representations of the DDR Simple API).

4.4.1.1 Methods

Get Message
```
public String getMessage();
```
Get Code
```
public int getCode();
```

4.4.1.2 Codes

CANNOT_PROCEED
```
public static int CANNOT_PROCEED = 500;
```
The implementation cannot continue with the processing of the current request due to an unexpected failure - disconnection from a database, for example.
ILLEGAL_ARGUMENT
```
public static int ILLEGAL_ARGUMENT = 400;
```
A method has been passed an illegal or inappropriate argument - a null argument where it is not allowed, for example.

4.4.2 DDRException Class

It is the superclass of all DDR Simple API exceptions other than SystemException.

Implementations should raise subclasses of DDRException, they should not raise this exception directly.

4.4.2.1 Methods

Get Message
```
public String getMessage();
```
Get Code
```
public int getCode();
```

4.4.2.2 Codes

IMPLEMENTATION_ERROR
```
public static int IMPLEMENTATION_ERROR = 65536;
```
This code may be used by implementations to create custom error codes. All implementation specific codes must be greater than this value.

Implementations may define specific codes for different kinds of failures during initialization.

4.4.3 InitializationException

This is a subclass of DDRException and represents an error during the initialization phase of the Simple API. It is thrown only by the initialize method of the Service interface and the newService method of the ServiceFactory class.

4.4.3.1 Codes

INITIALIZATION_ERROR
```
public static int INITIALIZATION_ERROR = 300;
```
There was a problem during initialization.

Implementations may define specific codes for different kinds of failures during initialization.

4.4.4 NameException Class

This is a subclass of DDRException and is thrown when it is detected that the name of a Property or Aspect or vocabulary IRI is in error. The exception code, when set, indicates the nature of the error.

A name of a Property or Aspect or a vocabulary IRI are in error when they are not syntactically valid or are not supported by the implementation.

4.4.4.1 Codes

PROPERTY_NOT_RECOGNIZED
```
public static int PROPERTY_NOT_RECOGNIZED = 100;
```
The name of a Property is in error
ASPECT_NOT_RECOGNIZED
```
public static int ASPECT_NOT_RECOGNIZED = 800;
```
The name of an Aspect is in error
VOCABULARY_NOT_RECOGNIZED
```
public static int VOCABULARY_NOT_RECOGNIZED = 200;
```
A vocabulary IRI is in error

4.4.5 ValueException Class

This is a subclass of DDRException and is thrown when an error is detected during an attempt to retrieve the value of a Property using one of the value accessor methods of the PropertyValue class. The exception code indicates the nature of the error.

4.4.5.1 Codes

NOT_KNOWN
```
public static int NOT_KNOWN = 900;
```
The property value is unknown.
INCOMPATIBLE_TYPES
```
public static int INCOMPATIBLE_TYPES = 600;
```
The value represented by the PropertyValue is incompatible with the return type of the method used to retrieve it.
MULTIPLE_VALUES
```
public static int MULTIPLE_VALUES = 10000;
```
The implementation is aware of multiple values for this Property.

4.5 `ServiceFactory` Class

The Java representation of the DDR Simple API defines a factory for instantiating Service with the supplied default namespace and configuration.

4.5.1 Methods

public static Service newService(String clazz, String defaultVocabulary,
	Properties configuration) throws InitializationException,
	NameException

Instantiates an instance of the class clazz establishing the Default Vocabulary to be the one specified and with implementation specific values passed as java.lang.Properties.

In the following example, ServiceFactory is used to instantiate the class "mobi.example.DDRService" using the ID of the W3C Core Vocabulary to set the default vocabulary, and with no implementation specific properties. Implementations are expected to require at least an indication of how to bind to their source of data, such as a filename or database connection passed in the configuration parameter.

Example:

Service myService = ServiceFactory.newService("mobi.example.DDRService",
	"http://www.w3.org/2008/01/DDR-Core-Vocabulary", null);

5 Conformance

This section is normative.

A conforming implementation of this Recommendation must implement all the normative sections of this document.