gnue/geas doc/faq.txt lib/classdefs/classdata_d...

[Treshna Enterprises]

CVSROOT:        /cvs
Module name:    gnue
Changes by:     Treshna Enterprises <address@hidden>    01/06/27 15:28:39

Modified files:
        geas/doc       : faq.txt 
        geas/lib/classdefs: classdata_database.c 
        geas/src/objectcache: objectcache.c 

Log message:
        edited docs
        bugfix: g_assert() removed, as a NULL was a valid input
        hack: now cache count will ignore geas internal classes (ie, if you
        don't free resources, the debugging output is now not very helpful)

CVSWeb URLs:
http://savannah.gnu.org/cgi-bin/viewcvs/gnue/geas/doc/faq.txt.diff?cvsroot=OldCVS&tr1=1.9&tr2=1.10&r1=text&r2=text
http://savannah.gnu.org/cgi-bin/viewcvs/gnue/geas/lib/classdefs/classdata_database.c.diff?cvsroot=OldCVS&tr1=1.19&tr2=1.20&r1=text&r2=text
http://savannah.gnu.org/cgi-bin/viewcvs/gnue/geas/src/objectcache/objectcache.c.diff?cvsroot=OldCVS&tr1=1.56&tr2=1.57&r1=text&r2=text

Patches:
Index: gnue/geas/doc/faq.txt
diff -u gnue/geas/doc/faq.txt:1.9 gnue/geas/doc/faq.txt:1.10
--- gnue/geas/doc/faq.txt:1.9   Sat Jun  9 09:31:15 2001
+++ gnue/geas/doc/faq.txt       Wed Jun 27 15:28:39 2001
@@ -7,7 +7,7 @@
 
  1      General GEAS questions
  1.1        What is GEAS?
- 1.2        How do I compile GEAS? [edited 2001-04-23]
+ 1.2        How do I compile GEAS?
  1.2.1      What is libuuid?
  1.3        Geas is running slowly.
  1.4        Can I use GEAS to develop web applications?
@@ -77,7 +77,7 @@
 
 0.2) Version
 
-  Last modified: $Id: faq.txt,v 1.9 2001/06/09 16:31:15 reinhard Exp $
+  Last modified: $Id: faq.txt,v 1.10 2001/06/27 22:28:39 treshna Exp $
 
 
 0.3) Copyright
@@ -115,10 +115,10 @@
 1.2) How do I compile GEAS?
 
     Code is available in CVS, and released versions are available as a tarball
-(see http://www.gnue.org/ and follow the 'Downloads' link.) Alternatively,
-the latest code can be retrrieved from CVS, using instructions also found on
-the GNUe web site. The file doc/INSTALL provides reasonably detailed
-instructions.
+(see http://www.gnuenterprise.org/ and follow the 'Downloads' link.)
+Alternatively, the latest code can be retrrieved from CVS, using
+instructions also found on the GNUe web site. The file doc/INSTALL
+provides reasonably detailed instructions.
 
     Run 'autogen.sh' (or 'configure' if autogen.sh is not present) with the
 appropriate arguments to enable/disable features. You must use --with-mysql
@@ -126,7 +126,7 @@
 
     This should warn you of any required libraries etc, which must be
 installed. (If you find something is missing that is not detected by the
-configure script, please email address@hidden with a description of the
+configure script, please email address@hidden with a description of the
 problem, including your OS and which version you are running.)
 
     Type 'make' to compile the server.
@@ -172,11 +172,12 @@
 1.4.1) I was hoping for more detail. How?
 
     GEAS itself provides no user interface at all. It is possible to develop
-a client in a range of languages (eg: Python, C, Java) that can run as
+a client in a range of languages (eg: Python, C, Java, PHP) that can run as
 cgi-bin programs, and use HTML as the output display. Java applets can also
 talk to GEAS, but the restrictions on what machines an applet can talk to
 may limit this in specific installations. Also, the appropriate classes
-(in the package org.omg. must be available on the client machine.)
+(in the package org.omg. must be available on the client machine, and
+these are not included in some earlier versions of the JRE.)
 
 1.5) What is the meaning of life?
 
@@ -253,7 +254,8 @@
 security system. As this prints information such as passwords, it can reduce
 security. When security debugging is turned on, the user must respond with
 'yes' to a warning message before the server will be activated. (This helps
-prevent a server from being used with this security hole accidentally.)
+prevent a server from being used with this potential security hole
+accidentally.)
 
 
 2.1.2) Run time options
@@ -349,8 +351,9 @@
 
 Running 'ping hostname' with the hostname _exactly_ as reported by
 ior-decode will confirm that the hostname is resolving correctly, and that
