[gnue] r8279 - trunk/gnue-navigator/doc/technotes

[jamest]

Author: jamest
Date: 2006-03-28 21:34:36 -0600 (Tue, 28 Mar 2006)
New Revision: 8279

Added:
   trunk/gnue-navigator/doc/technotes/00003.txt
   trunk/gnue-navigator/doc/technotes/00004.txt
Modified:
   trunk/gnue-navigator/doc/technotes/00002.txt
Log:
GAP proposed features
High level description of the GAP Component system and it's usage
Work in progress on GAP/Common relationship


Modified: trunk/gnue-navigator/doc/technotes/00002.txt
===================================================================
--- trunk/gnue-navigator/doc/technotes/00002.txt        2006-03-28 16:32:11 UTC 
(rev 8278)
+++ trunk/gnue-navigator/doc/technotes/00002.txt        2006-03-29 03:34:36 UTC 
(rev 8279)
@@ -1,87 +1,54 @@
-Title:   Services and Utilities in GAP
+Title:   GAP General Feature Overview
 Status:  Current
 Created: 2006-03-27
 
-All applications require a mixture of a base set of features.  In GAP
-applications are considered as either GUI or Non-GUI.  An example of a
-GUI application would be GNUE-Forms.  Examples of non-GUI applications
-would include a report ran from the command line, or something as complex 
-gnue-appserver.
+Most applications have a similar set of base requirements.  GAP provides
+a common set of features on which you can easily build custom applications.
 
-*WIP*
+A listing of features commonly required by applications.
 
-Features apps need:
-  Non-GUI
-    configuration
-    debugging 
-    profiling
-    file storage
-    authentication
-    communications
+  Configuration management
+    System and user specific settings
 
-  GUI
-    menus
-    toolbars
-    status bars
-    windows
+  Debugging support
+    Logging, exception handling, profiling
+    
+  Storage systems 
+    File access
+    Data Base access
+  
+  Authentication
+    Access control lists
+  
+  Communications
+    Networking
+  
+  Extensibility
+    Components 
+    
+  Output
+    Standard output formats
+      PDF
+      Barcode
+      PS
+    
+  
+  User Interface Framework
+    A generic API to manipulate high level structures in an application
+    such as menus, toolbars, status bars, splashscreens, dialogs, and
+    display "windows".  This is not a complete widget set, it is a 
+    general framework that will provide widget set compatible display
+    areas in which an app can draw.
 
 
+In addition to features commonly required by applications other
+things should be taken into account when building an applications.
 
-App 
-  * Should require no arguments to it's constructor
-  * No functionality beyond the registry
-  * Configuration via code for simple apps
-  * Configutation via an xml stream 
-      - so we can create a base GUI app and developers can remove things
-        from it and add things to it.  Like netbeans
-        
-  Registry
-    * Manages the loading of components
-    * Should also provide a service to reload components upon demand
-      (optional auto look for updates?)
-      
-  Components
-    * Components provide services to the application
-    * They should not require args to their constructors, instead an
-      api should exist to let them register services.
-    * Constructors should be able to list dependencies of constructor types
-    * Every component should have a primary interface defined via 
-      zope.interface 
-
-The gap registry would consist of GObj based tree of components and the like
-
-
-# GAP =========================================================================
-Most gap functionality will be based upon libraries found in GNUe Common.  Some
-items will be removed from common as they are a better fit in GAP.
-
-gap.foundation             # The primary application
-gap.service.registry       # Manages components (always loaded)
-
-gap.utility.security       # Deals with user authentication
-gap.utility.logging        # Loging support
-gap.utility.config         # Configuration processing
-gap.utility.debug          # Debug support
-gap.utility.profile        # Profiler 
-gap.utility.clp            # Command line processor
-gap.utility.datasources    # Datasources
-gap.utility.events         # Event handling
-gap.utility.storage        # Persistant storage
-gap.utility.rpc            # Remote procedure calls
-gap.utility.settings       # Supports user settings
-gap.utility.pdftable       # A PDF Table generator
-gap.utility.barcode        # Barcode utility
-gap.utility.ui             # User interface
-gap.utility.ui.menu        # menuing
-
-# Common wrappers =============================================================
-
-common.ui.cursing
-common.datatypes
-common.xml
-common.setup              # Setup.py support
-common.utils.string       # String processing functions
-common.external           # External libs we've added
-common.drivers.ui.cursing # Curses interface
-common.drivers.data.dbf   # DBF Driver
-common.
\ No newline at end of file
+  Maintainability
+    The environment should encourage good coding styles in all places
+    and should enforce them when possible.
+  
+  Testing
+    
+  Documentation
+    Programs should self document their configuration options.
\ No newline at end of file

