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

[Reinhard Mueller]

CVSROOT:        /cvsroot/gnue
Module name:    gnue-appserver
Branch:         
Changes by:     Reinhard Mueller <address@hidden>       03/09/17 13:13:52

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

Log message:
        Document exceptions and system classes.

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

Patches:
Index: gnue-appserver/doc/api/api.texi
diff -c gnue-appserver/doc/api/api.texi:1.9 gnue-appserver/doc/api/api.texi:1.10
*** gnue-appserver/doc/api/api.texi:1.9 Tue Jan  7 16:57:41 2003
--- gnue-appserver/doc/api/api.texi     Wed Sep 17 13:13:52 2003
***************
*** 50,55 ****
--- 50,56 ----
  @menu
  * Data Types::
  * API Functions::
+ * System Classes::
  * FDL:: GNU Free Documentation License
  * Index::
  @end menu
***************
*** 106,112 ****
  @end deftp
  
  @c 
----------------------------------------------------------------------------
! @node API Functions,                                       FDL, Data Types, 
Top
  @c 
----------------------------------------------------------------------------
  
  @chapter API Functions
--- 107,113 ----
  @end deftp
  
  @c 
----------------------------------------------------------------------------
! @node API Functions,                            System Classes, Data Types, 
Top
  @c 
----------------------------------------------------------------------------
  
  @chapter API Functions
***************
*** 121,126 ****
--- 122,129 ----
  are describing the functions in a C-like syntax here, using the data
  type placeholders we defined above.
  
+ @c 
----------------------------------------------------------------------------
+ 
  @section Session Management
  
  @deftypefun session_id open (@var{auth_parameters})
***************
*** 128,133 ****
--- 131,139 ----
  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.
+ 
+ An Exception is raised if the server cannot be contacted or authentication
+ fails.
  @end deftypefun
  
  @deftypefun void close (session_id @var{session}, boolean @var{commit})
***************
*** 136,166 ****
  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
--- 142,173 ----
  committed; if @var{commit} is FALSE, it is implicitly rolled back.
  After this call, @var{session} will no longer be a valid session
  identifier.
+ 
+ An Exception is raised if @var{session} is not a valid session identifier.
  @end deftypefun
  
  @deftypefun void commit (session_id @var{session})
  Commits the current transaction of @var{session}, making all changes
! permanent.
! 
! An Exception is raised if @var{session} is not a valid session identifier.
  @end deftypefun
  
  @deftypefun void rollback (session_id @var{session})
  Discards all changes done in @var{session} since the last @code{commit}
  or @code{rollback}.
  
! An Exception is raised if @var{session} is not a valid session identifier.
  @end deftypefun
  
+ @c 
----------------------------------------------------------------------------
+ 
  @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{sortorder}, 
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
***************
*** 174,184 ****
  
  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})
--- 181,198 ----
  
  This function only returns a list identifier.  No actual data is passed
  over the network when calling this function.
+ 
+ An Exception is raised if @var{session} is not a valid session identifier, the
+ requested class does not exist, the current user has not access to the
+ requested class, or any of the given @var{properties} does not exist.
  @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}.
! 
! An Exception is raised if @var{session} is not a valid session identifier or
! @var{list} is not a valid list identifier.
  @end deftypefun
  
  @deftypefun stringtable fetch (session_id @var{session}, list_id @var{list}, 
integer @var{start}, integer @var{count}, boolean @var{close})
***************
*** 193,200 ****
--- 207,219 ----
  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.
+ 
+ An Exception is raised if @var{session} is not a valid session identifier or
+ @var{list} is not a valid list identifier.
  @end deftypefun
  
+ @c 
----------------------------------------------------------------------------
+ 
  @section Handling Specific Objects
  
  These functions provide a means for reading, writing and deleting an object
***************
*** 208,213 ****
--- 227,237 ----
  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.