-there is a working network connection. (eg: ping geas.treshna.com will
-reveal that there is no such machine avaialble on the network.)
+there is a working network connection. (eg: ping
+geas.gnuenterprise.com will reveal that there is no such machine
+avaialble on the network.)
 
 If the client and server both use ORBit, and both run on the same machine,
 ensure that the indicated socket path can be accessed by both the client
@@ -359,8 +362,11 @@
 
 2.2.4) GEAS complains about not finding a database
 
-    The configuration file being read must define at least one database with
-the 'active' setting set to 'true'.
+    The configuration file being read must define one and only one
+database with the 'active' setting set to 'true'. (More are
+technically possible, but only the first one marked as active will
+ever be used.) (Of course editing the configuration file and
+restarting the server will allow another database to be selected.)
 
 
 2.2.5) GEAS can't connect to a database
@@ -368,7 +374,7 @@
     The first active database will be used: ie, if more than one database in
 geas.conf has 'active' set to 'true' the first one will be used. If it is
 not available, GEAS will not be able to work. To fix this, ensure that only
-available databases are active.
+an available database is active.
 
     If this is not the case, there is most likely a problem with the
 database configuration, which will need to be fixed.
@@ -387,12 +393,12 @@
 relationships to be constructed by performing a JOIN when executing a query.
 
    SQL does, however, support relational integrity, which GEAS has does not
-yet do - but this will be implemented in the future.
+yet do - but this should be implemented in the future.
 
 
 3.2) How can I use an existing database?
 
-Code is being developed to enable GEAS to use existing databsae tables. This
+Code is being developed to enable GEAS to use existing database tables. This
 has not been completed as yet.
 
 
@@ -459,7 +465,8 @@
           old a person would be, given those two inputs.
 
            The only operation that may be performed on a class is to create
-          a new instance.
+          a new instance. (Of course, some languages allow classes to
+          have static members, but GEAS does not support this.)
 
 
   Object : An object is a specific instance of a class. Class 'person'
@@ -508,10 +515,11 @@
 
 A person is not an address. A person has an address. Using 'has a' allows a
 person to have a residential address and a mailing address. Using 'is a'
-requires 'residential address' and 'mailing address' to be different classes
-with different fieldnames.
+requires 'residential address' and 'mailing address' to be different
+classes.
 
 
+
 5.2.2.1) So how do I do 'has a' in GCD files?
 
 Step 1: Create a data type that an object may posess.
@@ -528,13 +536,17 @@
     mailing.street;
     mailing.number
 
+(On second thoughts, this may have been a less than perfect idea. It
+may change in the future, to allow a class to be used as a member of
+another class, or in relationships.)
+
 
 5.2.2) Isn't multiple inheritance bad?
 
 No. Every language feature can be used incorrectly. This is an argument for
 only allowing competent programmers to write code. Removing every feature
 that is hard to use would in fact require all programming languages to be
-banned.
+banned. (Some people may argue that this would be a good thing.  :)
 
 
 5.3) How do I make a new class?
@@ -607,6 +619,9 @@
 how I learned enough CORBA to write GEAS. A solid understanding of OOP will,
 of course, be useful as well.
 
+    (Once the GNUe specific CORBA replacement is complete, there will
+be no need to know about CORBA at all  :)
+
 
 6.2) What languages and ORBs can be used?
 
@@ -729,7 +744,46 @@
 6.4) Exception handling
 
 GEAS does not use return values for indicating errors. Instead, the CORBA
-exception mechanism, which is mapped to a langauge specific 
+exception mechanism is used, which is mapped to a language specific
+implementation. For Python, C++ and Java, the native exception
+handling system is used. In C, an extra data structure is used, and
+all CORBA functions must be passed a pointer to this structure, for
+storing exception information.
+
+When raising an exception in a method, the return value is ignored.
+Functions that return a pointer should return NULL, and other
+functions may return any arbitrary value.
+
+
+Example:
+
+/* setup */
+CORBA_Environment *ev = g_new0( CORBA_Environment , 1 );
+CORBA_exception_init( ev ); /* ORBit specific */
+
+/* function call */
+GEAS_DataObject_getField( obj , "fieldname" , ev  );
+
+/* test for exception */
+if( ev->_major != CORBA_NO_EXCEPTION )
+{
+    /* handle exception - function in GEAS src code (src/exceptions.c) */
+    switch( get_user_exception_id(ev) )
+    {
+        case GEAS_EXCEPTIONID_UnknownField:
+           /* handle this exception */
+           break;
+        case GEAS_EXCEPTIONID_ServerError:
+           /* handle this exception */
+           break;
+    }
+}
+
+/* create a new exception (GEAS function, also from src/exceptions.c) */
+make_ServerError_exception( ev , "Just a dummy thing (%d)" , integer_var );
+
+/* done */
+CORBA_exception_free( ev ); /* ORBit specific */
 
 
 6.4.1) Python
