1
<?xml version="1.0" encoding="UTF-8"?>
2
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
3
<html xmlns="http://www.w3.org/1999/xhtml" lang="en-US" xml:lang="en-US"><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8" /><title>Device Description Repository Simple API </title><style type="text/css">
4
code { font-family: monospace; }
9
div.notice { margin-left: 2em; }
11
ol.enumar { list-style-type: decimal; }
12
ol.enumla { list-style-type: lower-alpha; }
13
ol.enumlr { list-style-type: lower-roman; }
14
ol.enumua { list-style-type: upper-alpha; }
15
ol.enumur { list-style-type: upper-roman; }
18
div.exampleInner pre { margin-left: 1em;
19
margin-top: 0em; margin-bottom: 0em}
20
div.exampleOuter {border: 4px double gray;
21
margin: 0em; padding: 0em}
22
div.exampleInner { background-color: #d5dee3;
23
border-top-width: 4px;
24
border-top-style: double;
25
border-top-color: #d3d3d3;
26
border-bottom-width: 4px;
27
border-bottom-style: double;
28
border-bottom-color: #d3d3d3;
29
padding: 4px; margin: 0em }
30
div.exampleWrapper { margin: 4px }
31
div.exampleHeader { font-weight: bold;
41
background-color: #BBDDDD;
43
font-family: monospace;
49
</style><link rel="stylesheet" type="text/css" href="../../../StyleSheets/TR/W3C-REC.css" /></head><body><div class="head"><p><a href="http://www.w3.org/"><img src="../../../Icons/w3c_home" alt="W3C" height="48" width="72" /></a></p>
50
<h1><a name="title" id="title"></a>Device Description Repository Simple API </h1>
51
<h2><a name="w3c-doctype" id="w3c-doctype"></a>W3C Recommendation 05 December 2008</h2><dl><dt>This version:</dt><dd>
52
<a href="index.html">http://www.w3.org/TR/2008/REC-DDR-Simple-API-20081205/</a>
53
</dd><dt>Latest version:</dt><dd>
54
<a href="http://www.w3.org/TR/DDR-Simple-API/">http://www.w3.org/TR/DDR-Simple-API/</a>
55
</dd><dt>Previous version:</dt><dd>
56
<a href="http://www.w3.org/TR/2008/PR-DDR-Simple-API-20080917/">http://www.w3.org/TR/2008/PR-DDR-Simple-API-20080917/</a>
57
</dd><dt>Editors:</dt><dd>Jo Rabin, dotMobi (mTLD Top Level Domain)</dd><dd>José Manuel Cantera Fonseca, Telefónica I+D</dd><dd>Rotan Hanrahan, MobileAware</dd><dd>Ignacio Marín, Fundación CTIC</dd></dl>
59
<p>Please refer to the <a href="http://www.w3.org/2008/11/DDR-Simple-API-errata.html"><strong>errata</strong></a> for this document, which may include some normative corrections.</p>
60
<p>See also <a href=" http://www.w3.org/2003/03/Translations/byTechnology?technology=shortname"> <strong>translations</strong></a>.</p>
61
<p class="copyright"><a href="http://www.w3.org/Consortium/Legal/ipr-notice#Copyright">Copyright</a> © 2008 <a href="http://www.w3.org/"><acronym title="World Wide Web Consortium">W3C</acronym></a><sup>®</sup> (<a href="http://www.csail.mit.edu/"><acronym title="Massachusetts Institute of Technology">MIT</acronym></a>, <a href="http://www.ercim.org/"><acronym title="European Research Consortium for Informatics and Mathematics">ERCIM</acronym></a>, <a href="http://www.keio.ac.jp/">Keio</a>), All Rights Reserved. W3C <a href="http://www.w3.org/Consortium/Legal/ipr-notice#Legal_Disclaimer">liability</a>, <a href="http://www.w3.org/Consortium/Legal/ipr-notice#W3C_Trademarks">trademark</a> and <a href="http://www.w3.org/Consortium/Legal/copyright-documents">document use</a> rules apply.</p></div><hr /><div>
62
<h2><a name="abstract" id="abstract"></a>Abstract</h2><p>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).</p><p>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.</p></div><div>
63
<h2><a name="status" id="status"></a>Status of this Document</h2><p>
64
<em>This section describes the status of this document at the time of its
65
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 <a href="http://www.w3.org/TR/">W3C technical reports index</a> at http://www.w3.org/TR/. </em>
66
</p><p>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 <a href="index.html#sec-changes">Appendix B</a>. A "Disposition of Comments" report is available at <a href="http://www.w3.org/2006/02/lc-comments-tracker/37583/WD-DDR-Simple-API-20080404/doc/single">http://www.w3.org/2006/02/lc-comments-tracker/37583/WD-DDR-Simple-API-20080404/doc/single</a>. An <a href="http://www.w3.org/2005/MWI/DDWG/drafts/api/test-report.html">implementation report</a> is available at <a href="http://www.w3.org/2005/MWI/DDWG/drafts/api/test-report.html">http://www.w3.org/2005/MWI/DDWG/drafts/api/test-report.html</a>.</p>
67
<p>This document is published as part of the W3C <a href="http://www.w3.org/Mobile/">Mobile Web Initiative</a> (MWI) by the <a href="http://www.w3.org/2005/MWI/DDWG/">Device Description Working Group</a>. It is a deliverable as defined in the <a href="http://www.w3.org/2006/09/mwi-ddwg2-charter">Charter</a> of that group.
68
This specification is considered stable by the DDWG Working Group. Please send public comments to <a href="mailto:public-ddwg-comments@w3.org">public-ddwg-comments@w3.org</a>. This list is archived at <a href="http://lists.w3.org/Archives/Public/public-ddwg-comments/">http://lists.w3.org/Archives/Public/public-ddwg-comments/</a>.</p>
70
<p>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.</p>
73
<p>This document was produced by a group operating under the <a href="http://www.w3.org/Consortium/Patent-Policy-20040205/">5 February 2004 W3C Patent Policy</a>. W3C maintains a
74
<a href="http://www.w3.org/2004/01/pp-impl/37583/status">public list of any patent
75
disclosures</a> 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 <a href="http://www.w3.org/Consortium/Patent-Policy-20040205/#def-essential">Essential Claim(s)</a> must disclose the information in accordance with <a href="http://www.w3.org/Consortium/Patent-Policy-20040205/#sec-Disclosure">section 6 of the W3C Patent Policy</a>.</p></div><div class="toc">
76
<h2><a name="contents" id="contents"></a>Table of Contents</h2><p class="toc"><a href="index.html#sec-summary">Summary of Methods</a><br />
77
</p><p class="toc">1 <a href="index.html#sec-introduction">Introduction</a><br />
78
1.1 <a href="index.html#id30558">Background to the need for Device Description Repositories</a><br />
79
1.2 <a href="index.html#sec-Scope">Scope</a><br />
80
2 <a href="index.html#sec-reading-the-spec">Reading the Recommendation</a><br />
81
2.1 <a href="index.html#id30769">Normative and Informative Parts</a><br />
82
2.2 <a href="index.html#id30781">Normative Language for Conformance Requirements</a><br />
83
3 <a href="index.html#sec-vocabularies">Vocabularies</a><br />
84
4 <a href="index.html#sec-interfaces">Interfaces</a><br />
85
4.1 <a href="index.html#sec-interface-definitions">Interface Definitions</a><br />
86
4.2 <a href="index.html#sec-supporting-interfaces">Supporting Interfaces</a><br />
87
4.2.1 <a href="index.html#sec-Evidence">Evidence Interface</a><br />
88
4.2.1.1 <a href="index.html#id31193">Methods</a><br />
89
4.2.2 <a href="index.html#sec-PropertyName">PropertyName Interface</a><br />
90
4.2.2.1 <a href="index.html#id31271">Methods</a><br />
91
4.2.3 <a href="index.html#sec-PropertyRef">PropertyRef Interface</a><br />
92
4.2.3.1 <a href="index.html#id31338">Constants</a><br />
93
4.2.3.2 <a href="index.html#id31366">Methods</a><br />
94
4.2.4 <a href="index.html#sec-PropertyValue">PropertyValue Interface</a><br />
95
4.2.4.1 <a href="index.html#id31498">Methods</a><br />
96
4.2.5 <a href="index.html#sec-PropertyValues">PropertyValues</a><br />
97
4.2.5.1 <a href="index.html#id31590">Methods</a><br />
98
4.3 <a href="index.html#sec-Service">Service Interface</a><br />
99
4.3.1 <a href="index.html#sec-Service-factory-methods">Factory Methods</a><br />
100
4.3.1.1 <a href="index.html#sec-Service-newHTTPEvidence">Create HTTP Evidence</a><br />
101
4.3.1.2 <a href="index.html#sec-Service-newPropertyName">Create PropertyName</a><br />
102
4.3.1.3 <a href="index.html#sec-Service-newPropertyRef">Create PropertyRef</a><br />
103
4.3.2 <a href="index.html#sec-Service-query-methods">Query Methods</a><br />
104
4.3.2.1 <a href="index.html#sec-Service-return-known-values">Return Known Values</a><br />
105
4.3.2.2 <a href="index.html#sec-Service-return-specific-list">Return the Values of a Specific List</a><br />
106
4.3.2.3 <a href="index.html#sec-Service-return-specific-value">Return the Value of a Single Property</a><br />
107
4.3.3 <a href="index.html#sec-Service-information-methods">Information Methods</a><br />
108
4.3.3.1 <a href="index.html#sec-Service-version">Get Version Information</a><br />
109
4.3.3.2 <a href="index.html#sec-Service-available-properties">List Available Properties</a><br />
110
4.3.4 <a href="index.html#sec-Service-initialization">Initialization</a><br />
111
4.4 <a href="index.html#sec-exceptions">Exceptions</a><br />
112
4.4.1 <a href="index.html#sec-SystemException">SystemException Class</a><br />
113
4.4.1.1 <a href="index.html#sec-SystemException-methods">Methods</a><br />
114
4.4.1.2 <a href="index.html#sec-SystemException-codes">Codes</a><br />
115
4.4.2 <a href="index.html#sec-DDRException">DDRException Class</a><br />
116
4.4.2.1 <a href="index.html#sec-DDRException-methods">Methods</a><br />
117
4.4.2.2 <a href="index.html#sec-DDRException-codes">Codes</a><br />
118
4.4.3 <a href="index.html#sec-InitializationException">InitializationException</a><br />
119
4.4.3.1 <a href="index.html#sec-InitializationException-codes">Codes</a><br />
120
4.4.4 <a href="index.html#sec-NameException">NameException Class</a><br />
121
4.4.4.1 <a href="index.html#sec-NameException-codes">Codes</a><br />
122
4.4.5 <a href="index.html#sec-ValueException">ValueException Class</a><br />
123
4.4.5.1 <a href="index.html#sec-ValueException-codes">Codes</a><br />
124
4.5 <a href="index.html#sec-ServiceFactory">ServiceFactory Class</a><br />
125
4.5.1 <a href="index.html#sec-ServiceFactory-methods">Methods</a><br />
126
5 <a href="index.html#sec-conformance">Conformance</a><br />
128
<h3><a name="appendices" id="appendices"></a>Appendices</h3><p class="toc">A <a href="index.html#sec-java-representation">Java Representation</a><br />
129
B <a href="index.html#sec-changes">Changes Since Previous Version</a><br />
130
C <a href="index.html#sec-normative-references">Normative References</a><br />
131
D <a href="index.html#sec-other-representations">Other Representations of the DDR Simple API</a> (Non-Normative)<br />
132
E <a href="index.html#sec-informative-references">Informative References</a> (Non-Normative)<br />
133
F <a href="index.html#sec-acknowledgements">Acknowledgements</a> (Non-Normative)<br />
134
</p></div><hr /><div class="front"><div class="div1">
135
<h2><a name="sec-summary" id="sec-summary"></a>Summary of Methods</h2><table class="summary"><thead><tr><th>Interface / Class</th><th>Method</th></tr></thead><tbody><tr><td rowspan="3"><a href="index.html#sec-Evidence">Evidence</a></td><td>String <a href="index.html#sec-Evidence-get">get</a>(String key)</td></tr><tr><td>boolean <a href="index.html#sec-Evidence-exists">exists</a>(String key)</td></tr><tr><td>void <a href="index.html#sec-Evidence-put">put</a>(String key, String value)</td></tr><tr><td rowspan="2"><a href="index.html#sec-PropertyName">PropertyName</a></td><td>String <a href="index.html#sec-PropertyName-getLocalPropertyName">getLocalPropertyName</a>()</td></tr><tr><td>String <a href="index.html#sec-PropertyName-getNamespace">getNamespace</a>()</td></tr><tr><td rowspan="3"><a href="index.html#sec-PropertyRef">PropertyRef</a></td><td>String <a href="index.html#sec-PropertyRef-getLocalPropertyName">getLocalPropertyName</a>()</td></tr><tr><td>String <a href="index.html#sec-PropertyRef-getAspectName">getAspectName</a>()</td></tr><tr><td>String <a href="index.html#sec-PropertyRef-getNamespace">getNamespace</a>()</td></tr><tr><td rowspan="3"><a href="index.html#sec-PropertyValue">PropertyValue</a></td><td>double <a href="index.html#sec-PropertyValue-getXXX">getDouble</a>()
136
long <a href="index.html#sec-PropertyValue-getXXX">getLong</a>()
137
String <a href="index.html#sec-PropertyValue-getXXX">getString</a>()
138
boolean <a href="index.html#sec-PropertyValue-getXXX">getBoolean</a>()
139
int <a href="index.html#sec-PropertyValue-getXXX">getInteger</a>()
140
String[] <a href="index.html#sec-PropertyValue-getXXX">getEnumeration</a>()
141
float <a href="index.html#sec-PropertyValue-getXXX">getFloat</a>()</td></tr><tr><td>boolean <a href="index.html#sec-PropertyValue-exists">exists</a>()</td></tr><tr><td>PropertyRef <a href="index.html#sec-PropertyValue-getPropertyRef">getPropertyRef</a>()</td></tr><tr><td rowspan="2"><a href="index.html#sec-PropertyValues">PropertyValues</a></td><td>PropertyValue[] <a href="index.html#sec-PropertyValues-getAll">getAll</a>()</td></tr><tr><td>PropertyValue <a href="index.html#sec-PropertyValues-getValue">getValue</a>(PropertyRef prop)</td></tr><tr><td rowspan="19"><a href="index.html#sec-Service">Service</a></td><td>Evidence <a href="index.html#sec-Service-newHTTPEvidence-1">newHTTPEvidence</a>()</td></tr><tr><td>Evidence <a href="index.html#sec-Service-newHTTPEvidence-2">newHTTPEvidence</a>(java.util.Map<String,String> map)</td></tr><tr><td>PropertyName <a href="index.html#sec-Service-newPropertyName-1">newPropertyName</a>(String localPropertyName)</td></tr><tr><td>PropertyName <a href="index.html#sec-Service-newPropertyName-2">newPropertyName</a>(String localPropertyName, String vocabularyIRI)</td></tr><tr><td>PropertyRef <a href="index.html#sec-Service-newPropertyRef-1">newPropertyRef</a>(String localPropertyName)</td></tr><tr><td>PropertyRef <a href="index.html#sec-Service-newPropertyRef-2">newPropertyRef</a>(PropertyName propertyName)</td></tr><tr><td>PropertyRef <a href="index.html#sec-Service-newPropertyRef-3">newPropertyRef</a>(PropertyName propertyName, String localAspectName)</td></tr><tr><td>PropertyValues <a href="index.html#sec-Service-getPropertyValues-1">getPropertyValues</a>(Evidence evidence)</td></tr><tr><td>PropertyValues <a href="index.html#sec-Service-getPropertyValues-2">getPropertyValues</a>(Evidence evidence, String localAspectName)</td></tr><tr><td>PropertyValues <a href="index.html#sec-Service-getPropertyValues-3">getPropertyValues</a>(Evidence evidence,
142
String localAspectName, String vocabularyIRI)</td></tr><tr><td>PropertyValues <a href="index.html#sec-Service-getPropertyValues-4">getPropertyValues</a>(Evidence evidence, PropertyRef[] propertyRefs)</td></tr><tr><td>PropertyValue <a href="index.html#sec-Service-getPropertyValue-1">getPropertyValue</a>(Evidence evidence, PropertyRef propertyRef)</td></tr><tr><td>PropertyValue <a href="index.html#sec-Service-getPropertyValue-2">getPropertyValue</a>(Evidence evidence, PropertyName propertyName)</td></tr><tr><td>PropertyValue <a href="index.html#sec-Service-getPropertyValue-3">getPropertyValue</a>(Evidence evidence, String localPropertyName)</td></tr><tr><td>PropertyValue <a href="index.html#sec-Service-getPropertyValue-4">getPropertyValue</a>(Evidence evidence, String localPropertyName,
143
String localAspectName, String vocabularyIRI)</td></tr><tr><td>String <a href="index.html#sec-Service-getImplementationVersion">getImplementationVersion</a>()</td></tr><tr><td>String <a href="index.html#sec-Service-getDataVersion">getDataVersion</a>()</td></tr><tr><td>PropertyRef[] <a href="index.html#sec-Service-listPropertyRefs">listPropertyRefs</a>()</td></tr><tr><td>void <a href="index.html#sec-Service-initialize">initialize</a>(String defaultVocabularyIRI, java.util.Properties props)</td></tr><tr><td><a href="index.html#sec-ServiceFactory">ServiceFactory</a></td><td>Service <a href="index.html#sec-ServiceFactory">newService</a>(String clazz, String defaultVocabulary,
144
Properties configuration)</td></tr></tbody></table></div></div><hr /><div class="body"><div class="div1">
145
<h2><a name="sec-introduction" id="sec-introduction"></a>1 Introduction</h2><p>This section is informative.</p><div class="div2">
146
<h3><a name="id30558" id="id30558"></a>1.1 Background to the need for Device Description Repositories</h3><p>The need for Device Descriptions (information about the Properties [<a title="Property" href="index.html#property">definition</a>] of various Aspects [<a title="Aspect" href="index.html#aspect">definition</a>] of the Delivery Context <a href="http://www.w3.org/TR/di-gloss/#def-delivery-context-v2">[definition]</a>) 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.</p><p>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.</p><p>As discussed in <a href="index.html#Landscape">[Landscape]</a> and <a href="index.html#Ecosystem">[Ecosystem]</a>, 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.</p><p>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.</p><p>The <a href="http://www.w3.org/2005/MWI/DDWG/">Device Description Working Group</a> (DDWG), a Working Group of the W3C <a href="http://www.w3.org/Mobile/">Mobile Web Initiative</a>, was chartered to create a single API though which Property values can be retrieved, and a "Core" Vocabulary <a href="index.html#CORE-VOCAB">[Core Vocabulary]</a> that identifies a small number of such Properties.</p></div><div class="div2">
147
<h3><a name="sec-Scope" id="sec-Scope"></a>1.2 Scope</h3><p>Various use cases for DDRs are detailed in <a href="index.html#Requirements">[Requirements]</a>. 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. </p><p>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.</p><p>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.</p><p>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 <a href="index.html#CORE-VOCAB">[Core Vocabulary]</a> recognises the Aspects of "device" and "webBrowser". Other Aspects of the Delivery Context may be supported by other Vocabularies.</p><p>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.</p><p>The requirements of Vocabularies supported by the DDR Simple API are documented in <a href="index.html#sec-vocabularies"><span class="specref">3 Vocabularies</span></a>.</p>
149
<p>This Recommendation provides a normative definition of the DDR Simple API,
150
using Java <a href="index.html#ref-Java">[Java]</a> as a means of expression. Also
151
included are <a href="index.html#sec-other-representations">non-normative
152
representations</a> in OMG Interface Definition Language <a
153
href="index.html#ref-IDL">[IDL]</a> and the Web Services Definition Language <a
154
href="index.html#ref-WSDL">[WSDL]</a>.
156
</div></div><div class="div1">
157
<h2><a name="sec-reading-the-spec" id="sec-reading-the-spec"></a>2 Reading the Recommendation</h2><p>This section is normative.</p><div class="div2">
158
<h3><a name="id30769" id="id30769"></a>2.1 Normative and Informative Parts</h3><p>The normative and informative parts of this Recommendation are identified by use of labels within various sections.</p></div><div class="div2">
159
<h3><a name="id30781" id="id30781"></a>2.2 Normative Language for Conformance Requirements</h3><p>Individual conformance requirements or testable statements are identified in this document by the use of specific key words. In particular, the key words <strong>must</strong>, <strong>must not</strong>, <strong>required</strong>, <strong>shall</strong>, <strong>shall not</strong>, <strong>should</strong>, <strong>should not</strong>, <strong>recommended</strong>, <strong>may</strong>, and <strong>optional </strong>in this Recommendation are to be interpreted as described in <a href="index.html#ref-rfc-2119">[RFC 2119]</a> .</p></div></div><div class="div1">
160
<h2><a name="sec-vocabularies" id="sec-vocabularies"></a>3 Vocabularies</h2><p>This section is normative.</p><p>From the point of view of the DDR Simple API:</p><p>[<a name="aspect" id="aspect" title="Aspect">Definition</a>: An <b>Aspect</b> 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.</p><p>[<a name="property" id="property" title="Property">Definition</a>: A <b>Property</b> is a characteristic of an <a title="Aspect" href="index.html#aspect">Aspect</a> 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 (<code>boolean</code>, <code>int</code> 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 <code>exists()</code> method of the PropertyValue interface must return <code>false</code>.</p><p>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.</p><p>[<a name="vocabulary" id="vocabulary" title="Vocabulary">Definition</a>: A <b>Vocabulary</b> is a set of <a title="Property" href="index.html#property">Properties</a> and the <a title="Aspect" href="index.html#aspect">Aspects</a> with which the Properties are associated.] Vocabularies <strong>should</strong> 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). </p><div class="note"><p class="prefix"><b>Note:</b></p><p>This Recommendation does not specify a standard representation (such as an XML serialization) for Vocabularies.</p></div><p>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 <strong>must</strong> be unique in their namespace and <strong>must</strong> conform to the <a href="http://www.w3.org/TR/2006/REC-xml-names-20060816/#NT-NCName">syntax</a> defined in "Namespaces in XML" <a href="index.html#ref-Namespaces">[XML Namespaces]</a>. The value <code>__NULL ('_','_','N','U','L','L')</code> is reserved as the null Aspect, to be employed where a vocabulary does not use or distinguish Aspects of the properties it defines.</p><p>Vocabularies also define the data types of values associated with their Properties. The data types supported are <code>boolean</code>, <code>int</code>, <code>long</code>, <code>float</code>, <code>double</code>, <code>String</code> and for enumeration, <code>String[]</code>, the meanings of which are as defined in <a href="index.html#ref-Java">[Java]</a>. Where necessary, Vocabularies specify the units of measure of their properties.</p><p>The DDWG has published a suggested "Core" Vocabulary for essential Properties for Web content adaptation <a href="index.html#CORE-VOCAB">[Core Vocabulary]</a>. 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 <strong>must</strong> be in a different namespace to the Core Vocabulary. As mentioned in <a href="index.html#sec-Scope"><span class="specref">1.2 Scope</span></a>, the DDWG strongly recommends that its Core Vocabulary is supported by all implementations of the DDR Simple API.</p><p>The DDWG anticipates that further work on standardization of Properties and Aspects will take place alongside development of the Delivery Context Ontology (see <a href="index.html#ref-DCO">[Delivery Context Ontology]</a>).</p></div><div class="div1">
161
<h2><a name="sec-interfaces" id="sec-interfaces"></a>4 Interfaces</h2><p>This section is normative.</p><div class="div2">
162
<h3><a name="sec-interface-definitions" id="sec-interface-definitions"></a>4.1 Interface Definitions</h3><p>This Recommendation defines the DDR Simple API in Java <a href="index.html#ref-Java">[Java]</a>.</p><p>Methods are identified in the text in the following way:</p><div class="exampleInner Java"><pre class="Java">public Example exampleMethod();</pre></div><p>A Java representation of the interfaces and classes of the API is linked from Appendix <a href="index.html#sec-java-representation"><span class="specref">A Java Representation</span></a>, together with a link to Javadoc for the representation. Informative IDL and WSDL representations are also provided (see <a href="index.html#sec-other-representations"><span class="specref">D Other Representations of the DDR Simple API</span></a>).</p></div><div class="div2">
163
<h3><a name="sec-supporting-interfaces" id="sec-supporting-interfaces"></a>4.2 Supporting Interfaces</h3><p>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.</p><p>The principal interface of the DDR Simple API, <code>Service</code>, is defined in <a href="index.html#sec-Service"><span class="specref">4.3 Service Interface</span></a>, it is this interface that contains the factory methods for creating instances of the interfaces discussed here.</p><div class="div3">
164
<h4><a name="sec-Evidence" id="sec-Evidence"></a>4.2.1 Evidence Interface</h4><p>When querying Property values (see <a href="index.html#sec-Service-query-methods"><span class="specref">4.3.2 Query Methods</span></a>), 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 <strong>must</strong> support Evidence consisting of HTTP Header name and value pairs. Implementations <strong>must</strong> 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 <strong>may</strong> be supported by implementations. They are not defined in this Recommendation.</p><div class="div4">
165
<h5><a name="id31193" id="id31193"></a>4.2.1.1 Methods</h5><ol class="enumar"><li id="sec-Evidence-put"><p>Add Evidence (Header name, Header value)</p><div class="exampleInner Java"><pre class="Java">public void put(String key, String value);</pre></div></li><li id="sec-Evidence-exists"><p>Query Evidence (Header name)</p><div class="exampleInner Java"><pre class="Java">public boolean exists(String key);</pre></div></li><li id="sec-Evidence-get"><p>Retrieve Evidence (Header name)</p><div class="exampleInner Java"><pre class="Java">public String get(String key);</pre></div></li></ol></div></div><div class="div3">
166
<h4><a name="sec-PropertyName" id="sec-PropertyName"></a>4.2.2 <code>PropertyName</code> Interface</h4><p>The name of a Property together with its namespace. See <a href="index.html#sec-vocabularies"><span class="specref">3 Vocabularies</span></a> for a discussion of Properties and namespaces.</p><div class="div4">
167
<h5><a name="id31271" id="id31271"></a>4.2.2.1 Methods</h5><ol class="enumar"><li id="sec-PropertyName-getLocalPropertyName"><p>Get Property Name</p><div class="exampleInner Java"><pre class="Java">public String getLocalPropertyName();</pre></div></li><li id="sec-PropertyName-getNamespace"><p>Get Namespace</p><div class="exampleInner Java"><pre class="Java">public String getNamespace();</pre></div></li></ol></div></div><div class="div3">
168
<h4><a name="sec-PropertyRef" id="sec-PropertyRef"></a>4.2.3 <code>PropertyRef</code> Interface</h4><p>The name of a Property together with its Aspect together with the namespace they are in. See <a href="index.html#sec-vocabularies"><span class="specref">3 Vocabularies</span></a> for a discussion of Properties, Aspects and namespaces. Note that the value <code>__NULL</code> may be used where a Vocabulary does not support the concept of Aspect.</p><div class="div4">
169
<h5><a name="id31338" id="id31338"></a>4.2.3.1 Constants</h5><ol class="enumar"><li><p>Null Aspect</p><div class="exampleInner Java"><pre class="Java">public static final String NULL_ASPECT = "__NULL";</pre></div><p>This value is used to support Vocabularies that do not distinguish Aspects.</p></li></ol></div><div class="div4">
170
<h5><a name="id31366" id="id31366"></a>4.2.3.2 Methods</h5><ol class="enumar"><li id="sec-PropertyRef-getLocalPropertyName"><p>Get Property Name</p><div class="exampleInner Java"><pre class="Java">public String getLocalPropertyName();</pre></div></li><li id="sec-PropertyRef-getAspectName"><p>Get Aspect Name</p><div class="exampleInner Java"><pre class="Java">public String getAspectName();</pre></div></li><li id="sec-PropertyRef-getNamespace"><p>Get Namespace</p><div class="exampleInner Java"><pre class="Java">public String getNamespace();</pre></div></li></ol></div></div><div class="div3">
171
<h4><a name="sec-PropertyValue" id="sec-PropertyValue"></a>4.2.4 <code>PropertyValue</code> Interface</h4><p><code>PropertyValue</code> models a <code>PropertyRef</code> together with its value. Values may be empty, in which case the method <code>exists</code> returns <code>false</code>. An attempt to query an empty <code>value</code> causes a <code>ValueException</code> as does an attempt to query a <code>value</code> with an incompatible accessor method (<code>string</code> as <code>float</code>, for example). For the <code>getString</code> method implementations <strong>must</strong> return an implementation dependent <code>String</code> representation if the type of the <code>value</code> is not natively <code>String</code>. For other methods if the underlying type of the data does not match the method signature then a <code>ValueException</code> <strong>must</strong> be thrown.</p><div class="div4">
172
<h5><a name="id31498" id="id31498"></a>4.2.4.1 Methods</h5><ol class="enumar"><li id="sec-PropertyValue-getXXX"><p>Value Retrieval</p><div class="exampleInner Java"><pre class="Java">public double getDouble() throws ValueException;
173
public long getLong() throws ValueException;
174
public String getString() throws ValueException;
175
public boolean getBoolean() throws ValueException;
176
public int getInteger() throws ValueException;
177
public String[] getEnumeration() throws ValueException;
178
public float getFloat() throws ValueException;</pre></div></li><li id="sec-PropertyValue-exists"><p>Existence</p><div class="exampleInner Java"><pre class="Java">public boolean exists();</pre></div><p>True if a value is available, false otherwise.</p></li><li id="sec-PropertyValue-getPropertyRef"><p>Property Reference</p><div class="exampleInner Java"><pre class="Java">public PropertyRef getPropertyRef();</pre></div><p>The <code>PropertyRef</code> that this <code>PropertyValue</code> refers to.</p></li></ol></div></div><div class="div3">
179
<h4><a name="sec-PropertyValues" id="sec-PropertyValues"></a>4.2.5 PropertyValues</h4><p>A set of <code>PropertyValues</code>.</p><div class="div4">
180
<h5><a name="id31590" id="id31590"></a>4.2.5.1 Methods</h5><ol class="enumar"><li id="sec-PropertyValues-getAll"><p>Get All Properties in the Set</p><div class="exampleInner Java"><pre class="Java">public PropertyValue[] getAll();</pre></div></li><li id="sec-PropertyValues-getValue"><p>Get the Named Property</p><div class="exampleInner Java"><pre class="Java">public PropertyValue getValue(PropertyRef prop) throws NameException;</pre></div></li></ol></div></div></div><div class="div2">
181
<h3><a name="sec-Service" id="sec-Service"></a>4.3 <code>Service</code> Interface</h3><p>The <code>Service</code> interface is the core of the DDR Simple API. Using methods of <code>Service</code> the caller supplies <code>Evidence</code> representing the Delivery Context and an indication of the Properties of interest. These methods return <code>PropertyValue</code> objects which can then be queried to reveal the values of the Properties of interest.</p><p>The <code>Service</code> may be instantiated by a supplied factory class (see <a href="index.html#sec-ServiceFactory"><span class="specref">4.5 ServiceFactory Class</span></a>). The class invokes the <code>initialize</code> method to establish a Default Vocabulary and to pass implementation specific settings.</p><p>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.</p><p>All implementations are required to support <code>Evidence</code> consisting of name/value pairs of HTTP headers.</p><p>The methods of the <code>Service</code> interface fall into the following categories, which are discussed in the subsequent sections:</p><ul><li><p><a href="index.html#sec-Service-factory-methods"><span class="specref">4.3.1 Factory Methods</span></a></p></li><li><p><a href="index.html#sec-Service-query-methods"><span class="specref">4.3.2 Query Methods</span></a></p></li><li><p><a href="index.html#sec-Service-information-methods"><span class="specref">4.3.3 Information Methods</span></a></p></li><li><p><a href="index.html#sec-Service-initialization"><span class="specref">4.3.4 Initialization</span></a></p></li></ul><div class="div3">
182
<h4><a name="sec-Service-factory-methods" id="sec-Service-factory-methods"></a>4.3.1 Factory Methods</h4><p>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 <strong>may</strong> provide other means of instantiating the interfaces.</p><div class="div4">
183
<h5><a name="sec-Service-newHTTPEvidence" id="sec-Service-newHTTPEvidence"></a>4.3.1.1 Create HTTP Evidence</h5><ol class="enumar"><li id="sec-Service-newHTTPEvidence-1"><p>Create Empty HTTP Evidence</p><div class="exampleInner Java"><pre class="Java">public Evidence newHTTPEvidence();</pre></div></li><li id="sec-Service-newHTTPEvidence-2"><p>Create HTTP Evidence from Map</p><div class="exampleInner Java"><pre class="Java">public Evidence newHTTPEvidence(java.util.Map<String,String> map);</pre></div><p>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.</p></li></ol></div><div class="div4">
184
<h5><a name="sec-Service-newPropertyName" id="sec-Service-newPropertyName"></a>4.3.1.2 Create <code>PropertyName</code></h5><ol class="enumar"><li id="sec-Service-newPropertyName-1"><p>Create <code>PropertyName</code> using Default Vocabulary</p><div class="exampleInner Java"><pre class="Java">public PropertyName newPropertyName(String localPropertyName)
185
throws NameException;</pre></div></li><li id="sec-Service-newPropertyName-2"><p>Create <code>PropertyName</code> with specified Vocabulary</p><div class="exampleInner Java"><pre class="Java">public PropertyName newPropertyName(String localPropertyName, String vocabularyIRI)
186
throws NameException;</pre></div></li></ol></div><div class="div4">
187
<h5><a name="sec-Service-newPropertyRef" id="sec-Service-newPropertyRef"></a>4.3.1.3 Create <code>PropertyRef</code></h5><ol class="enumar"><li id="sec-Service-newPropertyRef-1"><p>Create <code>PropertyRef</code> using Default Vocabulary and Aspect</p><div class="exampleInner Java"><pre class="Java">public PropertyRef newPropertyRef(String localPropertyName)
188
throws NameException;</pre></div><p>The <code>PropertyRef</code> created is in the default Vocabulary and the Aspect is the default Aspect for the Property in that Vocabulary.</p></li><li id="sec-Service-newPropertyRef-2"><p>Create <code>PropertyRef</code> from <code>PropertyName</code> using Default Aspect</p><div class="exampleInner Java"><pre class="Java">public PropertyRef newPropertyRef(PropertyName propertyName)
189
throws NameException;</pre></div><p>The Aspect of the <code>PropertyRef</code> created is the default Aspect of the Property in the Vocabulary determined by the <code>propertyName</code> parameter.</p></li><li id="sec-Service-newPropertyRef-3"><p>Create <code>PropertyRef</code> from <code>PropertyName</code> in Named Aspect</p><div class="exampleInner Java"><pre class="Java">public PropertyRef newPropertyRef(PropertyName propertyName, String localAspectName)
190
throws NameException;</pre></div><p>The namespace associated with the Aspect <code>localAspectName</code> is associated with the namespace of the <code>propertyName</code> parameter.</p></li></ol></div></div><div class="div3">
191
<h4><a name="sec-Service-query-methods" id="sec-Service-query-methods"></a>4.3.2 Query Methods</h4><p>Query methods return values for Properties of the Delivery Context represented by the supplied <code>Evidence</code>.</p><p>The following types of query method exist:</p><ul><li><p><a href="index.html#sec-Service-return-known-values"><span class="specref">4.3.2.1 Return Known Values</span></a></p></li><li><p><a href="index.html#sec-Service-return-specific-list"><span class="specref">4.3.2.2 Return the Values of a Specific List</span></a></p></li><li><p><a href="index.html#sec-Service-return-specific-value"><span class="specref">4.3.2.3 Return the Value of a Single Property</span></a></p></li></ul><div class="div4">
192
<h5><a name="sec-Service-return-known-values" id="sec-Service-return-known-values"></a>4.3.2.1 Return Known Values</h5><ol class="enumar"><li id="sec-Service-getPropertyValues-1"><p>Return all available Property values for all the Aspects and Vocabularies known by an implementation of the DDR Simple API</p><div class="exampleInner Java"><pre class="Java">public PropertyValues getPropertyValues(Evidence evidence)
193
throws NameException;</pre></div></li><li id="sec-Service-getPropertyValues-2"><p>Return all known values for the given Aspect of the Default Vocabulary</p><div class="exampleInner Java"><pre class="Java">public PropertyValues getPropertyValues(Evidence evidence,
194
String localAspectName)
195
throws NameException;</pre></div></li><li id="sec-Service-getPropertyValues-3"><p>Return all known values for an Aspect of a specified Vocabulary</p><div class="exampleInner Java"><pre class="Java">public PropertyValues getPropertyValues(Evidence evidence,
196
String localAspectName, String vocabularyIRI)
197
throws NameException;</pre></div></li></ol></div><div class="div4">
198
<h5><a name="sec-Service-return-specific-list" id="sec-Service-return-specific-list"></a>4.3.2.2 Return the Values of a Specific List</h5><ol class="enumar"><li id="sec-Service-getPropertyValues-4"><p>Return values for all the supplied Properties, returning empty values for those that are not known. An "unknown value" is distinguished by the PropertyValue <code>exists()</code> method returning <code>false</code>.</p><div class="exampleInner Java"><pre class="Java">public PropertyValues getPropertyValues(Evidence evidence,
199
PropertyRef[] propertyRefs)
200
throws NameException;
201
</pre></div><p></p></li></ol></div><div class="div4">
202
<h5><a name="sec-Service-return-specific-value" id="sec-Service-return-specific-value"></a>4.3.2.3 Return the Value of a Single Property</h5><ol class="enumar"><li id="sec-Service-getPropertyValue-1"><p>Return the value of a specific Property</p><div class="exampleInner Java"><pre class="Java">public PropertyValue getPropertyValue(Evidence evidence,
203
PropertyRef propertyRef)
204
throws NameException;</pre></div></li><li id="sec-Service-getPropertyValue-2"><p>Return the value of a specific Property in its Default Aspect in the Vocabulary specified by <code>propertyName</code></p><div class="exampleInner Java"><pre class="Java">public PropertyValue getPropertyValue(Evidence evidence,
205
PropertyName propertyName)
206
throws NameException;</pre></div></li><li id="sec-Service-getPropertyValue-3"><p>Return the value of a specific Property in its Default Aspect in the Default Vocabulary</p><div class="exampleInner Java"><pre class="Java">public PropertyValue getPropertyValue(Evidence evidence,
207
String localPropertyName)
208
throws NameException;</pre></div></li><li id="sec-Service-getPropertyValue-4"><p>Return the value of a specific Property with a specific Aspect in a specific Vocabulary.</p><div class="exampleInner Java"><pre class="Java">public PropertyValue getPropertyValue(Evidence evidence,
209
String localPropertyName, String localAspectName, String vocabularyIRI)
210
throws NameException;</pre></div></li></ol></div></div><div class="div3">
211
<h4><a name="sec-Service-information-methods" id="sec-Service-information-methods"></a>4.3.3 Information Methods</h4><div class="div4">
212
<h5><a name="sec-Service-version" id="sec-Service-version"></a>4.3.3.1 Get Version Information</h5><ol class="enumar"><li id="sec-Service-getImplementationVersion"><p>Get Implementation Version</p><div class="exampleInner Java"><pre class="Java">public String getImplementationVersion();</pre></div><p>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.</p></li><li id="sec-Service-getDataVersion"><p>Get Data Version</p><div class="exampleInner Java"><pre class="Java">public String getDataVersion();</pre></div><p>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 <strong>must</strong> 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 <code>__NOT_SUPPORTED ('_','_','N','O','T','_','S','U','P','P','O','R','T','E','D')</code> is returned.</p></li></ol></div><div class="div4">
213
<h5><a name="sec-Service-available-properties" id="sec-Service-available-properties"></a>4.3.3.2 List Available Properties</h5><ol class="enumar"><li id="sec-Service-listPropertyRefs"><p>List Properties</p><div class="exampleInner Java"><pre class="Java">public PropertyRef[] listPropertyRefs();</pre></div><p>Lists the combination of all known Properties and Aspects in all Vocabularies that can be used without causing a <code>NameException</code> to be thrown. The order in which Properties are listed is not significant.</p></li></ol></div></div><div class="div3">
214
<h4><a name="sec-Service-initialization" id="sec-Service-initialization"></a>4.3.4 Initialization</h4><ol class="enumar"><li id="sec-Service-initialize"><p>Initialize the Library</p><div class="exampleInner Java"><pre class="Java">public void initialize(String defaultVocabularyIRI,
215
java.util.Properties props)
216
throws NameException, InitializationException;</pre></div><p>Called by the instantiation class (see <a href="index.html#sec-ServiceFactory"><span class="specref">4.5 ServiceFactory Class</span></a>) to initialize the implementation. Implementation specific initialization parameters may be passed using the <code>props</code> parameter.</p><div class="note"><p class="prefix"><b>Note:</b></p><p>Note that the <code>props</code> parameter is of the class <code>java.util.Properties</code> and is not related to <a title="Property" href="index.html#property">Properties</a> of <a title="Vocabulary" href="index.html#vocabulary">Vocabularies</a> discussed in this document.</p></div></li></ol></div></div><div class="div2">
217
<h3><a name="sec-exceptions" id="sec-exceptions"></a>4.4 Exceptions</h3><p>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 <strong>may</strong> create new exceptions and exception codes when needed.</p><p>The following sections describe each exception, its methods, associated codes and the conditions under they <strong>must</strong> be thrown. Implementations <strong>should</strong> add additional information in the form of messages to assist with diagnosis of the condition that caused the exception to be thrown.</p><div class="div3">
218
<h4><a name="sec-SystemException" id="sec-SystemException"></a>4.4.1 SystemException Class</h4><p>This exception, a subclass of <code>java.lang.Runtime</code>, is thrown by DDR Simple API implementations when they encounter unrecoverable errors.</p><div class="note"><p class="prefix"><b>Note:</b></p><p>Being a run time exception, SystemException does not require specification as part of a method's <code>throws</code> clause.</p><p>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 (<a href="index.html#sec-other-representations"><span class="specref">D Other Representations of the DDR Simple API</span></a>).</p></div><div class="div4">
219
<h5><a name="sec-SystemException-methods" id="sec-SystemException-methods"></a>4.4.1.1 Methods</h5><ol class="enumar"><li id="sec-SystemException-getMessage"><p>Get Message</p><div class="exampleInner Java"><pre class="Java">public String getMessage();</pre></div></li><li id="sec-SystemException-getCode"><p>Get Code</p><div class="exampleInner Java"><pre class="Java">public int getCode();</pre></div></li></ol></div><div class="div4">
220
<h5><a name="sec-SystemException-codes" id="sec-SystemException-codes"></a>4.4.1.2 Codes</h5><ol class="enumar"><li id="def-CANNOT_PROCEED"><p><code>CANNOT_PROCEED</code></p><div class="exampleInner "><pre>public static int CANNOT_PROCEED = 500;</pre></div><p>The implementation cannot continue with the processing of the current request due to an unexpected failure - disconnection from a database, for example.</p></li><li id="def-ILLEGAL_ARGUMENT"><p><code>ILLEGAL_ARGUMENT</code></p><div class="exampleInner "><pre>public static int ILLEGAL_ARGUMENT = 400;</pre></div><p>A method has been passed an illegal or inappropriate argument - a <code>null</code> argument where it is not allowed, for example.</p></li></ol></div></div><div class="div3">
221
<h4><a name="sec-DDRException" id="sec-DDRException"></a>4.4.2 DDRException Class</h4><p>It is the superclass of all DDR Simple API exceptions other than SystemException.</p><p>Implementations should raise subclasses of <code>DDRException</code>, they <strong>should not</strong> raise this exception directly.</p><div class="div4">
222
<h5><a name="sec-DDRException-methods" id="sec-DDRException-methods"></a>4.4.2.1 Methods</h5><ol class="enumar"><li id="sec-DDRException-getMessage"><p>Get Message</p><div class="exampleInner Java"><pre class="Java">public String getMessage();</pre></div></li><li id="sec-DDRException-getCode"><p>Get Code</p><div class="exampleInner Java"><pre class="Java">public int getCode();</pre></div></li></ol></div><div class="div4">
223
<h5><a name="sec-DDRException-codes" id="sec-DDRException-codes"></a>4.4.2.2 Codes</h5><ol class="enumar"><li id="def-IMPLEMENTATION_ERROR"><p><code>IMPLEMENTATION_ERROR</code></p><div class="exampleInner "><pre>public static int IMPLEMENTATION_ERROR = 65536;</pre></div><p>This code may be used by implementations to create custom error codes. All implementation specific codes <strong>must</strong> be greater than this value.</p></li></ol><p>Implementations <strong>may</strong> define specific codes for different kinds of failures during initialization.</p></div></div><div class="div3">
224
<h4><a name="sec-InitializationException" id="sec-InitializationException"></a>4.4.3 InitializationException</h4><p>This is a subclass of <code><a href="index.html#sec-DDRException">DDRException</a></code> and represents an error during the initialization phase of the Simple API. It is thrown only by the <code><a href="index.html#sec-Service-initialize">initialize</a></code> method of the <code>Service</code> interface and the <code><a href="index.html#sec-ServiceFactory">newService</a></code> method of the <code>ServiceFactory</code> class.</p><div class="div4">
225
<h5><a name="sec-InitializationException-codes" id="sec-InitializationException-codes"></a>4.4.3.1 Codes</h5><ol class="enumar"><li id="def-INITIALIZATION_ERROR"><p><code>INITIALIZATION_ERROR</code></p><div class="exampleInner "><pre>public static int INITIALIZATION_ERROR = 300;</pre></div><p>There was a problem during initialization.</p></li></ol><p>Implementations <strong>may</strong> define specific codes for different kinds of failures during initialization.</p></div></div><div class="div3">
226
<h4><a name="sec-NameException" id="sec-NameException"></a>4.4.4 NameException Class</h4><p>This is a subclass of <code><a href="index.html#sec-DDRException">DDRException</a></code> 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.</p><p>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.</p><div class="div4">
227
<h5><a name="sec-NameException-codes" id="sec-NameException-codes"></a>4.4.4.1 Codes</h5><ol class="enumar"><li id="def-PROPERTY_NOT_RECOGNIZED"><p><code>PROPERTY_NOT_RECOGNIZED</code></p><div class="exampleInner "><pre>public static int PROPERTY_NOT_RECOGNIZED = 100;</pre></div><p>The name of a Property is in error</p></li><li id="def-ASPECT_NOT_RECOGNIZED"><p><code>ASPECT_NOT_RECOGNIZED</code></p><div class="exampleInner "><pre>public static int ASPECT_NOT_RECOGNIZED = 800;</pre></div><p>The name of an Aspect is in error</p></li><li id="def-VOCABULARY_NOT_RECOGNIZED"><p><code>VOCABULARY_NOT_RECOGNIZED</code></p><div class="exampleInner "><pre>public static int VOCABULARY_NOT_RECOGNIZED = 200;</pre></div><p>A vocabulary IRI is in error</p></li></ol></div></div><div class="div3">
228
<h4><a name="sec-ValueException" id="sec-ValueException"></a>4.4.5 ValueException Class</h4><p>This is a subclass of <code><a href="index.html#sec-DDRException">DDRException</a></code> and is thrown when an error is detected during an attempt to retrieve the value of a Property using one of the <a href="index.html#sec-PropertyValue-getXXX">value accessor methods</a> of the <code>PropertyValue</code> class. The exception code indicates the nature of the error.</p><div class="div4">
229
<h5><a name="sec-ValueException-codes" id="sec-ValueException-codes"></a>4.4.5.1 Codes</h5><ol class="enumar"><li id="def-NOT_KNOWN"><p><code>NOT_KNOWN</code></p><div class="exampleInner "><pre>public static int NOT_KNOWN = 900;</pre></div><p>The property value is unknown.</p></li><li id="def-INCOMPATIBLE_TYPES"><p><code>INCOMPATIBLE_TYPES</code></p><div class="exampleInner "><pre>public static int INCOMPATIBLE_TYPES = 600;</pre></div><p>The value represented by the <code>PropertyValue</code> is incompatible with the return type of the method used to retrieve it.</p></li><li id="def-MULTIPLE_VALUES"><p><code>MULTIPLE_VALUES</code></p><div class="exampleInner "><pre>public static int MULTIPLE_VALUES = 10000;</pre></div><p>The implementation is aware of multiple values for this Property.</p></li></ol></div></div></div><div class="div2">
230
<h3><a name="sec-ServiceFactory" id="sec-ServiceFactory"></a>4.5 <code>ServiceFactory</code> Class</h3><p>The Java representation of the DDR Simple API defines a factory for instantiating <code>Service</code> with the supplied default namespace and configuration.</p><div class="div3">
231
<h4><a name="sec-ServiceFactory-methods" id="sec-ServiceFactory-methods"></a>4.5.1 Methods</h4><div class="exampleInner Java"><pre class="Java">public static Service newService(String clazz, String defaultVocabulary,
232
Properties configuration) throws InitializationException,
233
NameException</pre></div><p>Instantiates an instance of the class <code>clazz</code> establishing the Default Vocabulary to be the one specified and with implementation specific values passed as <code>java.lang.Properties</code>.</p><p> In the following example, <code>ServiceFactory</code> 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 <code>configuration</code> parameter.</p><p>Example:</p><div class="exampleOuter"><div class="exampleInner "><pre>Service myService = ServiceFactory.newService("mobi.example.DDRService",
234
"http://www.w3.org/2008/01/DDR-Core-Vocabulary", null);</pre></div></div></div></div></div><div class="div1">
235
<h2><a name="sec-conformance" id="sec-conformance"></a>5 Conformance</h2><p>This section is normative.</p><p>A conforming implementation of this Recommendation <strong>must</strong> implement all the normative sections of this document.</p></div></div><div class="back"><div class="div1">
236
<h2><a name="sec-java-representation" id="sec-java-representation"></a>A Java Representation</h2><p>The DDR Simple API is available as a <a href="http://www.w3.org/TR/2008/REC-DDR-Simple-API-20081205/DDRSimpleAPI.jar">JAR file</a>, and as <a href="http://www.w3.org/TR/2008/REC-DDR-Simple-API-20081205/javadoc/">Javadoc</a>.
237
</p></div><div class="div1">
238
<h2><a name="sec-changes" id="sec-changes"></a>B Changes Since Previous Version</h2>
239
<p>The following changes have been made since the Proposed Recommendation version of this document:</p>
241
<li>Corrected typo, pluralized "Device Description" in <a href="index.html#sec-introduction">section 1.1</a></li>
242
<li>Clarified usage of Java in <a href="index.html#sec-Scope">section 1.2</a></li>
243
<li>Corrected link to IDL version of the specification in <a href="index.html#sec-other-representations">Appendix D</a></li>
245
<p>The following changes were made between the Last Call Working Draft and the Proposed Recommendation:</p><ul><li>consistently coded keywords</li><li>inserted word "HTTP" into headers for sections dealing with HTTP based evidence</li><li>clarified usage of IRI's to identify vocabularies</li><li>clarified usage of Map type in Evidence </li><li>renamed getAPIVersion to getImplementationVersion</li><li>clarified handling of unsupported versioning features</li></ul></div><div class="div1">
246
<h2><a name="sec-normative-references" id="sec-normative-references"></a>C Normative References</h2><dl><dt class="label"><a name="ref-rfc-2119" id="ref-rfc-2119"></a>RFC 2119</dt><dd>Key words for use in RFCs to Indicate Requirement Levels, S. Bradner, March 1997 (See <a href="http://www.ietf.org/rfc/rfc2119.txt">http://www.ietf.org/rfc/rfc2119.txt</a>)</dd><dt class="label"><a name="ref-Java" id="ref-Java"></a>Java</dt><dd>The Java Language Specification, Third Edition (See <a href="http://java.sun.com/docs/books/jls/third_edition/html/j3TOC.html">http://java.sun.com/docs/books/jls/third_edition/html/j3TOC.html</a>)</dd><dt class="label"><a name="ref-Namespaces" id="ref-Namespaces"></a>XML Namespaces</dt><dd>Namespaces in XML 1.0 (Second Edition), W3C Recommendation, Tim Bray, Dave Hollander, Andrew Layman, Richard Tobin (eds.), 16 August 2006 (See <a href="http://www.w3.org/TR/2006/REC-xml-names-20060816/">http://www.w3.org/TR/2006/REC-xml-names-20060816/</a>)</dd></dl></div><div class="div1">
247
<h2><a name="sec-other-representations" id="sec-other-representations"></a>D Other Representations of the DDR Simple API (Non-Normative)</h2><p>A non-normative OMG IDL <a href="index.html#ref-IDL">[IDL]</a> <a href="ddr-simpleapi.idl">representation</a> for the DDR Simple API may be used to create other language representations.</p><p>There is a non-normative WSDL <a href="index.html#ref-WSDL">[WSDL]</a> <a href="ddr-simpleapi.wsdl">representation</a> for the DDR Simple API.</p><p>For other non-normative representations see <a href="index.html#DDWG">[DDWG]</a> </p></div><div class="div1">
248
<h2><a name="sec-informative-references" id="sec-informative-references"></a>E Informative References (Non-Normative)</h2><dl><dt class="label"><a name="DDWG" id="DDWG"></a>DDWG</dt><dd>DDWG Home Page (See <a href="http://www.w3.org/2005/MWI/DDWG/">http://www.w3.org/2005/MWI/DDWG/</a>)</dd><dt class="label"><a name="DIGLOSS" id="DIGLOSS"></a>DIGLOSS</dt><dd>Glossary of Terms for Device Independence, W3C Working Draft, Rhys Lewis (ed.), 18 January 2005 (See <a href="http://www.w3.org/TR/2005/WD-di-gloss-20050118/">http://www.w3.org/TR/2005/WD-di-gloss-20050118/</a>)</dd><dt class="label"><a name="CORE-VOCAB" id="CORE-VOCAB"></a>Core Vocabulary</dt><dd>Device Description Repository Core Vocabulary,
249
W3C Working Draft, Andrea Trasatti, Jo Rabin, Rotan Hanrahan (eds.), 14 April 2008 (See <a href="http://www.w3.org/TR/2008/NOTE-ddr-core-vocabulary-20080414/">http://www.w3.org/TR/2008/NOTE-ddr-core-vocabulary-20080414/</a>)</dd><dt class="label"><a name="Requirements" id="Requirements"></a>Requirements</dt><dd>Device Description Repository Requirements 1.0, W3C Working Group Note, Kevin Smith (ed.), 17 December 2007 (See <a href="http://www.w3.org/TR/DDR-requirements/">http://www.w3.org/TR/DDR-requirements/</a>)</dd><dt class="label"><a name="Landscape" id="Landscape"></a>Landscape</dt><dd>Device Description Landscape 1.0, W3C Working Group Note, Eman Nkeze, James Pearce, Matt Womer (eds.), 31 October 2007, (See <a href="http://www.w3.org/TR/2007/NOTE-dd-landscape-20071031/">http://www.w3.org/TR/2007/NOTE-dd-landscape-20071031/</a>)</dd><dt class="label"><a name="Ecosystem" id="Ecosystem"></a>Ecosystem</dt><dd>Device Description Ecosystem 1.0, W3C Working Group Note, Rotan Hanrahan (ed.), 31 October 2007 (See <a href="http://www.w3.org/TR/2007/NOTE-dd-ecosystem-20071031/">http://www.w3.org/TR/2007/NOTE-dd-ecosystem-20071031/</a>)</dd><dt class="label"><a name="ref-DCO" id="ref-DCO"></a>Delivery Context Ontology</dt><dd>Delivery Context Ontology, W3C Working Draft, Rhys Lewis (ed.), 21 December 2007 (See <a href="http://www.w3.org/TR/dcontology/">http://www.w3.org/TR/dcontology/</a>)</dd><dt class="label"><a name="ref-WSDL" id="ref-WSDL"></a>WSDL</dt><dd>Web Services Description Language (WSDL) 1.1, W3C Note, Erik Christensen, Francisco Curbera, Greg Meredith, Sanjiva Weerawarana, 15 March 2001 (See <a href="http://www.w3.org/TR/wsdl">http://www.w3.org/TR/wsdl</a>)</dd><dt class="label"><a name="ref-IDL" id="ref-IDL"></a>IDL</dt><dd>OMG IDL
250
Syntax and Semantics, Object Management Group. (See <a href="http://www.omg.org/technology/documents/formal/corba_2.htm">http://www.omg.org/technology/documents/formal/corba_2.htm</a>)</dd></dl></div><div class="div1">
252
<h2><a name="sec-acknowledgements" id="sec-acknowledgements"></a>F
253
Acknowledgements (Non-Normative)</h2><p>The editors wish to acknowledge the
254
contributions of members of the DDWG.</p><p>The editors wish to acknowledge
255
the specific written contributions of:</p><ul><li>Andrea Trasatti, dotMobi
256
(mTLD Top Level Domain)</li><li>Rhys Lewis, then at Volantis Systems
257
Ltd.</li><li>Rodrigo Garcia, Fundación
258
CTIC</li></ul></div></div></body></html>
added
removed
www.w3.org/TR/2008/REC-DDR-Simple-API-20081205/index.html
