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

[Reinhard Mueller]

CVSROOT:        /cvsroot/gnue
Module name:    gnue
Changes by:     Reinhard Mueller <address@hidden>       02/10/24 15:56:58

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

Log message:
        Tried to make API documentation clearer.

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

Patches:
Index: gnue/appserver/doc/api/api.texi
diff -c gnue/appserver/doc/api/api.texi:1.3 gnue/appserver/doc/api/api.texi:1.4
*** gnue/appserver/doc/api/api.texi:1.3 Wed Jun  5 16:39:20 2002
--- gnue/appserver/doc/api/api.texi     Thu Oct 24 15:56:58 2002
***************
*** 62,89 ****
  
  @chapter Introduction
  
! The first step is to create and set up an instance of the
! @code{geasSession} class, which has to be done at least once for each
! process.  An application can also set up multiple sessions.
! 
! With the @code{geasSession} object, a @code{geasList} instance
! can be created to request a list of business object instances from the
! server. This @code{geasList} object, once set up, virtually holds a number
! of @code{geasInstance} objects, which represent the actual business objects.
  
  The application can also create a new instance of any business object class,
! using the @code{geasSession.createInstance} method.
  
! The @code{geasInstance} class provides means of altering the field values
! for the instance, deleting the instance, calling methods of the instance or
! get instances of other business object classes that are refered to by this
! instance.
  
  @c 
----------------------------------------------------------------------------
  @node Session,                                          List, Introduction, 
Top
  @c 
----------------------------------------------------------------------------
  
! @chapter The Session Object
  
  @section Logging Into And Logging Out Of The Application Server
  
--- 62,108 ----
  
  @chapter Introduction
  
! @section Terminology
! 
! To understand the principles of the Application Server, one has to clearly
! distinguish between @dfn{business objects} (like customers, orders, or
! accounts) and @dfn{programming objects} which build the interface between
! the Application Server and the client.
! 
! As an example, there is a programming object called @code{geasInstance},
! which is nothing more than a language construct in the client language --
! a normal Python object. However, instances of @code{geasInstance} are used
! to represent an instance of a business object.
! 
! In this documentation, the term @dfn{Object} will be used as a shortcut for
! "business object instance", while @dfn{Class} will be used as a shortcut for
! "business object class". On the other hand, we will call programming objects
! by their names instead of using the words "Object" and "Class". For example,
! we will say "you have to create a @code{geasSession}".
! 
! @section Overview
! 
! The first step is to create and set up a @code{geasSession}, which has to
! be done at least once for each process.  An application can also set up
! multiple sessions.
! 
! With the @code{geasSession}, a @code{geasList} can be created to request
! a list of objects from the server. This @code{geasList}, once set up,
! virtually holds a number of @code{geasInstance}s, which represent the actual
! objects.
  
  The application can also create a new instance of any business object class,
! using @code{geasSession.createInstance}.
  
! @code{geasInstance} provides means of altering the attribute values for the
! object, deleting the object, calling methods of the object or get other
! objects (of other classes) that are refered to by this instance.
  
  @c 
----------------------------------------------------------------------------
  @node Session,                                          List, Introduction, 
Top
  @c 
----------------------------------------------------------------------------
  
! @chapter The Session
  
  @section Logging Into And Logging Out Of The Application Server
  
***************
*** 103,118 ****
  
  @section Retrieving Lists Of Business Objects
  
! To retrieve a list of business objects of a given class, first a
! @code{geasList} object has to be created. This is, initially, an empty
! list that can later be filled with instances of the given class.
  
! To populate the list with real instances, use the population methods of the
! @code{geasList} object.
  
  @defmethod geasSession createList (@var{class})
! Creates an empty list that can hold @code{geasInstance}) objects of the
! given class.
  @end defmethod
  
  @section Transactions
--- 122,134 ----
  
  @section Retrieving Lists Of Business Objects
  
! To retrieve a list of objects of a given class, first a @code{geasList} has
! to be created. This is, initially, an empty list that can later be filled.
  
! To populate the list, use the population methods of @code{geasList}.
  
  @defmethod geasSession createList (@var{class})
! Creates an empty list that can hold @code{geasInstance}s of the given class.
  @end defmethod
  
  @section Transactions
***************
*** 125,132 ****
  There is no explicit command to start a transaction. A transaction is started
  implicitly when a operation is performed and no transaction is already 
running.
  
! Transactions can be ended via the @code{commit} and the @code{rollback}
! methods.
  
  @defmethod geasSession commit
  @end defmethod
--- 141,147 ----
  There is no explicit command to start a transaction. A transaction is started
  implicitly when a operation is performed and no transaction is already 
running.
  
! Transactions can be ended via @code{commit} and @code{rollback}.
  
  @defmethod geasSession commit
  @end defmethod
***************
*** 138,180 ****
  @node List,                                              Instance, Session, 
Top
  @c 
----------------------------------------------------------------------------
  
! @chapter The List Object
  
  @section Populating The List
  
  @defivar geasList prefetch
! This list of strings holds the names of the @dfn{prefetch fields}.
! Once the @code{geasList} is populated, each defined field will be
! retrievable for every object in the list.
! However, retrieving fields that appear in the list of prefetch fields will
! be much faster.
  
! This variable must be set before calling the @code{populate} method.
  @end defivar
  
  @defivar geasList conditions
  This list holds the conditions that have to be fulfilled.
! When the list is populated with the @code{populate} method, only instances
! that fulfill @emph{all} of the conditions will be inserted into the list.
  
  The format in which the conditions are passed is to be defined.
  
! This variable must be set before calling the @code{populate} method.
  @end defivar
  
  @defivar geasList sort
