W3C

Device Description Repository Simple API

W3C Working Draft 4 April 2008

This version:
http://www.w3.org/TR/2008/WD-DDR-Simple-API-20080404/
Latest version:
http://www.w3.org/TR/DDR-Simple-API/
Previous version:
No previous version
Editors:
Jo Rabin, dotMobi (mTLD Top Level Domain)
José Manuel Cantera Fonseca, Telefónica I+D
Rotan Hanrahan, MobileAware
Ignacio Marín, Fundación CTIC

Abstract

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.

Status of this Document

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.

Table of Contents

Summary of Methods

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

Appendices

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)


Summary of Methods

Interface / ClassMethod
EvidenceString get(String key)
boolean exists(String key)
void put(String key, String value)
PropertyNameString getLocalPropertyName()
String getNamespace()
PropertyRefString getLocalPropertyName()
String getAspectName()
String getNamespace()
PropertyValuedouble getDouble() long getLong() String getString() boolean getBoolean() int getInteger() String[] getEnumeration() float getFloat()
boolean exists()
PropertyRef getPropertyRef()
PropertyValuesPropertyValue[] getAll()
PropertyValue getValue(PropertyRef prop)
ServiceEvidence 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)
ServiceFactoryService newService(String clazz, String defaultVocabulary, Properties configuration)

1 Introduction

This section is informative.

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 (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.

2 Reading the Recommendation

This section is normative.

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).

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]).

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.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

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.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.4 Initialization

  1. Initialize the Library

    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.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.

5 Conformance

This section is normative.

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

A Java Representation

The normative Java representation of the DDR Simple API is available as a JAR file, and as Javadoc.

B Normative References

RFC 2119
Key words for use in RFCs to Indicate Requirement Levels, S. Bradner, March 1997 (See http://www.ietf.org/rfc/rfc2119.txt)
Java
The Java Language Specification, Third Edition (See http://java.sun.com/docs/books/jls/third_edition/html/j3TOC.html)
XML Namespaces
Namespaces in XML, W3C Recommendation, Tim Bray, Dave Hollander, Andrew Layman (eds.), 14 January 1999 (See http://www.w3.org/TR/1999/REC-xml-names-19990114/)

C Other Representations of the DDR Simple API (Non-Normative)

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]

D Informative References (Non-Normative)

DDWG
DDWG Home Page (See http://www.w3.org/2005/MWI/DDWG/)
DIGLOSS
Glossary of Terms for Device Independence, W3C Working Draft, Rhys Lewis (ed.), 18 January 2005 (See http://www.w3.org/TR/2005/WD-di-gloss-20050118)
Core Vocabulary
Device Description Repository Core Vocabulary, W3C Working Draft, Andrea Trasatti, Jo Rabin, Rotan Hanrahan (eds.), 18 December 2007 (See http://www.w3.org/TR/ddr-core-vocabulary/)
Requirements
Device Description Repository Requirements 1.0, W3C Working Group Note, Kevin Smith (ed.), 17 December 2007 (See http://www.w3.org/TR/DDR-requirements/)
Landscape
Device Description Landscape 1.0, W3C Working Group Note, Eman Nkeze, James Pearce, Matt Womer (eds.), 31 October 2007, (See http://www.w3.org/TR/2007/NOTE-dd-landscape-20071031/)
Ecosystem
Device Description Ecosystem 1.0, W3C Working Group Note, Rotan Hanrahan (ed.), 31 October 2007 (See http://www.w3.org/TR/2007/NOTE-dd-ecosystem-20071031/)
Delivery Context Ontology
Delivery Context Ontology, W3C Working Draft, Rhys Lewis (ed.), 21 December 2007 (See http://www.w3.org/TR/dcontology/)
WSDL
Web Services Description Language (WSDL) 1.1, W3C Note, Erik Christensen, Francisco Curbera, Greg Meredith, Sanjiva Weerawarana, 15 March 2001 (See http://www.w3.org/TR/wsdl)
IDL
OMG IDL Syntax and Semantics, Object Management Group. (See http://www.omg.org/technology/documents/formal/corba_2.htm)

E Acknowledgements (Non-Normative)

The editors wish to acknowledge the contributions of members of the DDWG.

The editors wish to acknowledge the specific written contributions of: