[gnue] r7070 - in trunk/gnue-appserver: . doc/devguide src/language

[reinhard]

Author: reinhard
Date: 2005-02-28 07:35:22 -0600 (Mon, 28 Feb 2005)
New Revision: 7070

Modified:
   trunk/gnue-appserver/BUGS
   trunk/gnue-appserver/doc/devguide/03-basicdb.texi
   trunk/gnue-appserver/doc/devguide/06-procedures.texi
   trunk/gnue-appserver/doc/devguide/devguide.texi
   trunk/gnue-appserver/src/language/ObjectList.py
Log:
More work on documentation.


Modified: trunk/gnue-appserver/BUGS
===================================================================
--- trunk/gnue-appserver/BUGS   2005-02-27 07:30:40 UTC (rev 7069)
+++ trunk/gnue-appserver/BUGS   2005-02-28 13:35:22 UTC (rev 7070)
@@ -25,3 +25,6 @@
   multiple new instances per item, gets slower with every iteration-step.
 
 * gnue-gsdgen shouldn't rescan the module path
+
+* session.get () from the language interface does not properly raise an
+  exception when the requested instance does not exist.

Modified: trunk/gnue-appserver/doc/devguide/03-basicdb.texi
===================================================================
--- trunk/gnue-appserver/doc/devguide/03-basicdb.texi   2005-02-27 07:30:40 UTC 
(rev 7069)
+++ trunk/gnue-appserver/doc/devguide/03-basicdb.texi   2005-02-28 13:35:22 UTC 
(rev 7070)
@@ -206,3 +206,34 @@
 <property name="foo" type="string" length="35" />
 <property name="bar" type="number" length="12" scale="2" />
 @end example
+
address@hidden 
----------------------------------------------------------------------------
+
address@hidden Implicit properties
+
+For every class, GNU Enterprise implicitly creates a few properties:
+
address@hidden @code
address@hidden gnue_id
+is a non-changeable string property with 32 characters. GNU Enterprise
+automatically assignes a unique random string for every new instance that is
+created.  The value of gnue_id will remain constant for a given instance until
+it is deleted.  The underlying column in the database table, also called
+gnue_id, serves as the primary key for the table.
+
address@hidden gnue_createdate
+holds the date and time of the creation of an instance.
+
address@hidden gnue_createuser
+holds the user name that created the instance, in case GNU Enterprise is
+configured for user authentication.
+
address@hidden gnue_modifydate
+holds the date and time of the last modification to this instance.  It can be
+empty if an instance hast just been created and is still in virgin state.
+
address@hidden gnue_modifyuser
+holds the user name that did the last modification to this instance, in case
+GNU Enterprise is configured for user authentication.  It can be empty if an
+instance hast just been created and is still in virgin state.
address@hidden table

Modified: trunk/gnue-appserver/doc/devguide/06-procedures.texi
===================================================================
--- trunk/gnue-appserver/doc/devguide/06-procedures.texi        2005-02-27 
07:30:40 UTC (rev 7069)
+++ trunk/gnue-appserver/doc/devguide/06-procedures.texi        2005-02-28 
13:35:22 UTC (rev 7070)
@@ -164,6 +164,11 @@
 external programs.  It is strongly advised, however, that the code in
 calcluated properties does not have any side effects.
 
+The type of calculated properties (which is effectively the type of the return
+value of the assigned procedure code) can be any of the basic data types
+(string, number, boolean, date, time, and datetime).  It is not possible to
+pass object references as the result of calculated properties.
+
 Whenever a calculated property with the name @samp{foo} is defined, GNU
 Enterprise defines a procedure with the name @samp{getfoo}, and every access to
 the property @samp{foo} is automatically and transparenty translated into a
@@ -183,16 +188,27 @@
 case).  These procedures may or may not have parameters, and they may or may
 not have return values, and they may contain virtually anything.
 
address@hidden Defining Parameters
+The return value of other procedures (the type of the procedure) can be any of
+the basic data types (string, number, boolean, date, time, and datetime).  It
+is not possible to pass object references as the result of procedures.
 
