/[papo]/gnue/appserver/doc/api/api.texi
ViewVC logotype

Diff of /gnue/appserver/doc/api/api.texi

Parent Directory Parent Directory | Revision Log Revision Log | View Patch Patch

revision 1.2 by styxman, Fri Nov 8 16:28:59 2002 UTC revision 1.2.4.1 by anthonyl, Tue Mar 4 22:03:46 2003 UTC
# Line 1  Line 1 
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
# Line 43  Free Documentation License''. Line 44  Free Documentation License''.
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
# Line 281  Return information if the user @var{user Line 251  Return information if the user @var{user
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

Legend:
Removed from v.1.2  
changed lines
  Added in v.1.2.4.1

savannah-hackers-public@gnu.org
ViewVC Help
Powered by ViewVC 1.1.26