Update Notification Protocol

From Apache OpenOffice Wiki
Revision as of 17:02, 28 January 2012 by Pescetti (Talk | contribs)

Jump to: navigation, search

Status: Draft

Introduction

Since version 2.0.3 OpenOffice.org users of builds providing an UpdateURL can manually check for available updates by invoking "Help -> Check for Updates .." . Starting with version 2.0.4 OpenOffice.org can perform this check automatically in a user configurable interval.

This is an attempt to define a second version of the update notification protocol, which is better extendable, can also be used for extensions and no longer uses http post requests.

Template:Documentation/Note ,

Request

The update notification request is a http get request to an URL, which may contain the operating system and processor type the OpenOffice.org instance is compiled for either as part of the URL or as URL parameter.

Examples

UpdateURL=http://update.services.openoffice.org/ProductUpdateService/check.Update2?_OS=Solaris&_ARCH=SPARC
UpdateURL=http://www.example.org/MyProduct/MyOS/MyArch

User-Agent field

To reduce the amount of transfered data when asking for OpenOffice.org updates, the user agent field contains all information required to identify a specific build:

User-Agent: OpenOffice.org/2.2 (680m212 (Build:9263); Solaris; SPARC; BundledLanguages=en-US_fr)

Accept-Language field

To be able to return language specific feeds, OpenOffice.org sets the Accept-Language http request header field to the UI language currently in use:

Accept-Language: en-GB

Update documents and feeds

The simplest possible reply is of the following form:

<?xml version="1.0" encoding="utf-8"?>
<inst:description xmlns:inst="http://installation.openoffice.org/description">
  <inst:id>OpenOffice.org_2_en-US_fr</inst:id>
  <inst:version>2.2.0-5</inst:version>
  <inst:buildid>9095</inst:buildid>
  <inst:os>Solaris</inst:os>
  <inst:arch>SPARC</inst:arch>
  <inst:update type="text/html" src="http://update.services.openoffice.org/ooo/snapshot.html" />
</inst:description>

As the type attribute of the update tag is "text/html", OOo will pass the URL specified in the src attribute to a browser. If you specify a different type, e.g.

  <inst:update type="application/octet-stream" src="http://openoffice.bouncer.osuosl.org/?product=OpenOffice.org&os=solarissparcwjre&lang=en-US&version=2.4" />

OOo will download the referenced file itself.


The other supported reply format, which also allows to include several components or several versions of a single component, is to embed the update document in an atom feed.

<?xml version="1.0" encoding="utf-8"?>
<feed xmlns="http://www.w3.org/2005/Atom" xml:lang”en-US”>

  <title>OpenOffice.org Update Feed</title>
  <link rel="alternate" type="text/html" href="http://update.services.openoffice.org/ooo/snapshot.html"/>
  <updated>2006-11-06T18:30:02Z</updated>
  <author>
    <name>The OpenOffice.org Project</name>
    <uri>http://openoffice.org</uri>
    <email>updatefeed@openoffice.org</email>
  </author>
  <id>urn:uuid:a4ccd383-1dd1-11b2-a95c-0003ba566e9d</id>
  <entry>
    <title>OpenOffice.org 2.2 available</title>
    <link rel="alternate" type="text/html"
        href="http://update.services.openoffice.org/ooo/snapshot.html"/>
    <id>urn:uuid:a4ccd383-1dd1-11b2-a95c-0003ba566e9e</id>
    <updated>2006-11-06T18:30:02Z</updated>
    <summary>Click here to go to the download page.</summary>
    <category term="OpenOffice.org_2_en-US_fr" label="OpenOffice.org 2.2 US english/french" />
    <content type="application/xml">
      <inst:description xmlns:inst="http://installation.openoffice.org/description">
        <inst:id>OpenOffice.org_2_en-US_fr</inst:id>
        <inst:version>2.2.0-5</inst:version>
        <inst:buildid>9095</inst:buildid>
        <inst:os>Solaris</inst:os>
        <inst:arch>SPARC</inst:arch>
        <inst:update type="text/html" src="http://update.services.openoffice.org/ooo/snapshot.html" />
      </inst:description>
    </content>
  </entry>
</feed>

description.xml OpenOffice.org 3.x update information example

The following content of a description.xml directly references update information for a German Windows OpenOffice.org 3.3.0:

<?xml version="1.0" encoding="utf-8"?>
<feed xmlns="http://www.w3.org/2005/Atom" xml:lang="en-US">
<title>Product Update Feed</title>
<link rel="alternate" type="text/html" href="http://update.services.openoffice.org/ooo/snapshot.html"/>
<updated>2011-01-01T08:00:02Z</updated>
<author>
        <name>The OpenOffice Project</name>
        <uri>http://openoffice.org</uri>
        <email>updatefeed@openoffice.org</email>
</author>
<id>urn:uuid:76676544</id>
<entry>
        <title>Update available</title>
        <link rel="alternate" type="text/html" href="http://update.services.openoffice.org/ooo/snapshot.html"/>
        <id>urn:uuid:76676544</id>
        <!-- IMPORTANT: category MUST be equal with UpdateID in version.ini -->
        <category term="OpenOffice.org_3_de" label="OpenOffice.org update"/>
        <updated>2011-01-01T08:00:02Z</updated>
        <summary>Text below download information (should be localized)</summary>
        <content type="application/xml">
                <inst:description xmlns:inst="http://installation.openoffice.org/description">
                        <inst:id>OpenOffice.org_3_de</inst:id>
                        <inst:version>'new version information'</inst:version>
                        <!-- buildid must be higher as installed version -->
                        <inst:buildid>9580</inst:buildid>
                        <inst:os>Windows</inst:os>
                        <inst:arch>x86</inst:arch>
                        <!-- app/octet-stream generates direct download as background-process -->
                        <!--<inst:update type="application/octet-stream" src="http://download.services.openoffice.org/files/localized/de/3.3.0/OOo_3.3.0_Win_x86_install-wJRE_de.exe"/>-->
                        <!-- text/html opens src-link in default browser -->
                        <inst:update type="text/html" src="http://download.openoffice.org"/>
                </inst:description>
        </content>
</entry>
</feed>

Note: to allow proper filtering, the term tag of the <category> node of the <atom:entry> element must contain the <inst:id> string of the component to be updated.


Extension developers might prefer to link to the update description file instead of embedding it:

<?xml version="1.0" encoding="utf-8"?>
<feed xmlns="http://www.w3.org/2005/Atom" xml:lang”en-US”>

  <title>My Extention Update Feed</title>
  <link rel="alternate" type="text/html" href="http://update.services.openoffice.org/ooo/snapshot.html"/>
  <updated>2006-11-06T18:30:02Z</updated>
  <author>
    <name>Extension Developer</name>
    <uri>http://example.org</uri>
    <email>update@example.org</email>
  </author>
  <id>urn:uuid:a4ccd383-1dd1-11b2-a95c-0003ba566e9d</id>
  <entry>
    <title>Version 2 available</title>
    <link rel="alternate" type="text/html"
        href="http://example.org/myextension/latest.html"/>
    <id>MyExtension+version</id>
    <updated>2006-11-06T18:30:02Z</updated>
    <category term="MyExtension" label="My Extension" />
    <content type="application/xml" src="http://example.org/myextension/latest/myextension.update.xml" />
  </entry>
</feed>

Note: to allow proper filtering, the term tag of the <category> node of the <atom:entry> element must contain the <identifier> value of the extension to be updated.

Personal tools