The GNU Enterprise Application Server
*************************************

Application Programmer's Interface

Edition 0.5.3, 2006-03-24

   Copyright (C) 2002-2006 Free Software Foundation

   Permission is granted to make and distribute verbatim copies of this
manual provided the copyright notice and this permission notice are
preserved on all copies.

   Permission is granted to copy and distribute modified versions of
this manual under the conditions for verbatim copying, provided that
the entire resulting derived work is distributed under the terms of a
permission notice identical to this one.

   Permission is granted to copy and distribute translations of this
manual into another language, under the above conditions for modified
versions, except that this permission notice may be stated in a
translation approved by the Foundation.

1 Introduction
**************

This document describes the RPC interface provided by GNUe Appserver.
Using this information, you can create a front end to GNUe Appserver.

   This document is _not_ about writing database applications with GNU
Enterprise. You only have to read this document if you are not
satisfied with GNUe Forms, and want to write a different front end to
Appserver.

2 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:

 -- Data Type: void
     This is used as the result type for functions that actually don't
     return a result.

 -- Data Type: boolean
     This is a boolean data type that can only hold TRUE or FALSE
     values.

 -- 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.

 -- Data Type: string
     This is a data type that must be able to hold variable lenght
     strings without length limitations.

 -- Data Type: stringlist
     This is an one-dimensional array of elements of the type `string'.
     Implementation may restrict the number of elements to 32767.

 -- Data Type: stringtable
     This is a two-dimensional array of elements of the type `string'.
     Implementation may restrict the numer of columns as well as the
     number of rows to 32767.

   The RPC API is object oriented. Some of the methods described here
return object instances, of which methods can be called subsequently.
Handling of these objects depends on the RPC transport method.

3 API Functions
***************

All API functions can raise exceptions on failure.  All functions are
atomic, in the sense that in case of an exception the function has no
effect at all.  No error in a function call can cause a function to be
"half-done".

   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.

