Device Description Repository Simple API 1f

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 has been common, for some time, to use the technique of "browser sniffing" to determine possibly small but important differences between various desktop Web browsers and adapt content to accommodate those differences.

The number of different properties that affect the usability of the resulting content for the desktop Delivery Context 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, as well as differences in implementation and support between Web browsers which typically vary by many factors including markup languages supported and image formats supported.

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 the sine qua non 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 Development of the Simple API Recommendation

Editorial Note Rev 1f (JR): Would this section better be placed into a note?

By charter, the DDWG's work was limited to providing an API into a DDR, and to consider only those applications of DDRs that relate to the delivery of Web content to mobile devices.

It was recognised at the time of creation of the charter that there are many other similar use cases, including delivery of non Web content (such as MMS) to mobile devices, as well as delivery of Web content to some types of non mobile devices which may share some of restrictions and wide variations of mobile devices.

It was also recognized that by their very nature, DDRs are limited to describing the values of properties of devices that can be known "a priori". For example, while it may be known that the screen size of a particular device is a certain number of pixels, and while it may also be known that the screen orientation can change from landscape to portrait, it cannot be known a priori what the orientation is at any particular moment.

In the course of the work of the DDWG it became clear that having an API that revealed only the a properties of a particular device that can be known a priori, and a potentially different api to reveal those that can not, would entail usability difficulties for creators of software that uses API. For instance, in the example above relating to screen orientation use of a DDR API would reveal the screen orientation for some set of devices, but for other devices leave the need for further, possibly unrelated, API calls to determine the actual screen orientation. It was felt that such a situation would not serve the community of software developers well.

Unfortunately, categorization of properties into classes of "can not be known a priori" (sometimes called dynamic properties) and "can be known a priori" (sometimes called static properties) turns out to be fraught with difficulties, leaving most properties in the category of "can not be known a priori on some set of devices".

Additionally, as work progressed, the DDWG gained an increasing understanding that properties refer in some cases to the Delivery Context as a whole, and in other cases to specific constituent components of the Delivery Context. For example, screen width and height are often considered to be properties of the device hardware, but more usefully to the developer, they might be considered to represent the size of the canvas when operating system and browser chrome, together with scroll bars are taken into account. In other cases, for example, the properties Vendor, Model and Version, each constituent component of the delivery context has a separate and discrete identity, so it is unhelpful to regard these properties as being a superposition of the contributions of the various individual components.

Moreover, it is possible that more than one component of the same type may be present in the delivery context. The type of the component was described by the DDWG as an "aspect" of the Delivery Context, and as work on the API progressed it became clear that to provide a complete API that allows both the identification of components present in a Delivery Context and also allows the querying of aspects or specific components of the Delivery Context would be a very significant task, well beyond the scope and charter of the DDWG. Such an API would not be limited to mobile Delivery Contexts and would not be limited to determining a priori information.

The DDWG, recognizing the urgent need for an API to ease and promote the development of adaptive context aware content - specifically mobile Web content - decided to create a "simple" API that fulfils the majority of needs of the "Run Time" use case. It decided also to documenting its findings to contribute to a possible future activity in a Working Group chartered to consider uses cases that go beyond the limitations of mobile repository derived information.

1.3 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. These are collectively also referred to as cataloging functions. By contrast, the run time use case represents the determining of 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 property values of aspects of the DC identified. In addition, it provides access to basic catalog information that allows it to find out about 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 types of components that compose a specific Delivery Context (its aspects) are in general many and various. 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 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 4 Vocabularies.

This Recommendation provides a normative definition of the interface based on OMG IDL [IDL]. In addition, it provides a normative WSDL [WSDL] and Java [Java] bindings.

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

2.3 Language Bindings

This Recommendation identifies three normative language bindings, IDL, Java and WSDL.

Interfaces are identified in the text in the following ways:

//IDL Example
public Example exampleMethod();

//Java Example
public Example exampleMethod();

//WSDL Example
public Example exampleMethod();

Full bindings are provided for each language as Appendices (see A IDL Definitions for Simple API , B Java Bindings and C WSDL Language Binding).

3.1 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 3.2 Service Interface, it is this interface that contains the factory methods for creating instances of the interfaces discussed here.

3.2 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 [@@(q.v.)] class. The class invokes the initialize method to establish a default vocabulary and to pass implementation specific settings.

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:

• 3.2.1 Query Methods

• 3.2.2 Factory Methods

• 3.2.3 Information Methods

• 3.2.4 Initialization

3.3 Exceptions

say something nice about exceptions

3.4 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;
	}
	
	public static Service newService(String defaultVocabulary,
		Properties configuration) throws SystemException, NameException {	
		return null;
	}

5.1 General Conformance Requirements

A conforming implementation of this Recommendation must implement all the normative sections of this document outside the appendices and must implement a binding conformant with one of the following sections.

5.2 Conformance Requirements (Languages where there is a Normative Binding)

Implementations must observe the general conformance requirements as well as implementing in full the appropriate interfaces described in normative appendices of this document.

5.3 Conformance Requirements (Languages where there is no Normative Binding)

Editorial Note Rev 1f (Jo): er, it must be nice? and not too expensive?