Device Description Repository Simple API 1g

1.1 Background to the need for Device Description Repositories

The need for Device Descriptions (information about the properties of various aspects 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. As a result of this, 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 supports only 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 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 simple API does not expose these two activities as distinct to the user of the API.

The there are many different types of components that compose a specific Delivery Context (known as its Aspects). Different Vocabularies (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 other Vocabularies.

There are an indefinite number of possible Properties that are descriptive of the Delivery Context. The simple API does not define any Properties nor 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 Simple DDR API in Java [Java] and provides informative IDL and WSDL versions derived from the Java definition.

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

4.1 Interface Definitions

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

Interfaces are identified in the text in the following way:

public Example exampleMethod();

A full Java definition is provided as an Appendix (see A Java Bindings). Informative IDL and WSDL versions are also provided (see C IDL Definitions for Simple API and D WSDL Language Binding).

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 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.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 Instantiation). 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.4 Exceptions

say something nice about exceptions

4.5 Instantiation

This needs a bit of cleaning up

The DDR Simple API defines a normative factory class, which instantiates Service with the supplied default namespace and configuration.

public class ServiceFactory {
	public static Service newService(String clazz,
		String defaultVocabulary, Properties configuration)
		throws SystemException, NameException {
			Service theService = null;
			try {
				// Instantiation
				theService = (Service) 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;
	}