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
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
|
%
% Copyright (c) 2006 XenSource, Inc.
%
% Permission is granted to copy, distribute and/or modify this document under
% the terms of the GNU Free Documentation License, Version 1.2 or any later
% version published by the Free Software Foundation; with no Invariant
% Sections, no Front-Cover Texts and no Back-Cover Texts. A copy of the
% license is included in the section entitled
% "GNU Free Documentation License" or the file fdl.tex.
%
% Authors: Ewan Mellor, Richard Sharp, Dave Scott, Jon Harrop.
%
The API is presented here as a set of Remote Procedure Calls, with a wire
format based upon XML-RPC. No specific language bindings are prescribed,
although examples will be given in the python programming language.
Although we adopt some terminology from object-oriented programming,
future client language bindings may or may not be object oriented.
The API reference uses the terminology {\em classes\/} and {\em objects\/}.
For our purposes a {\em class\/} is simply a hierarchical namespace;
an {\em object\/} is an instance of a class with its fields set to
specific values. Objects are persistent and exist on the server-side.
Clients may obtain opaque references to these server-side objects and then
access their fields via get/set RPCs.
%In each class there is a $\mathit{uid}$ field that assigns an indentifier
%to each object. This $\mathit{uid}$ serves as an object reference
%on both client- and server-side, and is often included as an argument in
%RPC messages.
For each class we specify a list of
fields along with their {\em types\/} and {\em qualifiers\/}. A
qualifier is one of:
\begin{itemize}
\item $\mathit{RO}_\mathit{run}$: the field is Read
Only. Furthermore, its value is automatically computed at runtime.
For example: current CPU load and disk IO throughput.
\item $\mathit{RO}_\mathit{ins}$: the field must be manually set
when a new object is created, but is then Read Only for
the duration of the object's life.
For example, the maximum memory addressable by a guest is set
before the guest boots.
\item $\mathit{RW}$: the field is Read/Write. For example, the name
of a VM.
\end{itemize}
A full list of types is given in Chapter~\ref{api-reference}. However,
there are three types that require explicit mention:
\begin{itemize}
\item $t~\mathit{Ref}$: signifies a reference to an object
of type $t$.
\item $t~\mathit{Set}$: signifies a set containing
values of type $t$.
\item $(t_1, t_2)~\mathit{Map}$: signifies a mapping from values of
type $t_1$ to values of type $t_2$.
\end{itemize}
Note that there are a number of cases where {\em Ref}s are {\em doubly
linked\/}---e.g.\ a VM has a field called {\tt groups} of type
$(\mathit{VMGroup}~\mathit{Ref})~\mathit{Set}$; this field lists
the VMGroups that a particular VM is part of. Similarly, the VMGroups
class has a field called {\tt VMs} of type $(\mathit{VM}~{\mathit
Ref})~\mathit{Set}$ that contains the VMs that are part of a particular
VMGroup. These two fields are {\em bound together\/}, in the sense that
adding a new VMGroup to a VM causes the VMs field of the corresponding
VMGroup object to be updated automatically.
The API reference explicitly lists the fields that are
bound together in this way. It also contains a diagram that shows
relationships between classes. In this diagram an edge signifies the
existance of a pair of fields that are bound together, using standard
crows-foot notation to signify the type of relationship (e.g.\
one-many, many-many).
\section{RPCs associated with fields}
Each field, {\tt f}, has an RPC accessor associated with it
that returns {\tt f}'s value:
\begin{itemize}
\item ``{\tt get\_f(Ref x)}'': takes a
{\tt Ref} that refers to an object and returns the value of {\tt f}.
\end{itemize}
Each field, {\tt f}, with attribute
{\em RW} and whose outermost type is {\em Set\/} has the following
additional RPCs associated with it:
\begin{itemize}
\item an ``{\tt add\_to\_f(Ref x, v)}'' RPC adds a new element v to the set\footnote{
%
Since sets cannot contain duplicate values this operation has no action in the case
that {\tt v} was already in the set.
%
};
\item a ``{\tt remove\_from\_f(Ref x, v)}'' RPC removes element {\tt v} from the set;
\end{itemize}
Each field, {\tt f}, with attribute
{\em RW} and whose outermost type is {\em Map\/} has the following
additional RPCs associated with it:
\begin{itemize}
\item an ``{\tt add\_to\_f(Ref x, k, v)}'' RPC adds new pair {\tt (k, v)}
to the mapping stored in {\tt f} in object {\tt x}. Adding a new pair for duplicate
key, {\tt k}, overwrites any previous mapping for {\tt k}.
\item a ``{\tt remove\_from\_f(Ref x, k)}'' RPC removes the pair with key {\tt k}
from the mapping stored in {\tt f} in object {\tt x}.
\end{itemize}
Each field whose outermost type is neither {\em Set\/} nor {\em Map\/},
but whose attribute is {\em RW} has an RPC acessor associated with it
that sets its value:
\begin{itemize}
\item For {\em RW\/} ({\em R\/}ead/{\em
W\/}rite), a ``{\tt set\_f(Ref x, v)}'' RPC function is also provided.
This sets field {\tt f} on object {\tt x} to value {\tt v}.
\end{itemize}
\section{RPCs associated with classes}
\begin{itemize}
\item Each class has a {\em constructor\/} RPC named ``{\tt create}'' that
takes as parameters all fields marked {\em RW\/} and
$\mathit{RO}_\mathit{ins}$. The result of this RPC is that a new {\em
persistent\/} object is created on the server-side with the specified field
values.
\item Each class has a {\tt get\_by\_uuid(uuid)} RPC that returns the object
of that class that has the specified {\tt uuid}.
\item Each class that has a {\tt name\_label} field has a
``{\tt get\_by\_name\_label(name)}'' RPC that returns a set of objects of that
class that have the specified {\tt label}.
\item Each class has a ``{\tt to\_XML()}'' RPC that serialises the
state of all fields as an XML string.
\item Each class has a ``{\tt destroy(Ref x)}'' RPC that explicitly deletes
the persistent object specified by {\tt x} from the system. This is a
non-cascading delete -- if the object being removed is referenced by another
object then the {\tt destroy} call will fail.
\end{itemize}
\subsection{Additional RPCs}
As well as the RPCs enumerated above, some classes have additional RPCs
associated with them. For example, the {\tt VM} class have RPCs for cloning,
suspending, starting etc. Such additional RPCs are described explicitly
in the API reference.
|