3.1 Session Management
======================

 -- Function: session open (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 session object.

     An Exception is raised if the server cannot be contacted or
     authentication fails.

 -- Method on session: void commit ()
     Commits the current transaction of the session, making all changes
     permanent.

     Exceptions can happen if a OnValidate procedure raises an
     exception, or if a non-nullable property is not set.

 -- Method on session: void rollback (session_id SESSION)
     Discards all changes done in this session since the last `commit'
     or `rollback'.

3.2 Handling Lists Of Objects
=============================

These functions provide a means for getting data for a list of objects
fulfilling certain conditions.

 -- Method on session: list request (string CLASSNAME, stringlist
          CONDITIONS, stringlist SORTORDER, stringlist PROPERTIES)
     Requests a list of objects of class CLASSNAME matching the
     CONDITIONS.  Appserver prepares to send the values of the
     properties listed in PROPERTIES on subsequent calls to `fetch',
     where the order of the objects is determined by the properties
     listed in SORT_ORDER.  The properties in SORT_ORDER may, but need
     not appear in PROPERTIES.  CLASSNAME, CONDITIONS, SORT_ORDER, and
     PROPERTIES must contain fully referenced identifiers for classes
     or properties.

     This function only returns a list object.  No actual data is passed
     over the network when calling this function.

     An Exception is raised if the requested class does not exist, the
     current user has no access to the requested class, or any of the
     given PROPERTIES does not exist.

 -- Method on list: integer count ()
     Returns the number of objects contained in the list.

 -- Method on list: stringtable fetch (integer START, integer COUNT)
     Returns a 2-dimensional array of data with 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 `request'.  Negative values for START
     indicate position from the end of the list.  Negative values for
     COUNT are invalid.  Count may not be greater than 32767.

3.3 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.

 -- Method on session: stringtable load (string CLASSNAME, stringlist
          OBJECT_IDS, stringlist PROPERTIES)
     Returns a 2-dimensional array of data with a row for every entry in
     the OBJECT_IDS list and a column for every entry in PROPERTIES.
     Unlike `fetch', this function does _not_ automatically return the
     object_ids in column 0.

     If this function is called with one of the OBJECT_IDS being an
     empty string, the corresponding row in the result contains a list
     of the data types of the PROPERTIES.  This is a temporary hack and
     will be removed again in a future version!

     An Exception is raised if the requested class does not exist, the
     current user has no access to the requested class, any of the
     given OBJECT_IDS does not exist, or any of the given PROPERTIES
     does not exist.

 -- Method on session: stringlist store (string CLASSNAME, stringlist
          OBJECT_IDS, stringlist PROPERTIES, stringtable VALUES)
     Stores the data in VALUES in the objects identified by OBJECT_IDS.
     Every row in VALUES matches an entry in OBJECT_IDS, while every
     column matches an entry in 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.  This function returns a list of all object
     ids of the stored objects.  This is important for the caller to
     know under which object ids the new objects have been stored and
     can be accessed from now on.  Note that after calling `store',
     `commit' has to be called to make the changes persistent, while a
     call to `rollback' can undo the changes.

     An Exception is raised if the requested class does not exist, the
     current user has no access to the requested class, any of the
     given OBJECT_IDS does not exist, any of the given PROPERTIES does
     not exist, or any of the VALUES does not fit the corresponding
     property.

 -- Method on session: void delete (string CLASSNAME, stringlist
          OBJECT_IDS)
     Deletes the objects of class CLASSNAME identified through
     OBJECT_IDS.

     An Exception is raised if the requested class does not exist, the
     current user has no access to the requested class, or any of the
     given OBJECT_IDS does not exist.

 -- Method on session: stringlist call (session_id SESSION, string
          CLASSNAME, stringlist OBJECT_IDS, string PROCEDURENAME,
          stringlist PARAMETERS)
     Calls the procedure PROCEDURENAME for every object identified
     through the OBJECT_IDS and passes the same PARAMETERS to every
     call.  The number of entries in 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 the requested class does not exist, the
     current user has no access to the requested class, any of the
     given OBJECT_IDS does not exist, or the given procedure is not
     defined.

4 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.

4.1 `gnue_module'
=================

 -- Property of gnue_module: gnue_name string(35)
     The name of the module.

 -- Property of gnue_module: gnue_comment string(70)
     Arbitary text explaining the purpose of the module.

4.2 `gnue_class'
================

 -- Property of gnue_class: gnue_module gnue_module
     The module that originally defines the class.

 -- Property of 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 `gnue_module' property.

 -- Property of gnue_class: gnue_comment string(70)
     Arbitary text explaining the purpose of the class.

4.3 `gnue_property'
===================

 -- Property of gnue_property: gnue_class gnue_class
     The class the property belongs to.

 -- Property of gnue_property: gnue_module gnue_module
     The module that defines the property.

 -- Property of 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 `gnue_module' property.

 -- Property of gnue_property: gnue_type string(35)
     The type of the property. This can be one of the predefined types
     "string", "number", "boolean", "date", "time", or "datetime", or
     the name of a class, in which case the property is a reference
     property to that class.

 -- Property of gnue_property: gnue_length number(6)
     The length of the property. Only relevant if `gnue_type' is
     "string" or "number".

 -- Property of gnue_property: gnue_scale number(4)
     Only relevant if `gnue_type' is "number", in which case it defines
     the number of fractional digits, while `gnue_length' defines the
     total number of digits.

 -- Property of gnue_property: gnue_nullable boolean
     If TRUE this property can contain NULL values.

 -- Property of gnue_property: gnue_comment string(70)
     Arbitary text explaining the purpose of the property.

4.4 `gnue_procedure'
====================

 -- Property of gnue_procedure: gnue_class gnue_class
     The class the procedure belongs to.

 -- Property of gnue_procedure: gnue_module gnue_module
     The module that defines the procedure.

 -- Property of gnue_procedure: gnue_name string(35)
     The name of the procedure without the module name. You can find
     out the module name by referencing the `gnue_module' property.

 -- Property of gnue_procedure: gnue_language string(10)
     Language of the procedure. Currently only "python" is valid.

 -- Property of gnue_procedure: gnue_code string
     The source code of the procedure.

 -- Property of gnue_procedure: gnue_type string(35)
     The type of the procedures' result. This can be one of the
     predefined types "string", "number", "boolean", "date", "time", or
     "datetime". If the procedure has no result this property will be
     left empty.

 -- Property of gnue_procedure: gnue_length number(6)
     The length of the procedures' result. Only relevant if `gnue_type'
     is "string" or "number".

 -- Property of gnue_procedure: gnue_scale number(4)
     Only relevant if `gnue_type' is "number", in which case it defines
     the number of fractional digits, while `gnue_length' defines the
     total number of digits.

 -- Property of gnue_procedure: gnue_nullable boolean
     If TRUE this procedure can return "NULL" or "None" values.

 -- Property of gnue_procedure: gnue_comment string(70)
     Arbitary text explaining the purpose of the procedure.

4.4.1 Special procedures
------------------------

Procedures having a `gnue_name' starting with "`get'" and without any
parameters but a result are automatically treated as "calculated
properties".  A procedure called "`getfoobar'" in a module named
"`address'" could be accessed as a property called "`address_foobar'".
Appserver will implicitly call the procedure "address_getfoobar".

   Besides this the application server looks for other special
procedure names to be called automatically as "triggers". Note that one
class can have several of these, all named identically, as each module
can define its own trigger; in this case the base class' trigger is
called first, followed by the triggers defined in other modules.  The
following procedure names (`gnue_name') are recognized:

4.4.1.1 OnInit
..............

When the application server comes to create a new instance of a given
class, all procedures of this class having a `gnue_name' of "`OnInit'"
(case-insensitive) are called. Such a procedure can refer to the
instance via SELF.

4.4.1.2 OnChange
................

Before the application server changes the value of a property, all
procedures of the class having a `gnue_name' of "`OnChange'"
(case-insensitive) are called. The variable PROPERTYNAME holds the name
of the property to be changed. The variable NEWVALUE holds the new
value which should be set and OLDVALUE holds the original value of the
property. One can use the function `abort' to prevent a modification of
the property.

4.4.1.3 OnValidate
..................

Before the application server performs a `commit' it calls all
procedures of the class having a `gnue_name' of "`OnValidate'"
(case-insensitive). Such a procedure can refer to the calling instance
via SELF. One can use the function `abort' to abort the validation
process and to stop the commit.

4.4.1.4 OnDelete
................

Before the application server deletes an instance of a class all
procedures of the class having a `gnue_name' of "`OnDelete'"
(case-insensitive) will be executed. Such a procedure can refer to the
calling instance via SELF. One can use the function `abort' to abort
the deletion.

4.5 `gnue_parameter'
====================

 -- Property of gnue_parameter: gnue_procedure gnue_procedure
     The procedure the parameter belongs to.

 -- Property of gnue_parameter: gnue_name string(35)
     The name of the parameter.  The parameter with the name "result"
     defines the return value of the procedure.

 -- Property of gnue_parameter: gnue_type string(35)
     The type of the parameter. This can be one of the predefined types
     "string", "number", "boolean", "date", "time", or "datetime".
     Object references cannot be passed as parameters.

 -- Property of gnue_parameter: gnue_length number(6)
     The length of the property. Only relevant if `gnue_type' is
     "string" or "number".

 -- Property of gnue_parameter: gnue_scale number(4)
     Only relevant if `gnue_type' is "number", in which case it defines
     the number of fractional digits, while `gnue_length' defines the
     total number of digits.

 -- Property of gnue_parameter: gnue_comment string(70)
     Arbitary text explaining the purpose of the parameter.

4.6 `gnue_label'
================

 -- Property of gnue_label: gnue_property gnue_property
     The name attribute of the property this label is attached to.

 -- Property of gnue_label: gnue_procedure gnue_procedure
     The name attribute of the procedure this label is attached to.

 -- Property of gnue_label: gnue_language string(5)
     The language in which the labels are defined.

 -- Property of gnue_label: gnue_page string(35)

 -- Property of gnue_label: gnue_label string(35)
     The label's text to display in the given language.

 -- Property of gnue_label: gnue_position number(6)
     Designates the Y order of the label and the property/procedure it
     refers to.

 -- Property of gnue_label: gnue_search number(6)
     If present, it makes the property referred a dropdown search field
     in a referring form.

 -- Property of gnue_label: gnue_info number(6)
     If present, it makes the property referred a label info field in
     pair with the search field in a referring form.

4.7 `gnue_message'
==================

 -- Property of gnue_message: gnue_module gnue_module
     The module that defines the message.

 -- Property of gnue_message: gnue_language string(5)
     The language in which the messages are defined.

 -- Property of gnue_message: gnue_name string(35)

 -- Property of gnue_message: gnue_text string

Appendix A Data Type and Function Index
***************************************

boolean:                                       See 2.         (line  47)
call on session:                               See 3.3.       (line 201)
commit on session:                             See 3.1.       (line  97)
count on list:                                 See 3.2.       (line 132)
delete on session:                             See 3.3.       (line 191)
fetch on list:                                 See 3.2.       (line 135)
integer:                                       See 2.         (line  51)
load on session:                               See 3.3.       (line 153)
open:                                          See 3.1.       (line  89)
request on session:                            See 3.2.       (line 115)
rollback on session:                           See 3.1.       (line 104)
store on session:                              See 3.3.       (line 170)
string:                                        See 2.         (line  56)
stringlist:                                    See 2.         (line  60)
stringtable:                                   See 2.         (line  64)
void:                                          See 2.         (line  43)
