diff options
Diffstat (limited to 'docs/xen-api/presentation.tex')
-rw-r--r-- | docs/xen-api/presentation.tex | 149 |
1 files changed, 149 insertions, 0 deletions
diff --git a/docs/xen-api/presentation.tex b/docs/xen-api/presentation.tex new file mode 100644 index 0000000000..0072704646 --- /dev/null +++ b/docs/xen-api/presentation.tex @@ -0,0 +1,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. |