Copyright © 2008 W3C® (MIT, ERCIM, Keio), All Rights Reserved. W3C liability, trademark and document use rules apply.
Web content delivered to mobile devices usually benefits from being tailored to take into account a range of factors such as screen size, markup language support and image format support. Such information is stored in "Device Description Repositories" (DDRs).
This document describes a simple API for access to DDRs, in order to ease and promote the development of Web content that adapts to its Delivery Context.
This section describes the status of this document at the time of its publication. Other documents may supersede this document. A list of current W3C publications and the latest revision of this technical report can be found in the W3C technical reports index at http://www.w3.org/TR/.
Publication as a Working Draft does not imply endorsement by the W3C Membership. This is a draft document and may be updated, replaced or obsoleted by other documents at any time. It is inappropriate to cite this document as other than work in progress.
This document defines an application program interface (API) for accessing a Device Description Repository (DDR). This API includes operations to access descriptions of devices and to query specific properties.
This document is a First Public Working Draft and a Last Call Working Draft that is intended to progress along the Recommendation Track. The Working Group has published this First Public Working Draft as a Last Call due to previous drafts being publicly available, and a number of implementations that are known to already exist.
This document is published as part of the W3C Mobile Web Initiative (MWI) by the Device Description Working Group. It is a deliverable as defined in the Charter of that group.
Please send comments by 1 May 2008 to public-ddwg-comments@w3.org. This list is archived at http://lists.w3.org/Archives/Public/public-ddwg-comments/.
This document was produced by a group operating under the 5 February 2004 W3C Patent Policy. W3C maintains a public list of any patent disclosures made in connection with the deliverables of the group; that page also includes instructions for disclosing a patent. An individual who has actual knowledge of a patent which the individual believes contains Essential Claim(s) must disclose the information in accordance with section 6 of the W3C Patent Policy.
1 Introduction
1.1 Background to the need for Device Description Repositories
1.2 Scope
2 Reading the Recommendation
2.1 Normative and Informative Parts
2.2 Normative Language for Conformance Requirements
3 Vocabularies
4 Interfaces
4.1 Interface Definitions
4.2 Supporting Interfaces
4.2.1 Evidence Interface
4.2.1.1 Methods
4.2.2 PropertyName Interface
4.2.2.1 Methods
4.2.3 PropertyRef Interface
4.2.3.1 Constants
4.2.3.2 Methods
4.2.4 PropertyValue Interface
4.2.4.1 Methods
4.2.5 PropertyValues
4.2.5.1 Methods
4.3 Service Interface
4.3.1 Factory Methods
4.3.1.1 Create Evidence
4.3.1.2 Create PropertyName
4.3.1.3 Create PropertyRef
4.3.2 Query Methods
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.3 Information Methods
4.3.3.1 Get Version Information
4.3.3.2 List Available Properties
4.3.4 Initialization
4.4 Exceptions
4.4.1 SystemException Class
4.4.1.1 Methods
4.4.1.2 Codes
4.4.2 DDRException Class
4.4.2.1 Methods
4.4.2.2 Codes
4.4.3 InitializationException
4.4.3.1 Codes
4.4.4 NameException Class
4.4.4.1 Codes
4.4.5 ValueException Class
4.4.5.1 Codes
4.5 ServiceFactory Class
4.5.1 Methods
5 Conformance
A Java Representation
B Normative References
C Other Representations of the DDR Simple API (Non-Normative)
D Informative References (Non-Normative)
E Acknowledgements (Non-Normative)
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 getAPIVersion() | |
String getDataVersion() | |
PropertyRef[] listPropertyRefs() | |
void initialize(String defaultVocabularyIRI, java.util.Properties props) | |
ServiceFactory | Service newService(String clazz, String defaultVocabulary, Properties configuration) |
This section is informative.
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.
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 (DC) and allows it to query the DDR for values of properties of the DC 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 "Web browser". 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 DDRs.
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.
This section is normative.
The normative and informative parts of this Recommendation are identified by use of labels within various sections.
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] .
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).
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 must 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.
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 name.
Vocabularies also define the data types of values associated with their Properties. The data types supported are boolean, int, long, float, double, String and 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.
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]).
This section is normative.
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).
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.
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.
The name of a Property together with its namespace. See 3 Vocabularies for a discussion of Properties and namespaces.
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.
PropertyValue models a PropertyRef
together with its value. Values may be empty, in which case the method exists
returns false
. An attempt to query an empty value causes a ValueException
as does an attempt to query a value with an incompatible accessor method (string as float, for example). For the getString
method implementations must return an implementation dependent String representation if the type of the value is not natively String. For other methods if the underlying type of the data does not match the method signature then a ValueException
must be thrown.
Value Retrieval
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.
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:
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.
Create Empty Evidence
public Evidence newHTTPEvidence();
Create 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.
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;
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.
Query methods return values for Properties of the Delivery Context represented by the supplied Evidence
.
The following types of query method exist:
Return all Available Values
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;
Return values for all the supplied Properties, returning empty values for those that are not known.
public PropertyValues getPropertyValues(Evidence evidence, PropertyRef[] propertyRefs) throws NameException;
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;
Get Implementation Version
public String getAPIVersion();
Returns information about the implementation of the API including the current version.
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 support versioning of data then a SystemException
should be thrown.
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.
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.
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).
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.
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.
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.
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.
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.
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
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.
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.
The Java representation of the DDR Simple API defines a factory for instantiating Service
with the supplied default namespace and configuration.
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);
The normative Java representation of the DDR Simple API is available as a JAR file, and as Javadoc.
A non-normative OMG IDL [IDL] representation for the DDR Simple API may be used to create other language representations.
There is a non-normative WSDL [WSDL] representation for the DDR Simple API.
For other non-normative representations see [DDWG]