The GNU Enterprise Application Server ************************************* Application Programmer's Interface Edition 0.5.2, 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)