Copyright © 2008 W3C® (MIT, ERCIM, Keio), All Rights Reserved. W3C liability, trademark and document use rules apply.
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.
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.
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.
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:
widget.update()
method defined in the
Widgets-API specification (works in conjunction to update
strategy 1). 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.
The space characters, valid URI, valid version-tag are defined in the Widget Packaging specification.
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.
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:
src
attribute represents
the URI (usually a URL) of the potential update.version
attribute
represents the version of the potential update.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).bytes
attribute
represents the size of the potential update in bytes.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.
Update description documents MUST be served with the
application/xml
MIME type.
widgetupdate
elementThe 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.
details
: zero or one.i.e. application/widget
).src
attribute.details
elementThe details
element represents a
human-readable description of differentiates this potential update from
other versions.
widgetupdate
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.
TBW: This section will describe how to process a UDD.
Widget user agents must assume the following defaults prior to processing a UDD:
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...
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.
the acquired
UDD as a [DOM3Core] Document
using a
[XMLNS]-aware parser. If the document is not well-formed
[XML], then threat this as an invalid UDD.documentElement
of
doc.widgetupdate
element in the widget
namespace, then treat this UDD as an invalid.widge
tupdate
element:
version
attribute was
used, and it is a valid version-tag,
then let version-tag be the value of version
.version
attribute was
used, or the value was in error, treat this as an invalid UDD.src
attribute was used, and
it is a valid URI, then let
update-source be the value of src
.id
attribute was used and it
is a valid URI, then let update-id
be the value of id
.bytes
attribute was used
and it is a valid non-negative integer, then let
update-size be the value bytes
. notify
attribute was used and it is a valid URI, then let notify-uri be the
value of notify
.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.TBW..
This section will describe how to adjust security policies when an update widget requests additional functionality.
TBW...
This section will extend the OMA-DL response codes with anything that is specific to widgets.
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.
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.
This section is informative.
Using an update description document is recommended for any of the following use cases:
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.
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.
widget.update()
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