gnue/appserver/doc/api api.texi version.texi

[Reinhard Mueller]

CVSROOT:        /cvsroot/gnue
Module name:    gnue
Changes by:     Reinhard Mueller <address@hidden>       02/12/04 18:10:39

Modified files:
        appserver/doc/api: api.texi version.texi 

Log message:
        Updated API documentation to reflect the new API agreed upon in the 
halloween meeting.

CVSWeb URLs:
http://savannah.gnu.org/cgi-bin/viewcvs/gnue/gnue/appserver/doc/api/api.texi.diff?tr1=1.5&tr2=1.6&r1=text&r2=text
http://savannah.gnu.org/cgi-bin/viewcvs/gnue/gnue/appserver/doc/api/version.texi.diff?tr1=1.3&tr2=1.4&r1=text&r2=text

Patches:
Index: gnue/appserver/doc/api/api.texi
diff -c gnue/appserver/doc/api/api.texi:1.5 gnue/appserver/doc/api/api.texi:1.6
*** gnue/appserver/doc/api/api.texi:1.5 Fri Nov 29 08:32:15 2002
--- gnue/appserver/doc/api/api.texi     Wed Dec  4 18:10:39 2002
***************
*** 1,6 ****
  \input texinfo
  @setfilename api.info
! @settitle The GEAS API
  @include version.texi
  @setcontentsaftertitlepage
  @c 
----------------------------------------------------------------------------
--- 1,6 ----
  \input texinfo
  @setfilename api.info
! @settitle The GNUe Appserver API
  @include version.texi
  @setcontentsaftertitlepage
  @c 
----------------------------------------------------------------------------
***************
*** 51,57 ****
  * Session::
  * List::
  * Instance::
! * AuthAgent::
  * FDL:: GNU Free Documentation License
  * Index::
  @end menu
--- 51,57 ----
  * Session::
  * List::
  * Instance::
! * API Functions::
  * FDL:: GNU Free Documentation License
  * Index::
  @end menu
***************
*** 213,219 ****
  @end defmethod
  
  @c 
----------------------------------------------------------------------------
! @node Instance,                                            AuthAgent, List, 
Top
  @c 
----------------------------------------------------------------------------
  
  @chapter The Instance
--- 213,219 ----
  @end defmethod
  
  @c 
----------------------------------------------------------------------------
! @node Instance,                                        API Functions, List, 
Top
  @c 
----------------------------------------------------------------------------
  
  @chapter The Instance
***************
*** 253,349 ****
  @end defmethod
  
  @c 
----------------------------------------------------------------------------
! @node AuthAgent,                                         RPCapi, 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
! 
! @c 
----------------------------------------------------------------------------
! @node RPCapi,                                             FDL, AuthAgent, Top
! @c 
----------------------------------------------------------------------------
! 
! @chapter The RPC API
! 
! @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
! 
! 
! @defmethod session_id open (@var{auth_parameters})
! @end defmethod
! 
! @defmethod void close (@var{session_id},@var{commit})
! @end defmethod
! 
! @defmethod  void commit (@var{session_id})
! 
! @end defmethod
! 
! @defmethod void rollback (@var{session_id})
! 
! @end defmethod
! 
! @defmethod list_id request 
(@var{session_id},@var{context},@var{conditions},@var{sort_order},@var{properties})
! 
! @end defmethod
! 
! @defmethod int count (@var{session_id},@var{list_id})
! 
! @end defmethod
! 
! @defmethod data fetch 
(@var{session_id},@var{list_id},@var{start},@var{count});
! returns a 2-dimensional array of data with count rows, where column 0
! always holds the object_id of the object.
! Negative values for start indicate position from the end of the list.
! @end defmethod
! 
! @defmethod data load (@var{session_id}, 
@var{object_id_list},@var{properties});
! 
! @end defmethod
! 
! @defmethod void store (@var{session_id}, 
@var{object_id_list},@var{properties},@var{values})
! 
! @end defmethod
! 
! @defmethod string (?) call (@var{session_id}, 
@var{object_id_list},@var{methodname}, @var{parameters})
! @end defmethod
! 
! 
! An object_id holds enough information for Appserver to identify the
! object. For example, the object_id could be built from the fully
! qualified class name and the (anonymous) primary key, like
! "base_customer.4711081512345678"
! 
! The "request" and "fetch" functions are used to get data from the
! appserver for objects that fulfill a specific condition, while the
! "load" function is used to request properties of an object with an
! already known object id.
! 
! Properties that hold a reference to another object return the object_id
! in this interface.
  
  @raisesections
  
  @c 
----------------------------------------------------------------------------
! @node FDL,                                                 Index, AuthAgent, 
Top
  @c 
----------------------------------------------------------------------------
  
  @include fdl.texi
--- 253,385 ----
  @end defmethod
  
  @c 
----------------------------------------------------------------------------
! @node API Functions,                                         FDL, Instance, 
Top
  @c 
----------------------------------------------------------------------------
  
! @chapter API Functions
  