-TBD
address@hidden Defining Parameters And The Return Value
 
+Parameters are declared in the gcd file by adding one or more
address@hidden<parameter>} tags within the @code{<procedure>} tag, with 
@code{name},
address@hidden, @code{length}, @code{scale}, and @code{comment} attributes just
+like you would use them for properties.
+
+The @code{type}, @code{length}, and @code{scale} attributes are also allowed
+directly in the @code{<procedure>} tag, where they declare the return type of
+the procedure.
+
 @subsection Calling Procedures From Other Procedures
 
 Within procedure code (also within the code of triggers and calculated fields),
 all defined procedures are available as methods of the respective objects.
 
-In Python, parameters must be given as keyword arguments.
+In Python, all parameters must be given as keyword arguments.
 
 The following examples show a few ways of calling procedures:
 
@@ -205,10 +221,270 @@
 
 @subsection Calling Procedures From Forms
 
-TBD
+If you you author your own form definition (.gfd) file, you can call a
+procedure of a class if that class in form trigger code.  You must have a block
+assigned to that class.
 
+To call a procedure, call the function @code{call} of the block and pass two
+parameters: the first one is the (fully qualified) procedure name to call, and
+the second one is a dictionary with @address@hidden@samp{parametername}:
address@hidden@}} pairs.
+
 @c ----------------------------------------------------------------------------
 
 @section Global Functions And Variables Available In Procedures
 
