gnue/appserver/doc/whitepaper version.texi whit...

[Reinhard Mueller]

CVSROOT:        /cvsroot/gnue
Module name:    gnue
Changes by:     Reinhard Mueller <address@hidden>       02/05/19 15:02:45

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

Log message:
        Added chapter "Features".

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

Patches:
Index: gnue/appserver/doc/whitepaper/version.texi
diff -c gnue/appserver/doc/whitepaper/version.texi:1.2 
gnue/appserver/doc/whitepaper/version.texi:1.3
*** gnue/appserver/doc/whitepaper/version.texi:1.2      Sun May 19 12:47:35 2002
--- gnue/appserver/doc/whitepaper/version.texi  Sun May 19 15:02:45 2002
***************
*** 1,2 ****
  @set UPDATED 2002-05-19
! @set EDITION 0.0.4
--- 1,2 ----
  @set UPDATED 2002-05-19
! @set EDITION 0.0.5
Index: gnue/appserver/doc/whitepaper/whitepaper.texi
diff -c gnue/appserver/doc/whitepaper/whitepaper.texi:1.2 
gnue/appserver/doc/whitepaper/whitepaper.texi:1.3
*** gnue/appserver/doc/whitepaper/whitepaper.texi:1.2   Sun May 19 12:47:35 2002
--- gnue/appserver/doc/whitepaper/whitepaper.texi       Sun May 19 15:02:45 2002
***************
*** 120,175 ****
  
  @chapter Features
  
! @section Theory of Operation
  
! For easy understanding, here is the basic way the Application Server
! will provide data:
! 
! @enumerate
! @item
! The client requests an object from the app server through the Remote Protocol
! Adapter.
  
! @item
! The Application Server checks if the requested class name is
! valid (according to the given definitions, i.e. via XML) 
! by looking up the class definition in the Object Repository.
  
! @item
! If it's valid, the Object Access Translator translates a class name
! into a table name. This will include adding a prefix to enable different
! application modules to have their own namespace.
  
! @item
! Then the Application Server passes the database request to the Data Interface
! to actually get the data.
! @end enumerate
  
! @section Practical Use
  
! The interface against the front end will be designed with understandability,
! simplicity and usability in mind.
! 
! The following objects will appear:
  
  @table @dfn
! @item List of instances:
! This is a sorted collection of business object instances of a single class.
! Example: All customers in Arizona, ordered by name.
! There will be methods for iterating through the list and get the individual
! instances.
! 
! @item Instance:
! This is a single business object instance, for example a specific customer.
! There will be methods for reading and writing values of fields of the
! instances, as well as for calling methods for the instance.
! 
! A field can be a simple value (e.g. the name, the address, the turnover),
! an instance (e.g. the instance of the "customer group" class that the
! customer belongs to) or even a list of instances (e.g. all invoices for
! the customer).
  @end table
  
  @c 
============================================================================
  @node Implementation,                            Building Blocks, Features, 
Top
  @c 
============================================================================
--- 120,278 ----
  
  @chapter Features
  
! @section Business Objects
  
! GEAS allows definition of data entities (for example name and address of a
! customer) and of program code to perform on such entities (for example how to
! build the address line from country, zipcode and city).
  
! The combination of a data entity with all code functions that can be performed
! on the entity is called a @dfn{business object}.
  
! GEAS lets the user define @dfn{classes} of business objects, where the class
! definition states the data elements (called @dfn{fields}) objects of this 
class
! will consist of as well as the functions that will be available to act upon
! the objects (called @dfn{methods}).
  
! The specific incarnation of a business object (for example a specific 
customer)
! is called a business object @dfn{instance}.
  
! @section Fields
  
! GEAS will provide the following field types:
  
  @table @dfn
! @item Basic fields
! contain most of the actual information, in the basic field types @dfn{string},
! @dfn{number}, @dfn{datetime}, and @dfn{boolean}. Examples could contain
! customer name, item price, invoice date, and invoice payment status.
! 
! @item Compound fields
! are a means for combining fields that logically belong together and appear
! repeatedly in the same combination. Compound fields can be built from fields
! of any type, not only of basic fields. An example could be a monetary value
! consisting of the amount and the currency.
! 
! @item Reference fields
! point to another object and declare a relation between two objects. The value
! of a reference field is another object. Examples include the customer of an
! invoice or the preferred vendor of an item.
! 
! @item List fields
! point to lists of objects and declare a relation between these objects. The
! value of a list field is a list of objects of a defined class, where all
! objects in the list will be of the same class. Examples include all line items
! of an invoice, or all contact persons of a customer.
! 
! @item Calculated fields
! contain information that is generated by GEAS out of other fields. Calculated
! fields are generally read-only. An example could be the total value of an
! invoice item (calculated from price * pieces) or the total value of an
! invoice (calculated from all total item values).
! 
! @item Indirect fields
! are fields of a referenced object and can be accessed as if they were fields
! of the current object. Examples could include the name of the customer of the
! invoice, or the name of the preferred vendor of the item of an invoice line
! item.
  @end table
  