! The exact syntax of the API functions is dependant on the selected
! RPC interface and the language sitting on top of it.  However, we
! are describing the functions in a C-like syntax here.
! 
! @section Session Management
! 
! @deftypefun session_id open (@var{auth_parameters})
! Opens a connection to Appserver using the given parameters for
! authentication.  The number and type of the parameters still have to
! be decided.  The return value is a handle to the session that has to
! be passed to all subsequent function calls.
! @end deftypefun
! 
! @deftypefun void close (session_id @var{session}, boolean @var{commit})
! Closes the connection identified by @var{session}.  If @var{commit} is
! TRUE, an uncommitted transaction of this session is implicitly
! committed; if @var{commit} is FALSE, it is implicitly rolled back.
! After this call, @var{session} will no longer be a valid session
! identifier.
! @end deftypefun
! 
! @deftypefun void commit (session_id @var{session})
! Commits the current transaction of @var{session}, making all changes
! permanent
! @end deftypefun
! 
! @deftypefun void rollback (session_id @var{session})
! Discards all changes done in @var{session} since the last @code{commit}
! or @code{rollback}.
! @end deftypefun
! 
! @deftypefun void setcontext (session_id @var{session}, string @var{context})
! Sets the current module context for @var{session} to @var{context}.  The
! module context is used to expand all nonfully qualified references to
! classes, properties, and procedures into fully qualified references for
! all subsequent operations within @var{session}.
! @end deftypefun
! 
! @section Handling Lists Of Objects
! 
! These functions provide a means for getting data for a list of objects
! fulfilling certain conditions.
! 
! @deftypefun list_id request (session_id @var{session}, string 
@var{classname}, string @var{conditions}, stringlist @var{sort_order}, 
stringlist @var{properties})
! Requests a list of objects of class @var{classname} matching the
! @var{conditions}.  Appserver prepares to send the values of the properties
! listed in @var{properties} on subsequent calls to @code{fetch}, where
! the order of the objects is determined by the properties listed in
! @var{sort_order}.
! The properties in @var{sort_order} may, but need not appear in
! @var{properties}.
! If @var{classname}, @var{conditions}, @var{sort_order}, or @var{properties}
! contain not fully referenced identifiers for classes or properties, they
! are expanded using @var{context} as the current module context.
! 
! This function only returns a list identifier.  No actual data is passed
! over the network when calling this function.
! @end deftypefun
! 
! @deftypefun integer count (session_id @var{session}, list_id @var{list})
! Returns the number of objects contained in @var{list}, where @var{list}
! is the return value of a previous call to @code{request}
! @end deftypefun
! 
! @deftypefun stringtable fetch (session_id @var{session}, list_id @var{list}, 
integer @var{start}, integer @var{count}, boolean @var{close})
! Returns a 2-dimensional array of data with @var{count} rows, where column 0
! always holds the object_id of the object, and the remaining columns contain
! the values for the properties defined in the previous call to @code{request}.
! Negative values for @var{start} indicate position from the end of the list.
! Negative values for @var{count} are invalid.
! 
! If @var{close} is TRUE, then the list is "closed", all server-side memory
! allocated with the management of this list is freed and the id @var{list}
! may no longer be used in calls to @code{count} or @code{fetch}. However,
! object_ids and other data already received remains valid.
! @end deftypefun
! 
! @section Handling Specific Objects
! 
! These functions provide a means for reading, writing and deleting an object
! or a set of objects, as well as for calling a procedure for an object or
! a set of objects.  However, the object_ids for the objects to operate upon
! have to be determined before these functions can be used, for example by
! using the list handling functions described above.
! 
! @deftypefun stringtable load (session_id @var{session}, string 
@var{classname}, stringlist @var{object_ids}, stringlist @var{properties})
! Returns a 2-dimensional array of data with a row for every entry in
! the @var{object_ids} list and a column for every entry in @var{properties}.
! Unlike @code{fetch}, this function does @emph{not} automatically return
! the object_ids in column 0.
! @end deftypefun
! 
! @deftypefun void store (session_id @var{session}, string @var{classname}, 
stringlist @var{object_ids}, stringlist @var{properties}, stringtable 
@var{values})
! Stores the data in @var{values} in the objects identified by @var{object_ids}.
! Every row in @var{values} matches an entry in @var{object_ids}, while every
! column matches an entry in @var{properties}.
! Empty object ids indicate that new objects with that data should be created.
! Validation is performed before the actual storing is done. If validation
! of a single object fails, none of the objects are stored, but an exception
! is raised.
! Note that after calling @code{store}, @code{commit} has to be called to make
! the changes persistent, while a call to @code{rollback} can undo the changes.
! @end deftypefun
! 
! @deftypefun void remove (session_id @var{session}, string @var{classname}, 
stringlist @var{object_ids})
! Deletes the objects of class @var{classname} identified through
! @var{object_ids}.
! @end deftypefun
! 
! @deftypefun stringlist call (session_id @var{session}, stringlist 
@var{object_ids}, string @var{procedurename}, stringlist @var{parameters})
! Calls the procedure @var{procedurename} for every object identified through
! the @var{object_ids} and passes the same @var{parameters} to every call.
! The number of entries in @var{parameters} must match the parameter count
! of the procedure.
! This function returns a list of strings that contains the results of the
! procedure calls for each object.
! @end deftypefun
  
  @raisesections
  
  @c 
----------------------------------------------------------------------------
! @node FDL,                                            Index, API Functions, 
Top
  @c 
----------------------------------------------------------------------------
  
  @include fdl.texi
Index: gnue/appserver/doc/api/version.texi
diff -c gnue/appserver/doc/api/version.texi:1.3 
gnue/appserver/doc/api/version.texi:1.4
*** gnue/appserver/doc/api/version.texi:1.3     Thu Oct 24 15:56:58 2002
--- gnue/appserver/doc/api/version.texi Wed Dec  4 18:10:39 2002
***************
*** 1,2 ****
! @set UPDATED 2002-10-24
! @set EDITION 0.0.5
--- 1,2 ----
! @set UPDATED 2002-12-04
! @set EDITION 0.0.6