Abstract
This specification defines a model to allow a widget user agent to
locate and replace a widget resource with a new or different version of a
widget resource. The updates model is designed to work both over HTTP and
from local storage. For updates performed via the Web, the model makes use
a simple XML documents that authors place on a Web server to indicate,
amongst other things, where the next most suitable version of a widget
resource can be retrieved from. It also defines a mechanism that allows
authors to be notified of installation errors or success. This
specification also describes how to renegotiate security policies when
widgets are updated.
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 is the First Public Working Draft of this document. 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.
This document is produced by the Web Applications WG, part of
the Rich Web Clients
Activity in the W3C Interaction Domain. It is
expected that this document will progress along the W3C's Recommendation
track. Publication as a Working Draft does not imply endorsement by the
W3C Membership. This is a draft document and may be updated, replaced or
obsoleted by other documents at any time. It is inappropriate to cite this
document as other than work in progress.
This document is probably out of date!
You can find the latest Editor's Draft of this
document in the W3C's CVS repository,
which is updated on a very regular basis. The public is
encouraged to send comments to the WebApps Working Group's public mailing
list public-webapps@w3.org (archive).
See W3C mailing list and archive usage
guidelines. A detailed list of changes from
the previous version is also available from the W3C's CVS server.
Implementers should be aware that this document is
unstable. Implementers who are not taking part in the discussions
are likely to find the specification changing out from under them in
incompatible ways. Vendors interested in implementing this
document before it eventually reaches the Candidate Recommendation stage
should join the aforementioned mailing lists and take part in the
discussions.
User agents that wish to extend this specification in any
way are encouraged to discuss their extensions on a public forum, such as
public-webapps so their
extensions can be considered for standardization.
Table of Contents
Everything in this specification is normative except for diagrams,
examples, notes and sections marked as informative.
The key words must, must not, should and
may in this document are to be interpreted as described in [RFC2119].
This specification describes the conformance criteria for user agents
(relevant to implementers) and various resource types (relevant to authors
and authoring tool implementers).
There are two classes of products that can claim conformance to this
specification:
Products that generate and/or allow authoring of update description
documents must not claim conformance to this
specification, though they can claim to produce update description
documents that themselves are conforming to this specification. Authoring
tools and markup generators must generate conforming
update description documents.
Products that check the conformance of update configuration documents
must not claim conformance to this specification,
though they can claim to verify that an update description document
conforms to this specification.
2. Introduction
TBW: Goals of this specification. A brief overview of the
architecture, and some background and motivation for its creating. Related
specifications (namely OMA-DL) and justification as to why this is needed.
An installed widget is a widget resource that
has been correctly installed on a widget user agent, but may or may not be
updatable.
An updatable widget is an installed widget
that meets all the preconditions defined in this specification that would
allow it to be updated.
An update source is the URi referenced by the
src attribute of the an
update element.
A potential update is a resource acquired by
downloading the resource addressed by the src attribute of the widgetupdate element.
The update process is a multi-step process where
by a widget user agent compares the version of a currently installed
widget resource to the version of a resource available either on the Web
or on local storage.
The version of an installed widget is determined
by the version attribute of the
widget element declared by an author in a widget
configuration document. Otherwise, if no version attribute has been declared for an
installed widget, the version may have been computed by the widget user
agent using the rules defined by the Widget Packaging
specification.
If a widget user agent determines, via the rules defined in this
specification, that two widget resources are not the same version, and if
the user consents, the widget user agent must attempt replace the
currently installed widget resource with the potential update. If a widget
user agent determines, via the rules define in this specification, that
installed widget does not need updating, then that installed widget is
said to be up-to-date.
This document defines three strategies that authors can rely on for
having a widget user agent check if a widget resource is up-to-date, as
well as the rules that define how widget user agents are expected to
behave when performing each update strategy. The
strategies are as follows:
- Referencing an update description document on
the Web.
- Updating via the
widget.update() method defined in the
Widgets-API specification (works in conjunction to update
strategy 1).
- Updating from local storage.
Update strategies 1 and 2 are performed by acquiring and processing an
update description document (UDD) from some IRI. An
UDD is an XML document in which an author declares, amongst other things,
what's new or different in the potential update, the version that the
widget will be updated to, and the IRI from where the widget user agent
can retrieve the potential update (the update source). It is expected that
widget user agents will perform updates asynchronously by periodically
checking for changes in either the HTTP response codes for the UDD (e.g. a
changed HTTP Etag header or using
If-Modified-Since) and by processing the UDD itself. The
timing of periodic checks is an implementation detail left to the
discretion of the implementer (e.g. once a day or once a week).
In the case of update strategy 2, an author can request that a widget
asynchronously check if a widget has been updated via the widget.update() method, defined in the
Widgets-API specification. This strategy also relies on the
author having declared a update element in the widget configuration
document, as it makes us of the URI to potentially retrieve an UDD and
relay whether an update is available back to the instantiated Widget.
Actually performing the update is left to the discretion of the widget
user agent.
In the case of update strategy 3, updating from local storage, this
specification works in conjunction with the Widget Packaging
specification to define the rules for how to verify and install a
potential update.
Extended examples of the three update strategies are provided in the
usage scenarios section of this specification.
In the use of any of the update strategies, a number of security
conditions need to be checked that are described in this document.
3. Value types
The space characters, valid URI, valid version-tag
are defined in the Widget Packaging specification.
4. Update Description Document
(UDD)
An update description document (UDD) is an
XML document that has a widgetupdate element at its root that is
in the widget namespace.
The purpose of the UDD is to describe details about a potential update.
4.1 Example Update Description
Document
This section is informative.
Below is an example of a typical UDD. In order for a widget user agent
to retrieve and process a UDD, an author must initially declare a valid
URI for the update element in the installed widget's
configuration document (e.g. <update
src="https://example.com/myWidget/updates"/>).
<widgetupdate xmlns="http://www.w3.org/ns/widgets"
src="https://example.com/myWidget/v1.1b/awesome.wgt"
version="1.0"
id="http://example.com/myWidget"
bytes="1024"
notify="https://example.com/myWidget/updateManager.php">
<details href="http://a.com/myWidget/1.1/whatsnew">
We fixed some bugs and improved performance!
</details>
</widgetupdate>
For the widgetupdate element:
- The required
src attribute represents
the URI (usually a URL) of the potential update.
- The required
version attribute
represents the version of the potential update.
- The optional
id attribute represents
the identifier for this widget. The value of the id attribute is intended to match the value of the
installed widget identifier, which an author will have declared in the
widget's configuration document (via the widget element's
id attribute).
- The optional
bytes attribute
represents the size of the potential update in bytes.
- The optional
notify attribute represent a URI where a
HTTP POST request will be made upon completion of the update process.
The optional details element
represents details of changes in the potential update. Its
href attribute represents a hyperlink to a (HTML) resource
where further details can be read.
4.2 MIME Type
Update description documents MUST be served with the
application/xml MIME type.
The widgetupdate is intended to
provide metadata about the potential update. In addition, it serves as a
container for the other elements; as such, it must be
used.
- Expected context:
- The root element of an UDD document.
- Expected children:
details: zero or one.
Attributes
- version
- Required. A valid version tag that denotes the version
number of the potential update.
- src
- Required. A valid URI that references a
potential update. Over the wire, the potential update must be labeled with a correct widget MIME type
(
i.e. application/widget).
- id
- Optional. The id of the potential update. When used, it must match the
id of the installed update. NOTE: need to specify how
to migrate to new widget IDs across updates.
- bytes
- Optional. The bytes attribute specifies a
valid non-negative integer that represents the number of
bytes of the resource identified by the
src attribute.
- ISSUE: should widget user agents verify this with
a HEAD request to the potential update?
- notify
- Optional. A URI Attribute that is contacted after installation has
completed.
4.4 The details element
The details element represents a
human-readable description of differentiates this potential update from
other versions.
- Expected context
widgetupdate- Expected children
- any
4.4.1 Attributes
- href
- A valid URI that points to additional information about the potential
update.
5. UDD Acquisition
TBW: This section will describe how to formulate HTTP
requests and deal with authentication and content negotiation. Widget user
agents will be expected to handle HTTP response codes and redirects. User
agents will also be expected to cache certain information, etc. This
section will also discuss confirmation of installation via POST to the
notify URI.
6. UDD Processing
TBW: This section will describe how to process a UDD.
6.1 Default values
Widget user agents must assume the following
defaults prior to processing a UDD:
Update Defaults
| Variable |
Type |
default value |
description |
| update-source |
URI |
null |
|
| version-tag |
DOMString |
null |
|
| update-id |
DOMString |
null |
|
| update-size |
DOMString |
null |
|
| notifyURI |
URI |
null |
|
| details |
DOMNode |
null |
|
Need to define the term invalid
UDD...
6.2 Processing model
The term in error, typically used of an element
or attribute, means that the element, attribute, or other construct is not
conformant according to the rules of this specification. Rules for exactly
how the construct must be treated when it is in error are always given
when the term is used. Typically this will involve ignoring the erroneous nodes, meaning the UA must,
for the purposes of processing, act as if those nodes were
absent. For cases where attributes on elements do not conform to this
specification, the attributes must be considered to be in error and the UA
must ignore them, meaning that the presence of these non-conforming
attributes in no way affects the processing.
- Let doc be the result of parsing
Document using a
[XMLNS]-aware parser. If the document is not well-formed
[XML], then threat this as an invalid UDD.
- Let root element be the
documentElement of
doc.
- If the root element is not a
widgetupdate element in the widget
namespace, then treat this UDD as an invalid.
- If the root element is a
widgetupdate element:
- If the
version attribute was
used, and it is a valid version-tag,
then let version-tag be the value of version.
- If no
version attribute was
used, or the value was in error, treat this as an invalid UDD.
- If the
src attribute was used, and
it is a valid URI, then let
update-source be the value of src.
- If no src attribute was used, or the value was in error, treat this
as an invalid UDD.
- If the
id attribute was used and it
is a valid URI, then let update-id
be the value of id.
- If the
bytes attribute was used
and it is a valid non-negative integer, then let
update-size be the value bytes.
- If the
notify attribute was used and it is a valid URI, then let notify-uri be the
value of notify.
- For any child element of the root element:
- If the child element is a details element:
- If this is not the first
details
element, then the element is in error and must be ignored.
- TBW: Need to extract the text content ignoring any
invalid nodes not defined in this document. However, need to align this
with the i18n model so that <bdo> is allowed (or whatever
solution we end up using).
- If the child element is a
Comment node, or a
ProcessingInstruction node, or a Text node that
only contains space characters, or a
CDATASection node that only contains space
characters, or anything else, this is in
error and must be ignored.
7. Potential update
verification and installation process
TBW..
7.1 Handling Security Policies
This section will describe how to adjust security
policies when an update widget requests additional functionality.
8. Post install
TBW...
8.1 Notify Response Codes
This section will extend the OMA-DL response codes with
anything that is specific to widgets.
9. Security concerns
It is conceivable that the automatic update model could be subject to a
man-in-the-middle-attack, as with any unencrypted requests performed over
HTTP. For this reason, it is recommended
that automatic update are always performed over HTTPS.
10. Usage Scenarios
This section is informative
The following sections describe each of the three automatic update
strategies in detail. The sections are divided up in terms of author
guidelines that describe how authors are expected to use the
specification.
Editor's note: this section and the subsections are
incomplete. The following text is just a guide as to what we plan to put
in here.
10.1 Using an Update Description
Document
This section is informative.
Using an update description document is recommended for any of the
following use cases:
- Widgets that were dynamically generated on the server for a
particular client.
- Widgets where the author would like to inform the end-user of the
details of what has been updated prior to an update.
- Situations where the author wishes to be notified whether or not the
updated succeeded.
In the configuration document, the author provides an
<update> element that points to some URI:
<widgets xmlns="..."
id="http://a.com/myWidget"
version="1.0">
<update
uri="http://a.com/myWidget/{version}/update.xml"/>
</widgets>
The widget engine sends a request:
GET /myWidget/1.0/update.xml
Host: a.com
User-Agent: SuperWidgetEngine
Accept: text/xml
If-modified-since: 23 March, 2008
Accept-Language: en-us,en;q=0.5
Accept-Encoding: gzip,deflate
Accept-Charset: ISO-8859-1,utf-8;q=0.7,*;q=0.7
Server responds with an update description document:
HTTP/1.1 200 OK
Date: Tue, 27 May 2008 06:02:05 GMT
Content-Type: text/xml
Content-Length: 370
<?xml version="1.0" encoding="utf-8"?>
<update xmlns="http://www.w3.org/ns/widgets"
src="https://a.com/myWidget/v1.1b/awesome.wgt"
notify="https://a.com/myWidget/updateManager.php"
version="1.1 beta (awesome edition)"
bytes="1024">
<details href="http://a.com/myWidget/1.1/whatsnew">
We fixed some bugs and added some new APIs!
</details>
</update>
So, the widget engine then checks that <update id>
matches <widget id> and that <widget
version> and <update version> are
different. If so, then the user is informed that a new
update is available. If the user agrees to download the new widget, then
the widget user agent attempts to retrieve the resource indicated by the
<update src> attribute. If the widget engine is able to
retrieve and verify the potential update, then the widget resource is
processed as normal, checking that the <widget id="id"> for the widget
stays the same. If all goes the plan, the old widget is either backed up
or erased and the new widget takes its place. Any previously set
preferences are kept.
10.2 Updating from Local
Storage
This section is informative.
This method of updating is suitable for widgets that were downloaded
from a web browser to disk or were acquired via some alternative means,
such as BlueTooth.
Upon instantiating the widget, the widget user agent compares the id and
version of the new widget to the currently existing widget and replacing.
This section is informative.
Authors can use scripts to allow a widget to be updated by calling the
widget.update() method [Widgets
API].
checkForUpdate(){
//custom code to check for update online using XHR
}
setInterval("checkForUpdate();", 86400000); //check for update once a day
Acknowledgements