@@ -739,16 +793,18 @@
 Example:
 
   try:
-      # code that throws an exception
-  catch GEAS.ServerError,ex:
-      # exception handling code
+      obj = con.newObject( "non-existant class" );
+  catch GEAS.UnknownClass,ex:
+      print "That class was not known (", ex.detail ,")"
 
 
 6.4.2) Java
 
 As for Python, Java's native exception handling mechanism is used. The
 significant difference is that Java requires all possible exceptions to be
-caught.
+caught - if a method is marked in the IDL file as throwing an
+exception, that exception must be handled, or a compile time error
+will occur.
 
 
 6.4.3) C
Index: gnue/geas/lib/classdefs/classdata_database.c
diff -u gnue/geas/lib/classdefs/classdata_database.c:1.19 
gnue/geas/lib/classdefs/classdata_database.c:1.20
--- gnue/geas/lib/classdefs/classdata_database.c:1.19   Wed Jun 27 11:46:57 2001
+++ gnue/geas/lib/classdefs/classdata_database.c        Wed Jun 27 15:28:39 2001
@@ -19,7 +19,7 @@
    along with this program; if not, write to the Free Software Foundation,
    Inc., 59 Temple Place - Suite 330, Boston, MA 02111-1307, USA.  
  
-   $Id: classdata_database.c,v 1.19 2001/06/27 18:46:57 ntiffin Exp $
+   $Id: classdata_database.c,v 1.20 2001/06/27 22:28:39 treshna Exp $
 */
 
 /* generally speaking, do not include this, except in classdata.h */
@@ -429,9 +429,8 @@
 DBchange *
 find_named_change (GList * l, char *name)
 {
-  /* g_assert (l != NULL); */
   g_assert (name != NULL);
-  while (l)
+  while (l) /* if l == NULL, then return 'not in list' value */
     {
       if (g_strcasecmp (((DBchange *) l->data)->name, name) == 0)
         {
Index: gnue/geas/src/objectcache/objectcache.c
diff -u gnue/geas/src/objectcache/objectcache.c:1.56 
gnue/geas/src/objectcache/objectcache.c:1.57
--- gnue/geas/src/objectcache/objectcache.c:1.56        Mon Jun 25 20:01:26 2001
+++ gnue/geas/src/objectcache/objectcache.c     Wed Jun 27 15:28:39 2001
@@ -19,7 +19,7 @@
    along with this program; if not, write to the Free Software Foundation,
    Inc., 59 Temple Place - Suite 330, Boston, MA 02111-1307, USA.  
    
-   $Id: objectcache.c,v 1.56 2001/06/26 03:01:26 treshna Exp $
+   $Id: objectcache.c,v 1.57 2001/06/27 22:28:39 treshna Exp $
 */
 
 #include "config.h"
@@ -54,14 +54,15 @@
 static GHashTable *cachedata = NULL;
 static GHashTable *indexes = NULL;
 static unsigned int objectcache_count = 0;
+static unsigned int hack_count = 0;
 static guint32 cache_max_size = 0;
 static GList *flushable = NULL;
 
 void
 oc_print_stats( void )
 {
-    printf( "Object Cache: %d entries   %d flushable\n" , objectcache_count ,
-           g_list_length(flushable) );
+    printf( "Object Cache: %d entries   %d flushable\n" , hack_count ,
+           hack_count );
 }
 
 static void oc_squeeze_cache (unsigned int spaces_to_make);
@@ -284,6 +285,7 @@
   cachedata = g_hash_table_new (g_str_hash, g_str_equal);
   indexes = g_hash_table_new (g_str_hash, g_str_equal);
   objectcache_count = 0;
+  hack_count = 0;
 }
 
 /* ------------------------------------------------------------------------- *\
@@ -433,6 +435,11 @@
   /* printf( "add %s/%s\n" , classname , key ); */
   g_hash_table_insert (cachedata, obj->hashkey, obj);
   objectcache_count += 1;
+
+  /* only count 'user' objects */
+  if( strncmp(classname,"geas::",6) != 0 )
+     hack_count += 1;
+
 #if 0
   printf ("objectcache_count = %d\n", objectcache_count);
   printf ("now has %d entries\n", objectcache_count);
@@ -470,8 +477,12 @@
     }
   /* remove it */
   g_hash_table_remove (cachedata, obj->hashkey);
-  oc_free_object_data (object);
   objectcache_count -= 1;
+  if( strncmp(object->classname,"geas::",6) != 0 )
+     hack_count -= 1;
+
+  oc_free_object_data (object);
+
   /* printf( "objectcache_count = %d\n" , objectcache_count ); */
 
   timer_done_operation( TIMER_CACHE );