1 |
\input texinfo |
\input texinfo |
2 |
@setfilename api.info |
@setfilename api.info |
3 |
@settitle The GEAS API |
@settitle The GNUe Appserver API |
4 |
@include version.texi |
@include version.texi |
5 |
@setcontentsaftertitlepage |
@setcontentsaftertitlepage |
6 |
|
@syncodeindex tp fn |
7 |
@c ---------------------------------------------------------------------------- |
@c ---------------------------------------------------------------------------- |
8 |
@ifnottex |
@ifnottex |
9 |
@chapheading The GNU Enterprise Application Server |
@chapheading The GNU Enterprise Application Server |
44 |
@end titlepage |
@end titlepage |
45 |
|
|
46 |
@c ---------------------------------------------------------------------------- |
@c ---------------------------------------------------------------------------- |
47 |
@node Top, Introduction |
@node Top, Data Types |
48 |
@c ---------------------------------------------------------------------------- |
@c ---------------------------------------------------------------------------- |
49 |
|
|
50 |
@menu |
@menu |
51 |
* Introduction:: |
* Data Types:: |
52 |
* Session:: |
* API Functions:: |
|
* List:: |
|
|
* Instance:: |
|
|
* AuthAgent:: |
|
53 |
* FDL:: GNU Free Documentation License |
* FDL:: GNU Free Documentation License |
54 |
* Index:: |
* Index:: |
55 |
@end menu |
@end menu |
56 |
|
|
57 |
@c ---------------------------------------------------------------------------- |
@c ---------------------------------------------------------------------------- |
58 |
@node Introduction, Session, Top, Top |
@node Data Types, API Functions, Top, Top |
59 |
@c ---------------------------------------------------------------------------- |
@c ---------------------------------------------------------------------------- |
60 |
|
|
61 |
@chapter Introduction |
@chapter Data Types |
62 |
|
|
63 |
@section Terminology |
In the API definition, we will make use of the following data type |
64 |
|
placeholders, which will have to be translated into appropriate data |
65 |
To understand the principles of the Application Server, one has to clearly |
types for the various implemented RPC mechanisms: |
66 |
distinguish between @dfn{business objects} (like customers, orders, or |
|
67 |
accounts) and @dfn{programming objects} which build the interface between |
@deftp {Data Type} void |
68 |
the Application Server and the client. |
This is used as the result type for functions that actually don't return |
69 |
|
a result. |
70 |
As an example, there is a programming object called @code{geasInstance}, |
@end deftp |
71 |
which is nothing more than a language construct in the client language -- |
|
72 |
a normal Python object. However, instances of @code{geasInstance} are used |
@deftp {Data Type} boolean |
73 |
to represent an instance of a business object. |
This is a boolean data type that can only hold TRUE or FALSE values. |
74 |
|
@end deftp |
75 |
In this documentation, the term @dfn{Object} will be used as a shortcut for |
|
76 |
"business object instance", while @dfn{Class} will be used as a shortcut for |
@deftp {Data Type} integer |
77 |
"business object class". On the other hand, we will call programming objects |
This is an integer data type which must be able to contain signed 32 bit |
78 |
by their names instead of using the words "Object" and "Class". For example, |
values. This restriction limits the maximum list size to more than |
79 |
we will say "you have to create a @code{geasSession}". |
2 billion objects. |
80 |
|
@end deftp |
81 |
@section Overview |
|
82 |
|
@deftp {Data Type} string |
83 |
The first step is to create and set up a @code{geasSession}, which has to |
This is a data type that must be able to hold variable lenght strings |
84 |
be done at least once for each process. An application can also set up |
without length limitations. |
85 |
multiple sessions. |
@end deftp |
86 |
|
|
87 |
With the @code{geasSession}, a @code{geasList} can be created to request |
@deftp {Data Type} stringlist |
88 |
a list of objects from the server. This @code{geasList}, once set up, |
This is an one-dimensional array of elements of the type @code{string}. |
89 |
virtually holds a number of @code{geasInstance}s, which represent the actual |
Implementation may restrict the number of elements to 32767. |
90 |
objects. |
@end deftp |
91 |
|
|
92 |
The application can also create a new instance of any business object class, |
@deftp {Data Type} stringtable |
93 |
using @code{geasSession.createInstance}. |
This is a two-dimensional array of elements of the type @code{string}. |
94 |
|
Implementation may restrict the numer of columns as well as the number |
95 |
@code{geasInstance} provides means of altering the attribute values for the |
of rows to 32767. |
96 |
object, deleting the object, calling methods of the object or get other |
@end deftp |
97 |
objects (of other classes) that are refered to by this instance. |
|
98 |
|
@deftp {Data Type} session_id |
99 |
@c ---------------------------------------------------------------------------- |
This is a 32 bit integer value identifying a session. There is no |
100 |
@node Session, List, Introduction, Top |
special meaning one could read from the value. |
101 |
@c ---------------------------------------------------------------------------- |
@end deftp |
102 |
|
|
103 |
@chapter The Session |
@deftp {Data Type} list_id |
104 |
|
This is a 32 bit integer value identifying a list. There is no special |
105 |
@section Logging Into And Logging Out Of The Application Server |
meaning one could read from the value. |
106 |
|
@end deftp |
107 |
@defmethod geasSession login (@var{user}, @var{password}) |
|
108 |
Logs into the server. This is the base for all subsequent operations. |
@c ---------------------------------------------------------------------------- |
109 |
@end defmethod |
@node API Functions, FDL, Data Types, Top |
110 |
|
@c ---------------------------------------------------------------------------- |
111 |
@defmethod geasSession logout |
|
112 |
Logs out of the server. No operations are allowed until @code{login} is called |
@chapter API Functions |
113 |
again. |
|
114 |
@end defmethod |
All API functions can raise exceptions on failure. All functions are |
115 |
|
atomic, in the sense that in case of an exception the function has no |
116 |
@defivar geasSession loggedIn |
effect at all. No error in a function call can cause a function to |
117 |
This read-only variable is set to @code{TRUE} if we are logged into the server, |
be "half-done". |
118 |
@code{FALSE} otherwise. |
|
119 |
@end defivar |
The exact syntax of the API functions is dependant on the selected |
120 |
|
RPC interface and the language sitting on top of it. However, we |
121 |
@section Retrieving Lists Of Business Objects |
are describing the functions in a C-like syntax here, using the data |
122 |
|
type placeholders we defined above. |
123 |
To retrieve a list of objects of a given class, first a @code{geasList} has |
|
124 |
to be created. This is, initially, an empty list that can later be filled. |
@section Session Management |
125 |
|
|
126 |
To populate the list, use the population methods of @code{geasList}. |
@deftypefun session_id open (@var{auth_parameters}) |
127 |
|
Opens a connection to Appserver using the given parameters for |
128 |
@defmethod geasSession createList (@var{class}) |
authentication. The number and type of the parameters still have to |
129 |
Creates an empty list that can hold @code{geasInstance}s of the given class. |
be decided. The return value is a handle to the session that has to |
130 |
@end defmethod |
be passed to all subsequent function calls. |
131 |
|
@end deftypefun |
132 |
@section Transactions |
|
133 |
|
@deftypefun void close (session_id @var{session}, boolean @var{commit}) |
134 |
Transactions take place at the session level. All operations that are performed |
Closes the connection identified by @var{session}. If @var{commit} is |
135 |
within a session while a transaction is running are part of that transaction. |
TRUE, an uncommitted transaction of this session is implicitly |
136 |
|
committed; if @var{commit} is FALSE, it is implicitly rolled back. |
137 |
Nested transactions are not supported. |
After this call, @var{session} will no longer be a valid session |
138 |
|
identifier. |
139 |
There is no explicit command to start a transaction. A transaction is started |
@end deftypefun |
140 |
implicitly when a operation is performed and no transaction is already running. |
|
141 |
|
@deftypefun void commit (session_id @var{session}) |
142 |
Transactions can be ended via @code{commit} and @code{rollback}. |
Commits the current transaction of @var{session}, making all changes |
143 |
|
permanent |
144 |
@defmethod geasSession commit |
@end deftypefun |
145 |
@end defmethod |
|
146 |
|
@deftypefun void rollback (session_id @var{session}) |
147 |
@defmethod geasSession rollback |
Discards all changes done in @var{session} since the last @code{commit} |
148 |
@end defmethod |
or @code{rollback}. |
149 |
|
@end deftypefun |
150 |
@c ---------------------------------------------------------------------------- |
|
151 |
@node List, Instance, Session, Top |
@deftypefun void setcontext (session_id @var{session}, string @var{context}) |
152 |
@c ---------------------------------------------------------------------------- |
Sets the current module context for @var{session} to @var{context}. The |
153 |
|
module context is used to expand all nonfully qualified references to |
154 |
@chapter The List |
classes, properties, and procedures into fully qualified references for |
155 |
|
all subsequent operations within @var{session}. |
156 |
@section Populating The List |
@end deftypefun |
157 |
|
|
158 |
@defivar geasList prefetch |
@section Handling Lists Of Objects |
159 |
This list of strings holds the names of the @dfn{prefetch attributes}. |
|
160 |
Once the @code{geasList} is populated, each defined attribute will be |
These functions provide a means for getting data for a list of objects |
161 |
retrievable, no matter whether it is a prefetch attribute or not. |
fulfilling certain conditions. |
162 |
However, retrieving attributes that are prefetch attributes will be much |
|
163 |
faster. |
@deftypefun list_id request (session_id @var{session}, string @var{classname}, string @var{conditions}, stringlist @var{sort_order}, stringlist @var{properties}) |
164 |
|
Requests a list of objects of class @var{classname} matching the |
165 |
This variable must be set before calling @code{populate}. |
@var{conditions}. Appserver prepares to send the values of the properties |
166 |
@end defivar |
listed in @var{properties} on subsequent calls to @code{fetch}, where |
167 |
|
the order of the objects is determined by the properties listed in |
168 |
@defivar geasList conditions |
@var{sort_order}. |
169 |
This list holds the conditions that have to be fulfilled. |
The properties in @var{sort_order} may, but need not appear in |
170 |
When the list is populated with @code{populate}, only objects that fulfill |
@var{properties}. |
171 |
@emph{all} of the conditions will be inserted into the list. |
If @var{classname}, @var{conditions}, @var{sort_order}, or @var{properties} |
172 |
|
contain not fully referenced identifiers for classes or properties, they |
173 |
The format in which the conditions are passed is to be defined. |
are expanded using @var{context} as the current module context. |
174 |
|
|
175 |
This variable must be set before calling @code{populate}. |
This function only returns a list identifier. No actual data is passed |
176 |
@end defivar |
over the network when calling this function. |
177 |
|
@end deftypefun |
178 |
@defivar geasList sort |
|
179 |
This list of strings holds the names of the attributes that should be used |
@deftypefun integer count (session_id @var{session}, list_id @var{list}) |
180 |
to sort the @code{geasList}. |
Returns the number of objects contained in @var{list}, where @var{list} |
181 |
@end defivar |
is the return value of a previous call to @code{request} |
182 |
|
@end deftypefun |
183 |
@defmethod geasList populate |
|
184 |
Populates the @code{geasList} with all the objects that fulfill all the |
@deftypefun stringtable fetch (session_id @var{session}, list_id @var{list}, integer @var{start}, integer @var{count}, boolean @var{close}) |
185 |
@code{conditions} and orders them using the attributes listed in @code{sort}. |
Returns a 2-dimensional array of data with @var{count} rows, where column 0 |
186 |
|
always holds the object_id of the object, and the remaining columns contain |
187 |
If the @code{geasList} is not empty at the time this method is called, it is |
the values for the properties defined in the previous call to @code{request}. |
188 |
cleared before it is repopulated. If an uncommitted transaction is active at |
Negative values for @var{start} indicate position from the end of the list. |
189 |
the moment, nothing is changed and an exception is raised. |
Negative values for @var{count} are invalid. Count may not be greater than |
190 |
@end defmethod |
32767. |
191 |
|
|
192 |
@section Iterating Through The List |
If @var{close} is TRUE, then the list is "closed", all server-side memory |
193 |
|
allocated with the management of this list is freed and the id @var{list} |
194 |
These methods are useful for iterating through the list. |
may no longer be used in calls to @code{count} or @code{fetch}. However, |
195 |
|
object_ids and other data already received remains valid. |
196 |
@defmethod geasList firstInstance |
@end deftypefun |
197 |
Returns the first @code{geasInstance} of the list. |
|
198 |
@end defmethod |
@section Handling Specific Objects |
199 |
|
|
200 |
@defmethod geasList nextInstance |
These functions provide a means for reading, writing and deleting an object |
201 |
Returns the next @code{geasInstance} of the list. |
or a set of objects, as well as for calling a procedure for an object or |
202 |
@end defmethod |
a set of objects. However, the object_ids for the objects to operate upon |
203 |
|
have to be determined before these functions can be used, for example by |
204 |
@section Creating New Objects |
using the list handling functions described above. |
205 |
|
|
206 |
@defmethod geasList insertNewInstance (@var{classname}) |
@deftypefun stringtable load (session_id @var{session}, string @var{classname}, stringlist @var{object_ids}, stringlist @var{properties}) |
207 |
Creates a new object of the given class. Returns a @code{geasInstance} that |
Returns a 2-dimensional array of data with a row for every entry in |
208 |
represents the newly created object. |
the @var{object_ids} list and a column for every entry in @var{properties}. |
209 |
This object can be regarded persistent as soon as the current transaction is |
Unlike @code{fetch}, this function does @emph{not} automatically return |
210 |
committed. |
the object_ids in column 0. |
211 |
@end defmethod |
@end deftypefun |
212 |
|
|
213 |
@c ---------------------------------------------------------------------------- |
@deftypefun stringlist store (session_id @var{session}, string @var{classname}, stringlist @var{object_ids}, stringlist @var{properties}, stringtable @var{values}) |
214 |
@node Instance, AuthAgent, List, Top |
Stores the data in @var{values} in the objects identified by @var{object_ids}. |
215 |
@c ---------------------------------------------------------------------------- |
Every row in @var{values} matches an entry in @var{object_ids}, while every |
216 |
|
column matches an entry in @var{properties}. |
217 |
@chapter The Instance |
Empty object ids indicate that new objects with that data should be created. |
218 |
|
Validation is performed before the actual storing is done. If validation |
219 |
Note: I seriously consider renaming geasInstance to geasObject, as well as |
of a single object fails, none of the objects are stored, but an exception |
220 |
renaming geasList.firstInstance to geasList.firstObject, geasList.nextInstance |
is raised. |
221 |
to geasList.nextObject and geasList.insertNewInstance to geasList.createObject. |
This function returns a list of all object ids of the stored objects. This |
222 |
It seems to me that these names would be less "technical" and better |
is important for the caller to know under which object ids the new objects |
223 |
understandable. -- Reinhard |
have been stored and can be accessed from now on. |
224 |
|
Note that after calling @code{store}, @code{commit} has to be called to make |
225 |
@section Basic Operations |
the changes persistent, while a call to @code{rollback} can undo the changes. |
226 |
|
@end deftypefun |
227 |
@defmethod geasInstance get (@var{attributename}) |
|
228 |
Returns the content of the given attribute. This can be a string, a number, a |
@deftypefun void delete (session_id @var{session}, string @var{classname}, stringlist @var{object_ids}) |
229 |
@code{geasInstance} or a @code{geasList}, depending on the type of the |
Deletes the objects of class @var{classname} identified through |
230 |
attribute. |
@var{object_ids}. |
231 |
@end defmethod |
@end deftypefun |
232 |
|
|
233 |
@defmethod geasInstance put (@var{attributename}, @var{value}) |
@deftypefun stringlist call (session_id @var{session}, stringlist @var{object_ids}, string @var{procedurename}, stringlist @var{parameters}) |
234 |
Sets the given attribute to @var{value}. The datatype of @var{value} must be |
Calls the procedure @var{procedurename} for every object identified through |
235 |
compatible with the type of the attribute, otherwise an exception will be |
the @var{object_ids} and passes the same @var{parameters} to every call. |
236 |
raised. |
The number of entries in @var{parameters} must match the parameter count |
237 |
@end defmethod |
of the procedure. |
238 |
|
This function returns a list of strings that contains the results of the |
239 |
@defmethod geasInstance call (@var{methodname}) |
procedure calls for each object. |
240 |
Calls a method. |
@end deftypefun |
|
@end defmethod |
|
|
|
|
|
@section Deleting Objects |
|
|
|
|
|
@defmethod geasInstance delete |
|
|
Deletes the business object. The business object is not longer persistent |
|
|
after the next commit. |
|
|
|
|
|
Note: Maybe "destroy" would be a better name, as it's the direct opposite |
|
|
of "createObject". |
|
|
@end defmethod |
|
|
|
|
|
@c ---------------------------------------------------------------------------- |
|
|
@node AuthAgent, FDL, Instance, Top |
|
|
@c ---------------------------------------------------------------------------- |
|
|
|
|
|
@chapter The AuthAgent Object |
|
|
|
|
|
@section Basic Operations |
|
|
|
|
|
@defmethod AuthAgent authentificate (@var{session}, @var{user}, @var{auth}) |
|
|
Authentificate the user @var{user} with the informations stored in the |
|
|
@var{auth} dictionary. The function returns 'true' on success. |
|
|
@end defmethod |
|
|
|
|
|
@defmethod AuthAgent hasAccess (@var{session}, @var{user}, @var{classname}) |
|
|
Return information if the user @var{user} has access to @var{classname}. |
|
|
@end defmethod |
|
241 |
|
|
242 |
@raisesections |
@raisesections |
243 |
|
|
244 |
@c ---------------------------------------------------------------------------- |
@c ---------------------------------------------------------------------------- |
245 |
@node FDL, Index, AuthAgent, Top |
@node FDL, Index, API Functions, Top |
246 |
@c ---------------------------------------------------------------------------- |
@c ---------------------------------------------------------------------------- |
247 |
|
|
248 |
@include fdl.texi |
@include fdl.texi |
251 |
@node Index, (null), FDL, Top |
@node Index, (null), FDL, Top |
252 |
@c ---------------------------------------------------------------------------- |
@c ---------------------------------------------------------------------------- |
253 |
|
|
254 |
@appendixsec Function Index |
@appendixsec Data Type and Function Index |
255 |
|
|
256 |
@printindex fn |
@printindex fn |
257 |
|
|
|
@appendixsec Variable Index |
|
|
|
|
|
@printindex vr |
|
|
|
|
258 |
@bye |
@bye |