+ 
+ An Exception is raised if @var{session} is not a valid session identifier, the
+ requested class does not exist, the current user has not access to the
+ requested class, any of the given @var{object_ids} does not exist, or any of
+ the given @var{properties} does not exist.
  @end deftypefun
  
  @deftypefun stringlist store (session_id @var{session}, string 
@var{classname}, stringlist @var{object_ids}, stringlist @var{properties}, 
stringtable @var{values})
***************
*** 223,248 ****
  have been stored and can be accessed from now on.
  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 delete (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
--- 247,384 ----
  have been stored and can be accessed from now on.
  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.
+ 
+ An Exception is raised if @var{session} is not a valid session identifier, the
+ requested class does not exist, the current user has not access to the
+ requested class, any of the given @var{object_ids} does not exist, any of
+ the given @var{properties} does not exist, or any of the @var{values} does not
+ fit the corresponding property.
  @end deftypefun
  
  @deftypefun void delete (session_id @var{session}, string @var{classname}, 
stringlist @var{object_ids})
  Deletes the objects of class @var{classname} identified through
  @var{object_ids}.
+ 
+ An Exception is raised if @var{session} is not a valid session identifier, the
+ requested class does not exist, the current user has not access to the
+ requested class, or any of the given @var{object_ids} does not exist.
  @end deftypefun
  
! @deftypefun stringlist call (session_id @var{session}, string 
@var{classname}, 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.
+ 
+ An Exception is raised if @var{session} is not a valid session identifier, the
+ requested class does not exist, the current user has not access to the
+ requested class, any of the given @var{object_ids} does not exist, or the 
given
+ procedure is not defined.
  @end deftypefun
  
+ @c 
----------------------------------------------------------------------------
+ @node System Classes,                                   FDL, API Functions, 
Top
+ @c 
----------------------------------------------------------------------------
+ 
+ @chapter System Classes
+ 
+ The following classes are always defined and can be accessed to query and/or
+ influence class definitions and (in future) other information about the state
+ of the Application Server.
+ 
+ @c 
----------------------------------------------------------------------------
+ 
+ @section @code{gnue_module}
+ 
+ @defcv Property gnue_module gnue_name string(35)
+ The name of the module.
+ @end defcv
+ 
+ @defcv Property gnue_module gnue_comment string(70)
+ Arbitary text explaining the purpose of the module.
+ @end defcv
+ 
+ @c 
----------------------------------------------------------------------------
+ 
+ @section @code{gnue_class}
+ 
+ @defcv Property gnue_class gnue_module gnue_module
+ The module that originally defines the class.
+ @end defcv
+ 
+ @defcv Property gnue_class gnue_name string(35)
+ The name of the class without the module name. You can find out the module 
name
+ by referencing the @code{gnue_module} property.
+ @end defcv
+ 
+ @defcv Property gnue_class gnue_comment string(70)
+ Arbitary text explaining the purpose of the class.
+ @end defcv
+ 
+ @c 
----------------------------------------------------------------------------
+ 
+ @section @code{gnue_property}
+ 
+ @defcv Property gnue_property gnue_class gnue_class
+ The class the property belongs to.
+ @end defcv
+ 
+ @defcv Property gnue_property gnue_module gnue_module
+ The module that defines the property.
+ @end defcv
+ 
+ @defcv Property gnue_property gnue_name string(35)
+ The name of the property without the module name. You can find out the module
+ name by referencing the @code{gnue_module} property.
+ @end defcv
+ 
+ @defcv Property gnue_property gnue_type string(35)
+ The type of the property. This can be one of the predefined types "string",
+ "number", "boolean" or "datetime", or the name of a class, in which case the
+ property is a reference property to that class.
+ @end defcv
+ 
+ @defcv Property gnue_property gnue_length number(6)
+ The length of the property. Only relevant if @code{gnue_type} is "string" or
+ "number".
+ @end defcv
+ 
+ @defcv Property gnue_property gnue_scale number(4)
+ Only relevant if @code{gnue_type} is "number", in which case it defines the
+ number of fractional digits, while @code{gnue_length} defines the total number
+ of digits.
+ @end defcv
+ 
+ @defcv Property gnue_property gnue_comment string(70)
+ Arbitary text explaining the purpose of the property.
+ @end defcv
+ 
+ @c 
----------------------------------------------------------------------------
+ 
+ @section @code{gnue_useraccess}
+ 
+ Note: This class is only preliminary and will most probably disappear in
+ future and be replaced by a more flexible access control system.
+ 
+ @defcv Property gnue_useraccess gnue_username string(20)
+ @end defcv
+ 
+ @defcv Property gnue_useraccess gnue_password string(20)
+ @end defcv
+ 
+ @defcv Property gnue_useraccess gnue_classlist string(100)
+ A list of the fully qualified names of all classes the user should have access
+ to, seperated by blanks.
+ @end defcv
+ 
+ @c 
----------------------------------------------------------------------------
+ 
  @raisesections
  
  @c 
----------------------------------------------------------------------------
! @node FDL,                                           Index, System Classes, 
Top
  @c 
----------------------------------------------------------------------------
  
  @include fdl.texi
Index: gnue-appserver/doc/api/version.texi
diff -c gnue-appserver/doc/api/version.texi:1.6 
gnue-appserver/doc/api/version.texi:1.7
*** gnue-appserver/doc/api/version.texi:1.6     Fri Dec 20 15:33:26 2002
--- gnue-appserver/doc/api/version.texi Wed Sep 17 13:13:52 2003
***************
*** 1,2 ****
! @set UPDATED 2002-12-20
! @set EDITION 0.0.7
--- 1,2 ----
! @set UPDATED 2003-09-17
! @set EDITION 0.0.8