Added: trunk/gnue-navigator/doc/technotes/00003.txt
===================================================================
--- trunk/gnue-navigator/doc/technotes/00003.txt        2006-03-28 16:32:11 UTC 
(rev 8278)
+++ trunk/gnue-navigator/doc/technotes/00003.txt        2006-03-29 03:34:36 UTC 
(rev 8279)
@@ -0,0 +1,151 @@
+Title:   GAP Component Architecture
+Status:  Current
+Created: 2006-03-28
+
+The component architecture is based upon a similar architecture in Zope3. In
+uses several modules from zope3 in fact as it's foundation.  In GAP,  
applications
+consist of components known as services and utilities.  
+
+  Services
+    As in zope3,  services are the mission critical components of an 
+    application.  If a service will not load then the application is 
+    non-functional.  An example of a service would be the datasource 
+    manager service in an application that processes information in
+    the database.
+    
+  Utilities
+    Utilities are less critical components of an application.  A failure 
+    to load a utility doesn't result in application failure.  An example
+    of an utility would be a component that adds a google style search
+    bar to your applications toolbar.
+    
+It's worth noting that almost any component might be a service in one
+application and a utility in another.  For example, the datasource
+manager component would be application critical in an application that 
+manipulated an database.  However it might be a utility in a call center
+monitoring application that attempted to store logs in a database but 
+could continue to display information if the database connection was
+unavailable.
+
+More on Components 
+  Component Interfaces
+    Components are written to an interface and can only communicate with
+    each other across that interface.  Once a component interface API
+    is stablized that interface will remain consistant.  While slanted 
+    toward java application the  "Life-cycle of an API" and 
+    "Preservation of Investments" sections of the document at 
+    http://openide.netbeans.org/tutorial/api-design.html are worth taking
+    into consideration 
+  
+  Component Assembly
+    Components are basically the building blocks of an application.  An
+    application developer will take existing GAP components, add a few 
+    custom components and plug them together to form a new application.
+    This assembly can either be done in python code for simple applications
+    or it can be done via an application specific manifest file.
+    
+    By providing for a file based assembly of components we make it 
+    simple to take an existing application such as GNUe Designer, remove
+    components we don't need, and tack on new components to the remaining 
+    pieces.
+  
+  Component Registry
+    The component registry is responsible for maintaining the current 
+    components loaded into an application.  It handles the loading of
+    components, processes requests for handles to components, reloads
+    components if required.  It will also probably deal with dependency
+    mapping so that components get loaded in the proper order.
+    
+    Since all components will interface with the component registry, 
+    it's interface will be kept small and simple.  Components are 
+    registered by both the Interface they provide and by a name. 
+    
+
+Advantages of the Component Architecture (some taken from IRC logs)
+
+  Extensiblity
+    New components can be added to applications at the end user site.
+    Say I wanted to write a call queue monitor for my call center at 
+    work to replace the full screen one we currently use.  I want this
+    monitor to add a button to my GNUe Forms toolbar that shows current
+    number of calls holding.  If the button is pressed I want it to launch
+    my full screen monitor.  By creating a component that registers this
+    button on my Forms toolbar I've extended forms without needing to 
+    know all the Forms internals.  I only needed to learn how to load and
+    register my component with GAP and the API to add a button to the 
+    toolbar.  Later if I were to port my primary sales application to 
+    the GAP platform then I could reuse that same component in that 
+    app as well.
+    
+  Maintainability
+    One issue we've faced in the GNUe applications is broken encapsulation.
+    Often times we hard link through numerous classes to get to the instance
+    we need.  An example from GNUe Forms reads 
+    
+    self._dataSourceLink._connection.rollback ()
+    
+    With components we'd do something along the lines of 
+    
+      queryComponent(IConnectionManager) 
+      or
+      queryComponentPool(IConnectionManager)
+       
+    to get a handle a connection manager that was registered for the 
+    application.  As a result code no longer needs to care about the
+    location of an instance in the application heirarchy.  It only
+    needs to know the Interface it requires and the API that interface
+    provides.
+    
+    Component APIs will also be kept as clean and small as possible
+    in order to maximize flexibility in the future.  The less API we
+    expose the easier it is to replace that component with a new 
+    implementation and not break existing code.
+     
+  Flexibility
+    Component based applications also provide unique oprotunities in 
+    customization of applications.  It is possible to replace or extend
+    existing services by replacing that service in an application.  While 
+    this would be handy in testing new replacement components another 
+    possibility exists.
+    
+    Since components ask for other components by Interface it is possible
+    to wrapper existing components inside another component that modifies
+    the behaviour of the existing component.  For the pattern crazed amongst 
+    us I believe you'd call this a decorator pattern.  An example
+    
+    Example: Connection tracking
+    
+    Lets say FooCorp wants to log all login attempts on their system to a line 
+    printer.  
+    
+    They could ask us to add the functionality to out connection manager.
+    However this is unlikely to be possible for every request and would
+    result in a fairly bloated connection manager code base and API over 
+    time.
+    
+    They could modify the existing connection manager login method to send 
+    the desired output to the line printer.  But they'd have to then track 
+    updates to our base code and remerge their changes after each upgrade.
+    
+    They could subclass our login manager, add a call to the login method
+    to send the desired output to the line printer, then call the existing
+    method in the superclass.  They would then need tofind all references 
+    to the original class and replace them.  Again creating update maintenance
+    after each new release.
+    
+    But with the component system they could still subclass our connection 
manager, 
+    or write their own to the same API.  They would then adjust the application
+    manifest to load their connection manager instead of our own.  When 
loaded, 
+    their custom connetion manager still would register itself as proving the 
IConnectionManager
+    interface.  GAP appliations are not coded to a specific connection manager
+    class located in a specific module.  Instead they query the component 
registry
+    for the component that provides an IConnectinManager interface, like this.
+    
+      queryComponent(IConnectionManager) 
+      
+    So existing applicatoins will not notice the change.  If they've 
subclassed 
+    our connection manager then they would get any security updates without
+    requiring any appication changes.  It would even be possible to provide 
+    a system wide override file for these components that would allow their 
+    on site replacements of components to stay in effect between upgrades
+    to applications manifest files.
\ No newline at end of file

