W3C

Device Description Repository Simple API

W3C Recommendation 05 December 2008

This version:
http://www.w3.org/TR/2008/REC-DDR-Simple-API-20081205/
Latest version:
http://www.w3.org/TR/DDR-Simple-API/
Previous version:
http://www.w3.org/TR/2008/PR-DDR-Simple-API-20080917/
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

Please refer to the errata for this document, which may include some normative corrections.

See also translations.


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

This document, the "Device Description Repository Simple API", is a W3C Recommendation. It reflects editorial changes made as a result of comments received during the Proposed Recommendation period which are detailed in Appendix B. A "Disposition of Comments" report is available at http://www.w3.org/2006/02/lc-comments-tracker/37583/WD-DDR-Simple-API-20080404/doc/single. An implementation report is available at http://www.w3.org/2005/MWI/DDWG/drafts/api/test-report.html.

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. This specification is considered stable by the DDWG Working Group. Please send public comments to public-ddwg-comments@w3.org. This list is archived at http://lists.w3.org/Archives/Public/public-ddwg-comments/.

This document has been reviewed by W3C Members, by software developers, and by other W3C groups and interested parties, and is endorsed by the Director as a W3C Recommendation. It is a stable document and may be used as reference material or cited from another document. W3C's role in making the Recommendation is to draw attention to the specification and to promote its widespread deployment. This enhances the functionality and interoperability of the Web.

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 HTTP 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 Changes Since Previous Version
C Normative References
D Other Representations of the DDR Simple API (Non-Normative)
E Informative References (Non-Normative)
F 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 getImplementationVersion()
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 Description 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, using Java [Java] as a means of expression. Also included are non-normative representations in OMG Interface Definition Language [IDL] and the Web Services Definition Language [WSDL].

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 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 D 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
  1. Add Evidence (Header name, Header value)

    public void put(String key, String value);
  2. Query Evidence (Header name)

    public boolean exists(String key);
  3. 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
  1. Get Property Name

    public String getLocalPropertyName();
  2. 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.

4.2.3.1 Constants
  1. Null Aspect

    public static final String NULL_ASPECT = "__NULL";

    This value is used to support Vocabularies that do not distinguish Aspects.

4.2.3.2 Methods
  1. Get Property Name

    public String getLocalPropertyName();
  2. Get Aspect Name

    public String getAspectName();
  3. Get Namespace

    public String getNamespace();

4.2.4 PropertyValue Interface

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.

4.2.4.1 Methods
  1. 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;
  2. Existence

    public boolean exists();

    True if a value is available, false otherwise.

  3. 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
  1. Get All Properties in the Set

    public PropertyValue[] getAll();
  2. 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

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
  1. Create Empty HTTP Evidence

    public Evidence newHTTPEvidence();
  2. 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
  1. Create PropertyName using Default Vocabulary

    public PropertyName newPropertyName(String localPropertyName)
    	throws NameException;
  2. Create PropertyName with specified Vocabulary

    public PropertyName newPropertyName(String localPropertyName, String vocabularyIRI)
    	throws NameException;
4.3.1.3 Create PropertyRef
  1. 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.

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

  3. 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
  1. 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;
  2. Return all known values for the given Aspect of the Default Vocabulary

    public PropertyValues getPropertyValues(Evidence evidence,
    	String localAspectName) 
    	throws NameException;
  3. 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
  1. 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
  1. Return the value of a specific Property

    public PropertyValue getPropertyValue(Evidence evidence,
    	PropertyRef propertyRef) 
    	throws NameException;
  2. 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;
  3. Return the value of a specific Property in its Default Aspect in the Default Vocabulary

    public PropertyValue getPropertyValue(Evidence evidence,
    	String localPropertyName) 
    	throws NameException;
  4. 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
  1. 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.

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

  1. 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 (D Other Representations of the DDR Simple API).

4.4.1.1 Methods
  1. Get Message

    public String getMessage();
  2. Get Code

    public int getCode();
4.4.1.2 Codes
  1. 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.

  2. 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
  1. Get Message

    public String getMessage();
  2. Get Code

    public int getCode();
4.4.2.2 Codes
  1. 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
  1. 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
  1. PROPERTY_NOT_RECOGNIZED

    public static int PROPERTY_NOT_RECOGNIZED = 100;

    The name of a Property is in error

  2. ASPECT_NOT_RECOGNIZED

    public static int ASPECT_NOT_RECOGNIZED = 800;

    The name of an Aspect is in error

  3. 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
  1. NOT_KNOWN

    public static int NOT_KNOWN = 900;

    The property value is unknown.

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

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

A Java Representation

The DDR Simple API is available as a JAR file, and as Javadoc.

B Changes Since Previous Version

The following changes have been made since the Proposed Recommendation version of this document:

The following changes were made between the Last Call Working Draft and the Proposed Recommendation:

C 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 1.0 (Second Edition), W3C Recommendation, Tim Bray, Dave Hollander, Andrew Layman, Richard Tobin (eds.), 16 August 2006 (See http://www.w3.org/TR/2006/REC-xml-names-20060816/)

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

E 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.), 14 April 2008 (See http://www.w3.org/TR/2008/NOTE-ddr-core-vocabulary-20080414/)
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)

F 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: