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

[Reinhard Mueller]

CVSROOT:        /cvsroot/gnue
Module name:    gnue
Changes by:     Reinhard Mueller <address@hidden>       02/12/08 13:47:57

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

Log message:
        Finished update to new API.

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

Patches:
Index: gnue/appserver/doc/api/api.texi
diff -c gnue/appserver/doc/api/api.texi:1.6 gnue/appserver/doc/api/api.texi:1.7
*** gnue/appserver/doc/api/api.texi:1.6 Wed Dec  4 18:10:39 2002
--- gnue/appserver/doc/api/api.texi     Sun Dec  8 13:47:57 2002
***************
*** 3,8 ****
--- 3,9 ----
  @settitle The GNUe Appserver API
  @include version.texi
  @setcontentsaftertitlepage
+ @syncodeindex tp fn
  @c 
----------------------------------------------------------------------------
  @ifnottex
  @chapheading The GNU Enterprise Application Server
***************
*** 43,266 ****
  @end titlepage
  
  @c 
----------------------------------------------------------------------------
! @node Top,                                                         
Introduction
  @c 
----------------------------------------------------------------------------
  
  @menu
! * Introduction::
! * Session::
! * List::
! * Instance::
  * API Functions::
  * FDL:: GNU Free Documentation License
  * Index::
  @end menu
  
  @c 
----------------------------------------------------------------------------
! @node Introduction,                                           Session, Top, 
Top
  @c 
----------------------------------------------------------------------------
  
! @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
! 
! @defmethod geasSession login (@var{user}, @var{password})
! Logs into the server.  This is the base for all subsequent operations.
! @end defmethod
! 
! @defmethod geasSession logout
! Logs out of the server.  No operations are allowed until @code{login} is 
called
! again.
! @end defmethod
! 
! @defivar geasSession loggedIn
! This read-only variable is set to @code{TRUE} if we are logged into the 
server,
! @code{FALSE} otherwise.
! @end defivar
! 
! @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
! 
! Transactions take place at the session level. All operations that are 
performed
! within a session while a transaction is running are part of that transaction.
! 
! Nested transactions are not supported.
! 
! 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
! 
! @defmethod geasSession rollback
! @end defmethod
! 
! @c 
----------------------------------------------------------------------------
! @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
! 
! These methods are useful for iterating through the list.
! 
! @defmethod geasList firstInstance
! Returns the first @code{geasInstance} of the list.
! @end defmethod
! 
! @defmethod geasList nextInstance
! 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,                                        API Functions, 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
! 
! @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 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
  
--- 44,120 ----
  @end titlepage
  
  @c 
----------------------------------------------------------------------------
! @node Top,                                                           Data 
Types
  @c 
----------------------------------------------------------------------------
  
  @menu
! * Data Types::
  * API Functions::
  * FDL:: GNU Free Documentation License
  * Index::
  @end menu
  
  @c 
----------------------------------------------------------------------------
! @node Data Types,                                       API Functions, Top, 
Top
  @c 
----------------------------------------------------------------------------
  
! @chapter Data Types
  
! In the API definition, we will make use of the following data type
! placeholders, which will have to be translated into appropriate data
! types for the various implemented RPC mechanisms:
! 
! @deftp {Data Type} void
! This is used as the result type for functions that actually don't return
! a result.
! @end deftp
! 
! @deftp {Data Type} boolean
! This is a boolean data type that can only hold TRUE or FALSE values.
! @end deftp
! 
! @deftp {Data Type} integer
! This is an integer data type which must be able to contain signed 32 bit
! values.  This restriction limits the maximum list size to more than
! 2 billion objects.
! @end deftp
! 
! @deftp {Data Type} string
! This is a data type that must be able to hold variable lenght strings
! without lenth limitations.
! @end deftp
! 
! @deftp {Data Type} stringlist
! This is an one-dimensional array of elements of the type @code{string}.
! Implementation may restrict the number of elements to 32767.
! @end deftp
! 
! @deftp {Data Type} stringtable
! This is a two-dimensional array of elements of the type @code{string}.
! Implementation may restrict the numer of columns as well as the number
! of rows to 32767.
! @end deftp
! 
! @deftp {Data Type} session_id
! This is a 32 bit integer value identifying a session.  There is no
! special meaning one could read from the value.
! @end deftp
! 
! @deftp {Data Type} list_id
! This is a 32 bit integer value identifying a list.  There is no special
! meaning one could read from the value.
! @end deftp
  
  @c 
----------------------------------------------------------------------------
! @node API Functions,                                       FDL, Data Types, 
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, using the data
! type placeholders we defined above.
  
  @section Session Management
  
***************
*** 327,333 ****
  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}
--- 181,188 ----
  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.  Count may not be greater than
! 32767.
  
  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}
***************
*** 388,399 ****
  @node Index,                                                   (null), FDL, 
Top
  @c 
----------------------------------------------------------------------------
  
! @appendixsec Function Index
  
  @printindex fn
- 
- @appendixsec Variable Index
- 
- @printindex vr
  
  @bye
--- 243,250 ----
  @node Index,                                                   (null), FDL, 
Top
  @c 
----------------------------------------------------------------------------
  
! @appendixsec Data Type and Function Index
  
  @printindex fn
  
  @bye
Index: gnue/appserver/doc/api/version.texi
diff -c gnue/appserver/doc/api/version.texi:1.4 
gnue/appserver/doc/api/version.texi:1.5
*** gnue/appserver/doc/api/version.texi:1.4     Wed Dec  4 18:10:39 2002
--- gnue/appserver/doc/api/version.texi Sun Dec  8 13:47:57 2002
***************
*** 1,2 ****
! @set UPDATED 2002-12-04
  @set EDITION 0.0.6
--- 1,2 ----
! @set UPDATED 2002-12-08
  @set EDITION 0.0.6