+ @section Methods
+ 
+ A method is code performed on an object. Methods can have parameters of any
+ field type (string, number, reference, etc.). Every method has the paramter
+ @dfn{self}, that is the object instance to operate on, as a parameter.
+ 
+ @section Modules
+ 
+ Modules define namespaces for classes, fields and methods. When module A
+ defines a class and some fields and methods for the class, module B can
+ extend the class with new fields. Another module C can independently
+ extend the class, without taking care about not using the same field names
+ as module B, because all modules have their own namespace.
+ 
+ @section Qualified class, field and method names
+ 
+ @emph{Note: This section is absolutely subject to discussion. We are looking 
for
+ a good and understandable syntax for fully qualified names.}
+ 
+ Class, field and method names can be preceded by a module name to override
+ the current module context. In this case, the module name is separated by a
+ colon (:).
+ 
+ Compound field names can be followed with a dot (.) and a member name of the
+ compound.
+ 
+ Reference field names can be followed with a dot (.) and a field name of the
+ referenced object to form an indirect field.
+ 
+ Example:
+ 
+ Module "cust" defines a class "customer". Module "sales" defines a class
+ "invoice_head" and a class "invoice_item". Module "base" defines a class
+ "item".
+ 
+ Then, @code{cust:customer} is the fully referenced class name for the
+ customer class, and @code{sales:invoice_head} is the fully referenced class
+ name for the invoice_head class.
+ 
+ Now, let module "cust" define the fields "name" and "address" for the
+ customer class, where address is a compound field consisting of "street"
+ and "city".
+ 
+ The following are now valid field references of a customer object:
+ 
+ @code{name} or @code{cust:name} is a base field.
+ 
+ @code{address} or @code{cust:address} is a compound field.
+ 
+ @code{address.street} or @code{cust:address.street} is a compound member 
field.
+ 
+ Now, the module "sales" extends the customer class by a field "last_invoice"
+ which is a reference to an invoice_head object.
+ 
+ @code{sales:last_invoice} is a reference containing an invoice_head object.
+ 
+ If module "sales" defines the fields "number" and "items" in "invoice_header",
+ then
+ 
+ @code{sales:last_invoice.number} is an indirect field and
+ 
+ @code{sales:last_invoice.items} is an indirect field, which is a list field.
+ 
+ And if yet another module "acct" extends the invoice_header class by a
+ field "paid", then
+ 
+ @code{sales:last_invoice.acct:paid} could be a boolean field that tells you
+ whether the customer has paid his last invoice or not, and you would access
+ it just as easy as the "name" field. However, this field would only be
+ available if all three modules "cust", "sales", and "acct" are installed.
+ 
+ @section Triggers
+ 
+ @dfn{Triggers} are methods that are automatically called upon occurance of
+ defined @dfn{events}, for example on every change of a specific field,
+ or before a commit of a changed object.
+ 
+ Triggers are always methods of the object where the event occurs. Because
+ every module can extend any class with a method of arbitary name, calling
+ of triggers could be automated by method name.
+ 
+ Example:
+ 
+ The cust module, which defines the customer object, defines a method
+ "OnChangeName", whose fully qualified name is of course
+ @code{cust:OnChangeName}.
+ 
+ The sales module could extend the customer class by a method and also call
+ this method "OnChangeName", because the fully qualified name of this method
+ will be @code{sales:OnChangeName} and therefore different from the other
+ method.
+ 
+ If the field "Name" is changed in a customer object, GEAS would call both
+ methods because both are named "OnChangeName". The order of the method calls
+ would be unpredictable.
+ 
  @c 
============================================================================
  @node Implementation,                            Building Blocks, Features, 
Top
  @c 
============================================================================
***************
*** 212,217 ****
--- 315,345 ----
  
  @item Remote Protocol Adapter:
  @end table
+ 
+ @section Theory of Operation
+ 
+ For easy understanding, here is the basic way the Application Server
+ will provide data:
+ 
+ @enumerate
+ @item
+ The client requests an object from the app server through the Remote Protocol
+ Adapter.
+ 
+ @item
+ The Application Server checks if the requested class name is
+ valid (according to the given definitions, i.e. via XML) 
+ by looking up the class definition in the Object Repository.
+ 
+ @item
+ If it's valid, the Object Access Translator translates a class name
+ into a table name. This will include adding a prefix to enable different
+ application modules to have their own namespace.
+ 
+ @item
+ Then the Application Server passes the database request to the Data Interface
+ to actually get the data.
+ @end enumerate
  
  @c 
----------------------------------------------------------------------------
  @node Data Interface,          Methods Adapter, Building Blocks, 
Implementation