! This list of strings holds the names of the fields that should be used
  to sort the @code{geasList}.
  @end defivar
  
  @defmethod geasList populate
! Populates the list with all the objects that fulfill the conditions set in the
! @code{conditions} variable and orders them using the fields listed in the
! @code{sort} variable.
! 
! If the list is not empty at the time this method is called, it is cleared
! before it is repopulated. If an uncommitted transaction is active at the
! moment, nothing is changed and an exception is raised.
  @end defmethod
  
  @section Iterating Through The List
--- 153,194 ----
  @node List,                                              Instance, Session, 
Top
  @c 
----------------------------------------------------------------------------
  
! @chapter The List
  
  @section Populating The List
  
  @defivar geasList prefetch
! This list of strings holds the names of the @dfn{prefetch attributes}.
! Once the @code{geasList} is populated, each defined attribute will be
! retrievable, no matter whether it is a prefetch attribute or not.
! However, retrieving attributes that are prefetch attributes will be much
! faster.
  
! This variable must be set before calling @code{populate}.
  @end defivar
  
  @defivar geasList conditions
  This list holds the conditions that have to be fulfilled.
! When the list is populated with @code{populate}, only objects that fulfill
! @emph{all} of the conditions will be inserted into the list.
  
  The format in which the conditions are passed is to be defined.
  
! This variable must be set before calling @code{populate}.
  @end defivar
  
  @defivar geasList sort
! This list of strings holds the names of the attributes that should be used
  to sort the @code{geasList}.
  @end defivar
  
  @defmethod geasList populate
! Populates the @code{geasList} with all the objects that fulfill all the
! @code{conditions} and orders them using the attributes listed in @code{sort}.
! 
! If the @code{geasList} is not empty at the time this method is called, it is
! cleared before it is repopulated. If an uncommitted transaction is active at
! the moment, nothing is changed and an exception is raised.
  @end defmethod
  
  @section Iterating Through The List
***************
*** 189,225 ****
  Returns the next @code{geasInstance} of the list.
  @end defmethod
  
! @section Creating New Business Object Instances
  
! @defmethod geasList insertNewInstance (@var{class})
! Creates a new instance of a business object of the given class. Returns a
! @code{geasInstance} object that represents the newly created business object.
! This business object can be regarded persistent as soon as the current
! transaction is committed.
  @end defmethod
  
  @c 
----------------------------------------------------------------------------
  @node Instance,                                            AuthAgent, List, 
Top
  @c 
----------------------------------------------------------------------------
  
! @chapter The Instance Object
  
  @section Basic Operations
  
! @defmethod geasInstance get (@var{fieldname})
! Returns the content of the given field. This can be a string, a number, an
! object of @code{geasInstance} class or an object of @code{geasList} class,
! depending on the type of the field.
  @end defmethod
  
! @defmethod geasInstance put (@var{fieldname}, @var{value})
! Sets the given field of the business object to @var{value}. The datatype of
! @var{value} must be compatible with the type of the field, otherwise an
! exception will be raised.
  @end defmethod
  
  @defmethod geasInstance call (@var{methodname})
! Calls a method of the business object.
  @end defmethod
  
  @section Deleting Objects
--- 203,245 ----
  Returns the next @code{geasInstance} of the list.
  @end defmethod
  
! @section Creating New Objects
  
! @defmethod geasList insertNewInstance (@var{classname})
! Creates a new object of the given class. Returns a @code{geasInstance} that
! represents the newly created object.
! This object can be regarded persistent as soon as the current transaction is
! committed.
  @end defmethod
  
  @c 
----------------------------------------------------------------------------
  @node Instance,                                            AuthAgent, List, 
Top
  @c 
----------------------------------------------------------------------------
  
! @chapter The Instance
! 
! Note: I seriously consider renaming geasInstance to geasObject, as well as
! renaming geasList.firstInstance to geasList.firstObject, geasList.nextInstance
! to geasList.nextObject and geasList.insertNewInstance to 
geasList.createObject.
! It seems to me that these names would be less "technical" and better
! understandable.  -- Reinhard
  
  @section Basic Operations
  
! @defmethod geasInstance get (@var{attributename})
! Returns the content of the given attribute. This can be a string, a number, a
! @code{geasInstance} or a @code{geasList}, depending on the type of the
! attribute.
  @end defmethod
  
! @defmethod geasInstance put (@var{attributename}, @var{value})
! Sets the given attribute to @var{value}. The datatype of @var{value} must be
! compatible with the type of the attribute, otherwise an exception will be
! raised.
  @end defmethod
  
  @defmethod geasInstance call (@var{methodname})
! Calls a method.
  @end defmethod
  
  @section Deleting Objects
***************
*** 227,234 ****
  @defmethod geasInstance delete
  Deletes the business object. The business object is not longer persistent
  after the next commit.
- @end defmethod
  
  
  @c 
----------------------------------------------------------------------------
  @node AuthAgent,                                             FDL, Instance, 
Top
--- 247,256 ----
  @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
***************
*** 239,246 ****
  @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})
--- 261,268 ----
  @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})
Index: gnue/appserver/doc/api/version.texi
diff -c gnue/appserver/doc/api/version.texi:1.2 
gnue/appserver/doc/api/version.texi:1.3
*** gnue/appserver/doc/api/version.texi:1.2     Sun May 26 16:46:25 2002
--- gnue/appserver/doc/api/version.texi Thu Oct 24 15:56:58 2002
***************
*** 1,2 ****
! @set UPDATED 2002-05-26
! @set EDITION 0.0.4
--- 1,2 ----
! @set UPDATED 2002-10-24
! @set EDITION 0.0.5