Added: trunk/gnue-navigator/doc/technotes/00004.txt
===================================================================
--- trunk/gnue-navigator/doc/technotes/00004.txt        2006-03-28 16:32:11 UTC 
(rev 8278)
+++ trunk/gnue-navigator/doc/technotes/00004.txt        2006-03-29 03:34:36 UTC 
(rev 8279)
@@ -0,0 +1,39 @@
+Title:   GAP/Common Interactions
+Status:  Work in Progress
+Created: 2006-03-28
+
+
+# GAP =========================================================================
+Most gap functionality will be based upon libraries found in GNUe Common.  Some
+items will be removed from common as they are a better fit in GAP.
+                                 
+gap.foundation             # The primary application
+gap.service.registry       # Manages components (always loaded)
+                                 
+gap.utility.security       # Deals with user authentication
+gap.utility.logging        # Loging support
+gap.utility.config         # Configuration processing
+gap.utility.debug          # Debug support
+gap.utility.profile        # Profiler 
+gap.utility.clp            # Command line processor
+gap.utility.datasources    # Datasources
+gap.utility.events         # Event handling
+gap.utility.storage        # Persistant storage
+gap.utility.rpc            # Remote procedure calls
+gap.utility.settings       # Supports user settings
+gap.utility.pdftable       # A PDF Table generator
+gap.utility.barcode        # Barcode utility
+gap.utility.ui             # User interface
+gap.utility.ui.menu        # menuing
+                                 
+# Common wrappers =============================================================
+                                 
+common.ui.cursing                
+common.datatypes                 
+common.xml                       
+common.setup              # Setup.py support
+common.utils.string       # String processing functions
+common.external           # External libs we've added
+common.drivers.ui.cursing # Curses interface
+common.drivers.data.dbf   # DBF Driver
+common.                                                                        
                                                                                
                                                                                
                                                          
\ No newline at end of file