[gnue] r7137 - trunk/gnue-common/src/datasources/drivers/Base

[reinhard]

Author: reinhard
Date: 2005-03-08 16:32:06 -0600 (Tue, 08 Mar 2005)
New Revision: 7137

Modified:
   trunk/gnue-common/src/datasources/drivers/Base/Connection.py
Log:
Code cleanup, added comments and docstrings.


Modified: trunk/gnue-common/src/datasources/drivers/Base/Connection.py
===================================================================
--- trunk/gnue-common/src/datasources/drivers/Base/Connection.py        
2005-03-08 21:24:29 UTC (rev 7136)
+++ trunk/gnue-common/src/datasources/drivers/Base/Connection.py        
2005-03-08 22:32:06 UTC (rev 7137)
@@ -1,4 +1,4 @@
-# GNU Enterprise Common - Base DB Driver - Connection
+# GNU Enterprise Common Library - Base DB Driver - Connection
 #
 # Copyright 2001-2005 Free Software Foundation
 #
@@ -24,22 +24,44 @@
 import copy
 import string
 
-__all__ = ['Connection']
 
+# =============================================================================
+# Basic connection class
+# =============================================================================
 
-# System Init:
-#   +-- GConnections initializes
-#   +-- GParser initializes:
-#     +-- GDataSource loaded
-#   +-- GDataSources Intialized
-#     +-- GConnection.getDataObject()
-#       +--
-#
 class Connection:
+  """
+  This class must be subclassed by all database drivers. It represents a
+  connection to the backend.
+
+  Following instance variables are available:
+  @param name: name of the connection from connections.conf
+  @param parameters: parameters from connections.conf
+  @param manager: the connection manager (GConnections) instance responsible
+      for this connection
+
+  Descendants I{must} override the following class variables:
+
+  @param defaultBehaviour: standard introspector class for this type of
+      connection
+  @param supportedDataObjects: dictionary of dataObject classes available for
+      this connection type, where the key is the type of the dataObject (can be
+      'object' or 'sql')
+  """
+
+  defaultBehaviour = None
+  supportedDataObjects = {}
+
+
+  # ---------------------------------------------------------------------------
+  # Constructor
+  # ---------------------------------------------------------------------------
+
   def __init__(self, connections, name, parameters):
+
     self.manager = connections
+    self.name = name
     self.parameters = parameters
-    self.name = name
 
     # Text encoding used by the database.
     # (Not all databases support this concept)
@@ -53,17 +75,59 @@
         self._encoding = 'iso8859-1'
 
 
-  # Commit changes to the database
+  # ---------------------------------------------------------------------------
+  # Virtual methods to be implemented by descendants
+  # ---------------------------------------------------------------------------
+
+  def getLoginFields (self):
+    """
+    This method should be overwritten by the database drivers to return a list
+    of tuples in the form (fieldname, label, hide). The first element of the
+    tuple is the field name passed as a dictionary key to the connect method
+    later. The second element is a label to display to the user. If the third
+    element is True, the input for this field should be hidden on the screen.
+    A typical return value would be [("username", "User name:", False),
+    ("password", "Password:", True)].
+    """
+    return []
+
+  # ---------------------------------------------------------------------------
+
+  def connect(self, connectData):
+    """
+    This method should be overwritten by the database drivers to connect to the
+    backend.
+
+    @param connectData: A dictionary with the login fields as requested by
+        getLoginFields and all parameters from connections.conf.
+    """
+    pass
+
+  # ---------------------------------------------------------------------------
+
   def commit(self):
+    """
+    This method should be overwritten by the database drivers to commit data to
+    the backend.
+    """
     pass
 
-  # Rollback changes to the database
+  # ---------------------------------------------------------------------------
+
   def rollback(self):
+    """
+    This method should be overwritten by the database drivers to abort and roll
+    back any running transaction.
+    """
     pass
 
-  # Close the connection to the database backend
+  # ---------------------------------------------------------------------------
+
   def close (self):
-
+    """
+    This method should be overwritten by the database drivers to close the
+    connection to the backend.
+    """
     # Make sure to release the reference to the connection manager as well as
     # the introspector's instance (if available). This makes garbage collection
     # behave nice :)
@@ -72,10 +136,6 @@
       self.introspector = None
 
 
-  def connect(self, connectData):
-    pass
-
-
   # ---------------------------------------------------------------------------
   # Create a new instance of the associated schema creator
   # ---------------------------------------------------------------------------