-TBD: self, session, abort
+In the code of any procedure, you can use these variables and global functions:
+
address@hidden self
+
+The variable @code{self} allows access to the object instance the procedure is
+called for.  @code{self} is usable just like any normal Python object: you can
+access (read and write) properties of the object as @samp{self.propertyname}
+and you can call procedures like object methods as
address@hidden@ (parameters)}.
+
+Reference properties virtually hold the objects themselves, so you can do
+things like
+
address@hidden
+c = self.customer
+self.custname = c.name
+c.lastinvoice = self
address@hidden example
+
address@hidden
+(where self.customer and c.lastinvoice would be reference properties)
+
+To clear the value of a property (set it to NULL in database speak), you can
+assign it the value @code{None}.  Accessing a property that is not set (or has
+been cleared this way) also yields @code{None} in case it's of one of the basic
+types.
+
+However, unset reference properties yield a special object called
address@hidden that simply returns @code{None} on access to any property.
+This way, you accessing for example @code{self.customer.name} for an object
+where the customer property is not set returns @code{None} instead of
+generating an exception.
+
+Because of this, you may not test reference properties like @code{if
+self.customer is None:}, use @code{if self.customer:} instead.
+
+Apart from all properties and procedures defined in the class definition or
+created implicitly by GNU Enterprise (like @code{gnue_id}), you can call the
address@hidden@ ()} method of an object to delete it.
+
address@hidden session
+
+The variable @code{session} holds an object representing the current connection
+to the GNU Enterprise Application Server.  It has a few handy methods you can
+use in your procedures:
+
address@hidden session new (@var{classname})
+Creates and returns a new instance of the class @var{classname}.
address@hidden defmethod
+
address@hidden session get (@var{classname}, @var{objectId})
+Returns the existing instance of the class @var{classname} that has a
address@hidden of @var{objectId}. If no such instance exists, an exception is
+raised.
address@hidden defmethod
+
address@hidden session find (@var{classname}, conditions = @var{conditions}, 
sortorder = @var{sortorder}, properties = @var{properties})
+Returns a list of those instances of class @var{classname} that match the
address@hidden, ordered by @var{sortorder}.
+
+The conditions can be given as a dictionary of propertyname/value pairs (in
+which case all the properties must have exactly the given value to match) or as
+a complex condition in prefix notation.  The default is to return all instances
+of the given class.
+
+The sort order is a list of sort items. An item can be either a simple string
+(interpreted as a property name) or a dictionary with the keys @code{'name'}
+(required, the property name), @code{'descending'} (optional, @code{True}
+indicates descending sort order), and @code{'ignorecase'} (optional,
address@hidden indicates the sort should be case insensitive).  The default is 
to
+sort by the @code{gnue_id} property (which is pretty useless in most cases).
+
+The last optional parameter is a list of property names that should be
+prefetched from the database.  Of course @emph{any} property of the objects can
+be accessed at @emph{any} time, but properties given in this list are included
+in the original database query and cached by GNU Enterprise, so subsequent
+access to prefetched properties is much faster.
+
+The result of this function is an object that behaves very much like it is a
+list of the found objects, most notably it supports the following operations:
+
address@hidden
address@hidden
+testing the truth value to find out whether the list contains any items at all
+
address@hidden
+requesting the length of the list with the @code{len (@var{list})} function
+(However, be aware that this can be a very time consuming pocess, especially if
+the condition contained calculated fields or @code{exists} operations)
+
address@hidden
+accessing the @var{n}th item in the list with @var{list} address@hidden
+
address@hidden
+accessing the @var{n}th to last item in the list with @var{list} 
address@hidden (as
+this involves finding out the length of the list, it can also be a time
+consuming process under some circumstances)
+
address@hidden
+iterating through the list with a @code{for} loop
address@hidden itemize
+
+The returned list is immutable.  The items of the list can be changed, but it
+is not possible to add items to the list or remove items from the list.
+
+Changing any item of the list in a way that it would not any more match the
+condition originally given to @code{find ()} does not remove the item from the
+list.  Likewise, changing an object that is not a member of the list in a way
+that it now would match the condition doesn't add it to the list, neither does
+creating a new instance.  You have to call @code{find ()} again to get a
+current list of matching objects.
address@hidden defmethod
+
address@hidden abort
+
+This function aborts the current operation.  It takes a single parameter, which
+is a string holding an error message to display to the user.
+
address@hidden 
----------------------------------------------------------------------------
+
address@hidden Complex Queries Using Condition Trees
+
+The @code{find} function introduced above can do queries of all kinds using a
+powerful and flexible construction called the @dfn{condition tree}.
+
+Condition trees are generally constructed as a sequence where the first element
+is an operation and the following elements are the arguments.  For many
+operations, one or several of the arguments can again be an operation, thus
+building up a tree of operations.
+
+The following operations are possible:
+
address@hidden @code
address@hidden 'Field'
+Takes a single argument with a property name and evaluates to the value of this
+property.
+
address@hidden 'Const'
+Takes a single argument with a constant value and evaluates to this value given
+in the argument.
+
address@hidden 'and'
+Takes an arbitary number of arguments of boolean type and evaluates to
address@hidden if all arguments are @code{True} and to @code{False} otherwise.
+
address@hidden 'or'
+Takes an arbitary number of arguments of boolean type and evaluates to
address@hidden if at least one of the arguments is @code{True} and to 
@code{False}
+otherwise.
+
address@hidden 'not'
+Takes exactly one argument of boolean type and evaluates to @code{True} if the
+argument is @code{False} and vice versa.
+
address@hidden 'add'
+Takes an arbitary number of arguments of numeric type and evaluates to the sum
+of the arguments.
+
address@hidden 'sub'
+Takes an arbitary number of arguments of numeric type and evaluates to the
+first argument minus the sum of the rest of the arguments.
+
address@hidden 'mul'
+Takes an arbitary number of arguments of numeric type and evaluates to the
+product of the rest of the arguments.
+
address@hidden 'div'
+Takes an arbitary number of arguments of numeric type and evaluates to the
+first argument divided by the product of the rest of the arguments.
+
address@hidden 'negate'
+Takes a single argument of numeric type and evaluates to the negation of the
+argument.
+
address@hidden 'eq'
+Takes exactly two arguments of any type and evaluates to @code{True} if both
+arguments are equal and to @code{False} otherwise.  If the arguments are of
+different types, they are tried to convert to the same type, where strings are
+converted to booleans, numbers, or date/time values, and booleans are converted
+to numbers.  If such a conversion fails, an exception is raised.
+
address@hidden 'ne'
+Takes exactly two arguments of any type and evaluates to @code{False} if both
+arguments are equal and to @code{True} otherwise. The same conversions as for
address@hidden'eq'} apply.
+
address@hidden 'gt'
+Takes exactly two arguments of any type and evaluates to @code{True} if the
+first argument is greater than the second one.  If the arguments are strings,
+"greater" means "sorting after".  If the arguments are date/time values,
+"greater" means "later".  If the arguments are of different types, the usual
+conversions apply.
+
address@hidden 'ge'
+Takes exactly two arguments of any type and evaluates to @code{True} if the
+first argument is greater than the second one or equal.
+
address@hidden 'lt'
+Takes exactly two arguments of any type and evaluates to @code{True} if the
+first argument is lower than the second one.
+
address@hidden 'le'
+Takes exactly two arguments of any type and evaluates to @code{True} if the
+first argument is lower than the second one or equal.
+
address@hidden 'like'
+Takes exactly two arguments, where the first is a string value to test, and the
+second is a string to match against.  The second string can contain the
+following wildcards: @code{?} matches any character, and @code{%} matches any
+number (including zero) of characters.  This operation evaluates to @code{True}
+if the strings match and to @code{False} if they don't.
+
address@hidden 'notline'
+Takes exactly two arguments and is the logical inversion of @code{'like'}.
+
address@hidden 'between'
+Takes exactly three arguments and evaluates to @code{True} if the first
+argument is greater or equal than the second and lower or equal than the third
+one, and @code{False} otherwise.
+
address@hidden 'notbetween'
+Takes exactly three arguments and evaluates to @code{True} if the first
+argument is either lower than the second one or greater than the third one, and
address@hidden otherwise.
+
address@hidden 'null'
+Takes a single argument and evaluates to @code{True} if it is None (NULL) and
+to @code{False} otherwise.
+
address@hidden 'notnull'
+Takes a single argument and evaluates to @code{False} if it is None (NULL) and
+to @code{True} otherwise.
+
address@hidden 'upper'
+Takes a single argument of type string and evaluates to the same string with
+all characters converted to uppercase.
+
address@hidden 'lower'
+Takes a single argument of type string and evaluates to the same string with
+all characters converted to lowercase.
+
address@hidden 'exist'
+Takes at least three arguments, where the first argument is a classname, the
+second argument is the name of a property in the current class and the third
+argument is the name of a property in the class given in the first argument.
+The rest of the arguments can be conditions to apply to the class given in the
+first argument.  The @code{'exists'} operation returns @code{True} if and only
+if there exists at least one instance in the class given in argument 1 that
+fulfills all the conditions given in arguments 4ff and where the property given
+in argument 3 matches the property of the current class given in argument 2.  A
+typical usage for this condition is to test for an instance whether it is
+referenced by instances of another class (in which case the third argument
+would usually be @code{'gnue_id'}).
address@hidden table

Modified: trunk/gnue-appserver/doc/devguide/devguide.texi
===================================================================
--- trunk/gnue-appserver/doc/devguide/devguide.texi     2005-02-27 07:30:40 UTC 
(rev 7069)
+++ trunk/gnue-appserver/doc/devguide/devguide.texi     2005-02-28 13:35:22 UTC 
(rev 7070)
@@ -87,5 +87,4 @@
 @include 05-references.texi
 @node Procedures,        ,                  References,        Top
 @include 06-procedures.texi
-
 @bye

Modified: trunk/gnue-appserver/src/language/ObjectList.py
===================================================================
--- trunk/gnue-appserver/src/language/ObjectList.py     2005-02-27 07:30:40 UTC 
(rev 7069)
+++ trunk/gnue-appserver/src/language/ObjectList.py     2005-02-28 13:35:22 UTC 
(rev 7070)
@@ -128,10 +128,6 @@
     # performance for fetching larger lists
     self.__cacheStep *= 2
 
-    # fix for gnue-common 0.5.1 release (will be removed for later releases 
-    # of gnue-common)
-    self.__length = len (self.__list)
-
     # return number of updated rows
     return len (rset)