1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
|
<?xml version="1.0"?>
<!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook XML V4.3//EN" "http://www.oasis-open.org/docbook/xml/4.3/docbookx.dtd">
<refentry id="gdata-overview">
<refmeta>
<refentrytitle role="top_of_page" id="gdata-overview.top_of_page">GData Overview</refentrytitle>
<manvolnum>3</manvolnum>
<refmiscinfo>GDATA Library</refmiscinfo>
</refmeta>
<refnamediv>
<refname>GData Overview</refname>
<refpurpose>overview of libgdata's architecture</refpurpose>
</refnamediv>
<refsect1>
<title>Introduction</title>
<para>libgdata is a library to allow access to web services using the GData protocol from the desktop. The <ulink type="http"
url="http://code.google.com/apis/gdata/overview.html">GData protocol</ulink> is a simple protocol for reading and writing
data on the web, designed by Google.</para>
<refsect2>
<title>Protocol</title>
<para>The GData protocol is designed by Google to allow interaction with their web services. It is based on the Atom Publishing
protocol, with namespaced XML additions. Communication between the client and server is broadly achieved through HTTP
requests with query parameters, and Atom feeds being returned with result entries. Each <firstterm>service</firstterm>
has its own namespaced additions to the GData protocol; for example, the Google Calendar service's API has
specialisations for addresses and time periods.
<figure>
<mediaobject>
<imageobject><imagedata fileref="data-flow.png" format="PNG" align="center"/></imageobject>
</mediaobject>
<textobject><phrase>An overview of the data flow when making a request of a GData service.</phrase></textobject>
</figure>
</para>
<para>Results are always returned in the form of result <firstterm>feeds</firstterm>, containing multiple
<firstterm>entries</firstterm>. How the entries are interpreted depends on what was queried of the service, but when
using libgdata, this is all taken care of transparently.</para>
</refsect2>
<refsect2>
<title>Structure</title>
<para>The basic design of libgdata mirrors the protocol's structure quite closely:
<figure>
<mediaobject>
<imageobject><imagedata fileref="structure.png" format="PNG" align="center"/></imageobject>
</mediaobject>
<textobject><phrase>An overview of the libgdata class structure.</phrase></textobject>
</figure>
</para>
<variablelist>
<varlistentry>
<term><type><link linkend="GDataService">GDataService</link></type></term>
<listitem><para>Subclassed for each different web service implemented, this class represents a single client's
connection to the relevant web service, holding their authentication state, and making the necessary
requests to read and write data to and from the service. All top-level actions, such as creating a new
object on the server, are carried out through a service.</para>
<para>There should be one <type><link linkend="GDataService">GDataService</link></type> subclass for each
of the services listed <ulink type="http" url="http://code.google.com/apis/gdata/">in the GData
documentation</ulink>.</para></listitem>
</varlistentry>
<varlistentry>
<term><type><link linkend="GDataQuery">GDataQuery</link></type></term>
<listitem><para>For queries to have multiple individual parameters, a
<type><link linkend="GDataQuery">GDataQuery</link></type> can be used to specify the parameters.</para>
<para>Query objects are optional, and can only be used with queries (not with entry insertions, updates
or deletions). The query object builds the query URI used by the
<type><link linkend="GDataService">GDataService</link></type> when sending the query to the server.</para>
<para>Services can subclass <type><link linkend="GDataQuery">GDataQuery</link></type> if the service
supports non-standard query parameters.</para>
</listitem>
</varlistentry>
<varlistentry>
<term><type><link linkend="GDataFeed">GDataFeed</link></type></term>
<listitem><para>Effectively a list of <type><link linkend="GDataEntry">GDataEntry</link></type>s, the
<type><link linkend="GDataFeed">GDataFeed</link></type> class is a direct counterpart of the root
<type><feed></type> element in the Atom feeds which form the GData protocol. It contains the
elements in a query response, as well as general information about the response, such as links to
related feeds and the categories under which the query response falls.</para>
<para><type><link linkend="GDataFeed">GDataFeed</link></type> is usually not subclassed by services,
as there are rarely service-specific elements in a feed itself.</para></listitem>
</varlistentry>
<varlistentry>
<term><type><link linkend="GDataEntry">GDataEntry</link></type></term>
<listitem><para>A <type><link linkend="GDataEntry">GDataEntry</link></type> is a direct counterpart of the
<type><entry></type> element in the Atom feeds which form the GData protocol. It represents a
single object of unspecified semantics; an entry could be anything from a calendar event to a video
comment or access control rule. Semantics are given to entries by subclassing
<type><link linkend="GDataEntry">GDataEntry</link></type> for the various types of entries returned
by queries to a service. Such subclasses implement useful, relevant and query-specific properties
on the entry (such as the duration of a video, or the recurrence rules of a calendar event).</para>
</listitem>
</varlistentry>
</variablelist>
</refsect2>
</refsect1>
</refentry>
|
