Difference between revisions of "Update Notification Protocol"

From Apache OpenOffice Wiki
Redirect page
Jump to: navigation, search
(Update documents and feeds)
(Redirected page to Update Service)
 
(3 intermediate revisions by the same user not shown)
Line 1: Line 1:
Status: Draft
+
#REDIRECT [[Update Service]]
 
+
= 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 | extensions]] and no longer uses http post requests.
+
 
+
{{Documentation/Note|Note: Even though this document is a draft, it seems to be the actually implemented version as of OpenOffice.org 3.3. See http://s.apache.org/e2u for more information.}}
+
 
+
= 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 ==
+
 
+
<pre>
+
UpdateURL=http://update.services.openoffice.org/ProductUpdateService/check.Update2?_OS=Solaris&_ARCH=SPARC
+
</pre>
+
 
+
<pre>
+
UpdateURL=http://www.example.org/MyProduct/MyOS/MyArch
+
</pre>
+
 
+
= 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:
+
 
+
<pre>
+
User-Agent: OpenOffice.org/2.2 (680m212 (Build:9263); Solaris; SPARC; BundledLanguages=en-US_fr)
+
</pre>
+
 
+
= 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:
+
 
+
<pre>
+
Accept-Language: en-GB
+
</pre>
+
 
+
= Update documents and feeds =
+
 
+
The simplest possible reply is of the following form:
+
 
+
<source lang="xml">
+
<?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>
+
</source>
+
 
+
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.
+
 
+
<source lang="xml">
+
  <inst:update type="application/octet-stream" src="http://openoffice.bouncer.osuosl.org/?product=OpenOffice.org&os=solarissparcwjre&lang=en-US&version=2.4" />
+
</source>
+
 
+
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 [http://tools.ietf.org/wg/atompub/draft-ietf-atompub-format/rfc4287.txt atom feed].
+
 
+
<source lang="xml">
+
<?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>
+
</source>
+
 
+
''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:
+
<source lang="xml">
+
<?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>
+
</source>
+
 
+
'''Note''': to allow proper filtering, the <tt>term</tt> 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:
+
 
+
<source lang="xml">
+
<?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>
+
</source>
+
 
+
'''Note''': to allow proper filtering, the <tt>term</tt> tag of the <category> node of the <atom:entry> element must contain the <identifier> value of the extension to be updated.
+
 
+
= A glance on the code for the Apache OpenOffice 3.4 release =
+
 
+
The following describes some deeper insight of the "Check for Updates..." code in the office. It should help us to re-activate a corresponding web service when Apache OpenOffice 3.4 has been released. (Do we need a real web service? Something to be discussed.)
+
 
+
The information given here is based on the work of Regina (regina at apache dot org), Ariel (arielch at apache dot org) and Kay (kschenk at apache dot org) found in the corresponding mailing list thread on ooo-dev - see http://s.apache.org/e2u.
+
Having this information gave me (orw at apache dot org) the right pointers for deeper investigations.
+
 
+
== summary information about request to <UpdateURL> ==
+
 
+
The <UpdateURL>, found in file <version.ini> of the office installation is typically an HTTP URL.
+
The office sends a GET request to this URL. Two header fields are included in this request which are already mentioned above.
+
These are "Accept-Language" and "User-Agent".
+
* "Accept-Language" contains the language of current locale - found in configuration item "org.openoffice.Setup/L10N", attribute "ooLocale"
+
* "User-Agent" contains needed information to identify the installed office version - see above. The information matches the following pattern which is found in file <version.ini>:
+
<blockquote>
+
<pre>
+
<PRODUCT> (${buildid}; ${_OS}; ${_ARCH}; BundledLanguages=${AllLanguages})
+
</pre>
+
</blockquote>
+
It reveals that this information can be used to create the corresponding information for the request response.
+
 
+
== information about processing the request response ==
+
 
+
The response is expected to be a corresponding XML snippet.
+
As shown in the above examples, two types of XML snippets as responses are possible:
+
a ''feed'' response and a ''simple'' response. The distinction between the two is made by its first element. If it is <feed> it is treated as a ''feed'' response, otherwise as a ''simple'' response.
+
 
+
==== ''simple'' response ====
+
 
+
The ''simple'' response is an XML snippet which is expected to have the format as the XML snippet in file [http://svn.apache.org/repos/asf/incubator/ooo/trunk/main/instsetoo_native/util/update.xml update.xml], found in our source repository.
+
 
+
The following conditions must hold to perform further evaluation of the response:
+
# value of <inst:os> matches the one of the installed office - ''${_ARCH}''.
+
# value of <inst:arch> matches the one of the installed office - ''${_OS}''.
+
# value of <inst:buildid> is greater than the one of the installed office - ''${buildid}''.
+
If these conditions hold, the following information is retrieved:
+
# values of attributes <src> and <type> of <inst:update>
+
#* if value of <type> equals "text/html", the value of <src> is taken as an website from which the new version can be downloaded manually. Otherwise (also in case that attribute <type> is missing) the value of <src> is interpreted as a download link to the new version.
+
#* all <inst:update> elements are evaluated. The information of the first one is used - provide download of version or provide link to download website. The purpose of the other is not known.
+
# value of <inst:version> - will be shown in the corresponding dialog.
+
# value of <inst:buildid> - currently its purpose is not known.
+
If the first information - download website or download link - can be found in the XML snippet, the corresponding dialog will state that a new version is available. The user can then download it manually or can trigger an automatic download.
+
 
+
If no download website/link is found, the dialog will state that the installed office is up to date.
+
 
+
==== ''feed'' response ====
+
 
+
The ''feed'' response is expected to conform to [http://tools.ietf.org/wg/atompub/draft-ietf-atompub-format/rfc4287.txt atom feed] - as stated above in the example area.
+
Each content of the <content> element of an atom entry (<entry> element) whose <category> element has an attribute <term> whose value matches the <UpdateId> value found in file <version.ini> of the installed office is treated as ''simple'' response.
+
 
+
The first of these ''simple'' responses from which a download website or a download link could be retrieved that matches the above given conditions is taken - the following ones are not processed. It will be shown to the user that a new version is available, and the user can trigger the download manually or automatically. One further information is taken from this atom entry - the content of the <summary> element. It is shown in the corresponding dialog.
+
 
+
If no download website/link is found, the dialog will state that the installed office is up to date.
+
 
+
[[Category:Spec]]
+
[[Category:Draft]]
+

Latest revision as of 09:42, 10 July 2014

Personal tools