org.netfrag.glib/DataSource/Generic.php

<?php
/**
 * This file contains the GenericDataSource child class
 *
 * @author Andreas Motl <andreas.motl@ilo.de>
 * @package org.netfrag.glib
 * @name DataSource::Generic
 *
 */

/**
 * <b>Cvs-Log:</b>
 *
 * <pre>
 * $Id: Generic.php,v 1.8 2003/03/20 07:22:14 jonen Exp $
 *
 * $Log: Generic.php,v $
 * Revision 1.8  2003/03/20 07:22:14  jonen
 * + modified case 'object' to 'objects'
 *   (cause its loads all *objects* of a given classname)
 *
 * Revision 1.7  2003/03/11 01:43:00  joko
 * + fixed metadata for phpDocumentor
 *
 * Revision 1.6  2003/03/11 01:22:25  joko
 * + fixed metadata for phpDocumentor
 *
 * Revision 1.5  2003/03/11 00:12:49  joko
 * + fixed metadata for phpDocumentor
 *
 * Revision 1.4  2003/03/10 23:25:03  joko
 * + fixed metadata for phpDocumentor
 *
 * Revision 1.3  2003/03/09 15:50:36  joko
 * + additional metadata for Autodia
 *
 * Revision 1.2  2003/03/05 17:28:43  joko
 * updated docu (phpDocumentor testing....)
 *
 * Revision 1.1  2003/03/05 12:04:00  joko
 * + initial commit, from GenericDataSource
 *
 * Revision 1.3  2003/03/03 21:24:18  joko
 * now based on DesignPattern::RemoteProxy
 *
 * Revision 1.2  2003/03/02 01:05:13  joko
 * - purged old code
 *
 * Revision 1.1  2003/03/01 21:47:15  joko
 * renamed from AbstractDataSource.inc
 *
 * Revision 1.1  2003/03/01 20:17:15  joko
 * renamed from GenericDataSource.inc
 * replaced '_proxy' through '_handler' to better associate the ability to act as a generic dispatcher handler
 *
 * Revision 1.3  2003/03/01 15:36:11  joko
 * + debugging
 * + renamed some methods regarding new proposal (build_handler_options, fetch_result, etc.)
 *
 * Revision 1.2  2003/03/01 04:50:27  joko
 * encapsulated all output into tracing mode
 * disabled tracing
 *
 * Revision 1.1  2003/03/01 03:10:40  joko
 * + initial commit
 * </pre>
 *
 */

/**
 * This requires the MemoryDataSource base class
 *
 */

  // V1: compile-time-include, stable since years  ;-)
  //include_once($phphtmllib."/widgets/data_source/MemoryDataSource.inc");

  // V2: runtime-load proposal, more flexible
  // loadModule('MemoryDataSource', 'inc');   // doesn't work (would do if basepath of module is in libpath)
  // loadModule($phphtmllib . '::widgets::data_source::MemoryDataSource', 'inc');   // works  (by accident)
  // loadModule($phphtmllib . "/widgets/data_source/MemoryDataSource", "inc");   // works  (should be stable)
  // loadModule($phphtmllib . "/widgets/data_source/MemoryDataSource.inc", null);   // works  (should be stable)
  

/**
 * Have to have PEAR and DB included
 * the pear dir must be in the 
 * include path.
 */
  // require_once("PEAR.php");   // FIXME: what about PEAR::XML::RPC?
  // require_once("DB.php");


loadModule('DesignPattern::Proxy');
loadModule('DesignPattern::TransparentProxy');
loadModule('DesignPattern::RemoteProxy');

//class GenericDataSource extends MemoryDataSource {
//class GenericDataSource extends DesignPattern_Proxy {
//class GenericDataSource extends DesignPattern_RemoteProxy {
//class GenericDataSource extends DesignPattern_TransparentProxy {

//class GenericDataSource extends MemoryDataSource {
//loadModule("DataSource::Proxy::Memory");
//class GenericDataSource extends DataSource_Proxy_Memory {
//class DataSource_GenericDataSource extends DataSource_Proxy_Memory {
//class DataSource_GenericDataSource extends DesignPattern_Proxy {
//class DataSource_GenericDataSource extends DataSource_Proxy_Memory {

// now independent!!! new class-inheritance-tree possible now!
// solved by having an Adapter *and* a Proxy here!
//class GenericDataSource {

loadModule('DesignPattern::AdapterProxy');


/**
 * This GenericDataSource child class is *completely* independent
 * of a specific storage implementation and intended to be a wrapper
 * class on the way from phpHtmlLib to Xyz. <br>
 *    ("Yyz" gets represented by Data::Storage by now.....)
 *
 * GenericDataSource interacts with an intermediate "proxy" object 
 * (e.g. Data::Driver::Proxy) when doing queries. <br>
 * <pre>
 *    Don't mix this up with a persistent database handle which gets
 *    reused each and every time for different queries.
 *    Here *is* a new instance of Data::Driver::Proxy for *each* query.
 * </pre>
 *
 * But the point is: Caching! The actual *data* isn't read redundant!
 *
 * <pre>
 * --- snipped into here from above ---
 * that may use arbitrary code modules as database handlers.
 * It's aims are to get together:
 *   o phpHtmlLibs "source-handlers"
 *   o PEAR's database handlers 
 *   o custom ones (e.g. Data::Driver::Proxy object, which talks to a remote rpc server)
 * --- snipped into here from above ---
 * </pre>
 *
 * <p>
 * !!!!!!  refactor this to Data::Driver::Proxy  !!!!!!     <-----------------
 *
 * Data::Driver::Proxy instantiates "handlers" below itself
 * which act as encapsulated workers to actually do the stuff to do.
 * It can cache data for "disconnected mode" using the
 * php PEAR DB abstraction objects.
 * One worker already implemented is Data::Driver::RPC::Remote, which
 * talks to a RPC::XML server (todo: talk SOAP!) using PEAR::XML::RPC.
 *
 * <pre>
 * ---  refactored here, but: redundant somehow  ---
 * Data::Driver::Proxy uses a PEAR XML::RPC object to actually
 * talk HTTP and serialize data chunks to and from XML,
 * but adds some caching to this "process of fetching data from a remote side".
 * It "proxies" arbitrary data chunks a) inside a native php4 session, 
 * b) by talking to a rdbms (single proxy-table) or c) [TODO] using PEAR::Cache.
 * ---  refactored here, but: redundant somehow  ---
 * </pre>
 *
 * !!!!!!  refactor this to Data::Driver::Proxy  !!!!!!     <-----------------
 * </p>
 *
 *
 * <p>
 * <b>How to use?</b>
 *
 * Pass an array holding "locator metadata" to the constructor.
 * GenericDataSource takes care of the rest.
 *
 * <pre>
 * Pass an array to the constructor: (e.g.)
 *
 *  1. doing rpc-calls....
 *    <code>
 *    $locator = array(
 *      type => 'rpc',
 *      metadata => array( Host => 'localhost', Port => '8765' ),
 *    );
 *    $source = ne w GenericDataSource($locator);
 *    $this->set_data_source( &$source );
 *    </code>
 *
 *  2. [proposal] common datahandles....
 *    <code>
 *    $locator = array(
 *      type => 'mysql',
 *      dsn => 'known dsn markup',
 *    );
 *    $source = ne w GenericDataSource($locator);
 *    $this->set_data_source( &$source );
 *    </code>
 * </pre>
 * </p>
 *
 *
 * @link http://www.netfrag.org/~joko/
 * @author Andreas Motl <andreas.motl@ilo.de>
 *
 * @link http://www.netfrag.org/~jonen/
 * @author Sebastian Utz <seut@tunemedia.de>
 *
 * @copyright (c) 2003 - All Rights reserved.
 *
 * @link http://www.gnu.org/licenses/lgpl.txt
 * @license GNU LGPL (GNU Lesser General Public License)
 *
 *
 * @package org.netfrag.glib
 * @subpackage DataSource
 * @name DataSource::Generic
 *
 * @todo this:
 * o mungle this to be able to be wrapped around phpHtmlLib's own storage-handles
 * o implement another Data::Driver::Proxy container
 *
 * <pre>
 *              !!!!!!!!          THIS IS THE PROBLEM          !!!!!!!!
 *    !!!!!!!!   here is it where we have to break inheritance again   !!!!!!!!
 *
 *    THE CONFLICT: Beeing in phpHtmlLib *and* DesignPattern::TransparentProxy
 *    inheritance trees at the same time, which is *not* possible at
 *    declare-time. We *do* need some runtime-infrastructure to solve this!
 *
 *    TODO: move build- and check-locator stuff from ObjectList to this place!!!
 *
 *    ABOUT:
 *      1. otherwhere: WebApp - scope:
 *          x handles page vs. block vs. widget; dispatches MVC-View
 *      2. here: DataSource - scope:
 *          x handles bridge to frameworks (e.g. phpHtmlLib) vs. actual data driver libs (PEAR, etc.))
 *          o clean implementation using a DesignPattern::AdapterProxy
 * </pre>
 *
 *
 */
class DataSource_Generic extends DesignPattern_AdapterProxy {

//    !!!!!!!!   here is it where we have to break inheritance again   !!!!!!!!
//              !!!!!!!!          THIS IS THE PROBLEM          !!!!!!!!


        /**
         * This var holds the locator metadata hash
         * that is used to feed metadata to a per-query-instance
         * of an Adapter object.
         *
         */
        //var $_locator = NULL;

  /**
    * This var holds the locator metadata hash
    * which is built from some predefined rules
    * using metadata from $_options and some
    * other presets.
    *
    * See '_buildLocator' which acts as a dispatcher
    * depending on $_options[datasource].
    * (main dispatching level)
    *
    * The structure of a full blown locator looks like this:
    *
    *  $locator = array(
    *    type => '<your type specifying the datasource-type>',
    *    metadata => array(
    *       ... your arbitrary deep metadata structure ...
    *    ),
    *    [dsn => '<your dsn markup>'],
    *  );
    *
    * Example 1 - data is inside a rdbms, using a dsn to connect to it:
    *  $locator = array(
    *    type => 'sql',
    *    dsn => 'mysql://username:password@localhost/database',
    *  );
    *
    * Example 2 - data is inside an odbms, reachable by doing remote procedure calls (rpc):
    *  $locator = array(
    *    type => 'rpc',
    *    metadata => array(
    *      package => 'Data::Driver::Proxy',
    *      Host => 'localhost',
    *      Port => '8765',
    *    )
    *  );
    *
    */
    var $_locator = NULL;


        /**
         * This var holds the module information required to
         * create instances of a Proxy and an Adapter.
         * Information might get extracted from a 
         * DataSource::Locator instance.
         *
         * --- A skeleton:
         *
         *  $this->_modules = array(
         *    _proxy => array( _id => '', _module => '', _options = array(), _instance => &$obj),
         *    _adapter => array( _id => '', _module => '', _options = array(), _instance => &$obj),
         *  );
         *
         *
         * --- An example:
         *
         *  $this->_modules = array(
         *    _proxy => array( _id => 'rpc', _module => 'DesignPattern::RemoteProxy', _instance => &$obj),
         *    _adapter => array( _id => 'phpHtmlLib', _module => 'DataSource::Adapter::phpHtmlLib::DataListSource', _instance => &$obj),
         *  );
         *
         *
         */
    //var $_modules = NULL;


        /**
         * This var holds the query hash
         * that is used to feed as query to a per-query-instance
         * of a Data::Driver::Proxy object.
         *
         */
        var $_query = NULL;


        /**
         * this holds the query result from the
         * Data::Driver::Proxy->queryXyz() call
         *
         */
        var $_result = NULL;


        /**
         * The constructor is used to pass in the
         * locator metadata hash.
         *
         * @param LocatorMetadataHash array - layout: array( type => '', metadata => '', dsn => '' )
         * @param Query array - layout: array( type => '', metadata => '', dsn => '' )
         */


        function DataSource_Generic( &$locator, $query ) {

                // copy parameter from query to locator
                //$this->_locator->merge_to($this->_locator, array( datasource_type => $query[datasource] ), '_');
                //$this->_locator->_datasource_type = $query[datasource];
                //$locator[_datasource_type] = $query[datasource];
                
      /**
       * <!-- Autodia -->
       * can do: (this is metadata supplied for Autodia, don't delete!)
       *  $this->_locator = new DataSource_Locator()
       *
       */

                // build master locator
                $this->_locator = php::mkComponent('DataSource::Locator', $locator, array( datasource_type => $query[datasource] ) );
                //exit;
                //$this->_locator = php::mkComponent('DataSource::Locator');
                
                $this->_locator->check();
                
                // trace
        //print "locator-obj: " . Dumper($this->_locator);
        //print "locator-data: " . Dumper($locator_data);
        //exit;
                
                
                /*
                $this->_modules = array(
                  _proxy => array( _id => $locator->_datasource_type ),
                  _adapter => array( _id => $locator->_adapter_type ),
                );
                */
                
      //$this->set_locator( $locator );
      $this->set_query( $query );


    /*
    // V1:
    // pre-flight: establish and check locator metadata
      $this->_buildLocator();
      $this->_checkLocator();
    */


    // pre-flight: check locator metadata
      //$locator->build();
      if (!$this->_locator->check()) {
        user_error("locator-check failed.");
        exit;
         //return;
      }

//exit;


    /**
     * <!-- Autodia -->
     * can do: (this is metadata supplied for Autodia, don't delete!)
     *  $proxy = new DesignPattern_RemoteProxy()
     *
     */


    // --- Proxy selector/dispatcher ...
    
    switch ($this->_locator->_datasource_type) {
      case 'rpc':
                //$locator_data = $this->_locator->get_metadata();
        //$this->_modules[_proxy][_options] = array( locator => $this->_locator, query => $query );
        //$this->_modules[_proxy][_module] = 'DataSource::Proxy::XMLRPC';

        //$this->_modules[_proxy][_module] = 'DesignPattern::RemoteProxy';
        //$this->_modules[_proxy][_options] = $locator_data;
        
        //$this->set_component_name('DesignPattern::RemoteProxy');
        //$this->set_component_options($locator_data);

        $this->set_component_name('DesignPattern::RemoteProxy');
        
        break;
      default:
        user_error("Site::GenericPage: no Proxy could be selected!");
        break;
    }


      /*
      // V1:
      // make up dummy args by now
      $args = array(
        adapter => 'phpHtmlLib',
      );
      */
      
      // V2: now propagated from caller!

      //print Dumper(array( locator => $locator, query => $query ));
      //exit;
      
      //$this->create_adapter($this->module, $this->function, $this->arguments);
      //$this->set_handler( $this->get_adapter() );


        // --- Adapter selector/dispatcher ...
        // ... resolves this._modules.adapter._id to this._modules.adapter._module
        
        switch ($locator->_adapter_type) {
          case 'phpHtmlLib':
            //$adapter_arguments = $args[title];

            $this->set_adapter_module('DataSource::Adapter::phpHtmlLib::DataSource');
            
            // in order to let the Adapter communicate with the Proxy,
            // instantiate a wrapper method in a third namespace via
            // Exporter::export_symbol(from, to)
            $this->set_adapter_options($this);


            break;
          default:
            user_error("DataSource::GenericDataSource: no Adapter could be selected!");
            break;
        }


    // --- module instantiation - Proxy and Adapter

      //user_error("handle proxy here!");
      //$this->create_proxy();

      //print Dumper($this);

      //print "this: " . Dumper($this);

      // V1:
      /*
      $proxy = php::mkComponent($this->_modules[_proxy][_module], $this->_modules[_proxy][_options]);
      print "proxy: " . Dumper($proxy);
      //exit;
      */

      // V2:
      /*
      $resultHandle = mkObject('DesignPattern::RemoteProxy', $cache_key, array( key => 1, command => $command, query => $query, remote => 1, rpcinfo => $rpcinfo, cache => array( db => 0, session => 1 ) ) );
      $result = $resultHandle->getAttributes();
      return $result;
      */

      // V3:
      // $this->set_handler( $proxy );

      // V4: use _component_name & _component_options (proposal from GenericPage)
      // $this->_component_name = ...
      // $this->create_handler();


      /**
       * <!-- Autodia -->
       * can do: (this is metadata supplied for Autodia, don't delete!)
       *  $adapter = new DataSource_Adapter_phpHtmlLib_DataListSource()
       *
       */

      // V1:
      //$this->create_adapter($adapter_module, $this->function, $this->arguments);

      // V2: FIXME - better use V1?
      $adapter = php::mkComponent($this->get_adapter_module(), $this->get_adapter_options());
      $this->set_adapter($adapter);
      
      
        }

    function make_adapter_transparent() {

      // ... known from Site::Adapter::php::Class:
      
        // At this place the Adapter becomes a Proxy.
        // This functionality currently correlates to the
        // name of our ancestor, DesignPattern::AdapterProxy.
        // FIXME: move this code to its namespace!!!
        // FIXME: rename to set_proxy...
        
        // The reason this has to occour here is required
        // by the TransparentProxy to actually make the
        // _handler (_proxy) transparent later....
        //$this->set_proxy( $this->get_adapter() );
    }
        
        /**
     * Set the metadata information 
     * (a DataSource::Locator) we will use 
     * to build encapsulated instances 
     * of both a Proxy and an Adapter.
     *
     * @param LocatorMetadataHash array - 
     *
     */
    function set_metadata( &$locator ) {
        $this->_locator = &$locator;
    }

    function &get_metadata() {
        return $this->_locator;
    }


        /**
     * Set the query metadata hash we will feed *completely*
     * to an encapsulated Proxy instance.
     *
     * @param QueryDeclaration array - 
     *
     */
    function set_query( $query ) {
        $this->_query = $query;
    }

        /**
     * Issue remote/proxy call
     * Stolen from Application_AbstractBackend::_remote_method (RefactoringProposal?)
     * Tweaked a bit: proxy package now taken from $this->_handler_name
     *
     * Create a new instance of a proxy and store it for later reuse.
     * Read the locator metadata hash and create 
     * the proxy handler instance using passed-in name.
     *
     * @param string - $proxy_name (namespaced classname - perl syntax - e.g.: Data::Driver::Proxy)
     *
     */
    function datasource_handler_call() {


      // 1. read args and build cache key

        $arg_list = func_get_args();
        $command = array_shift($arg_list);
        $cache_key = join("-", array(session_id(), $command, join('_', $arg_list) ));
        //print "cache_key: $cache_key<br>";
  
        // FIXME: what if arg_list still contains more elements after doing this?
        $query = array_shift($arg_list);

      // 2. prepare proxy-options (read from locator)
      
      //print "this: " . Dumper($this);
      //exit;

        // read from locator metadata
          //$proxy_name = $this->_locator[metadata][package];
          
          // V1:
          //$rpcinfo = array( Host => $this->_locator[metadata][Host], Port => $this->_locator[metadata][Port] );

          // V2:
          $rpcinfo = $this->_locator->get_metadata();

        // FIXME! implement this into Data::Driver::RPC::Remote!
          //$rpcinfo[to_latin] = 1;
          
        // FIXME! patch query
        if (sizeof($query) == 1) {
          $query = $query[0];
        }

      //print "query: " . Dumper($query);

      //  !!! use DesignPattern::Proxy here !!!
      // $proxy = new DesignPattern_Proxy($proxy_name, ...)
      // or:
      // $proxy = mkObject('DesignPattern::Proxy');
      // $this->set_handler( $proxy );
      // or:
      // $proxy = mkObject('DesignPattern::Proxy');
      // $proxy->
      // $this->set_handler( $proxy );
      
      
      //$this->set_component_name( $proxy_name );
      $this->set_component_options( $cache_key, array( key => 1, command => $command, query => $query, remote => 1, rpcinfo => $rpcinfo, cache => array( db => 0, session => 1 ) ) );
      //print Dumper($this);
      //exit;
      
      $this->create_proxy();
      
      //print Dumper($this);
      //exit;
      
      /*
      // --------------------   clone this & modify  ----------
      $proxy = mkObject($proxy_name, $cache_key, array( key => 1, command => $command, query => $query, remote => 1, rpcinfo => $rpcinfo, cache => array( db => 0, session => 1 ) ) );
      $this->set_handler( $proxy );
      //$result = $resultHandle->getAttributes();
      //return $result;
      //$this->_result = $resultHandle->getAttributes();
      //$this->_result = $this->_handler->getAttributes();
      // --------------------   clone this & modify  ----------
      */
  
    }


        function datasource_handler_buildoptions() {

      //print Dumper($this->_query);
      //exit;

      // make up a command from metadata
      // FIXME: abstract this some more (e.g. via a CommandMapper|Registry)
        switch ($this->_query[metatype]) {
          case 'data':
            $command = 'queryData';
            //$command = 'getObjects';   // FIXME!!!
            //$this->_locator->set_option('metadata.command', $command);
/*
            $args = array();
            switch ($this->_query[vartype]) {
              case 'objects':
                if (!$this->_query[classname]) {
                  $msg = "_query[vartype] == 'objects' requires _query[classname]";
                  user_error("GenericDataSource::query_data() - failed: " . $msg);
                }
                array_push($args, $this->_query[classname]);
                break;
            }
 */
            $query_args = array();
             switch ($this->_query[abstract_type]) {
              case 'list':
                if (!$this->_query[classname]) {
                  $msg = "_query[vartype] == 'objects' requires _query[classname]";
                  user_error("GenericDataSource::query_data() - failed: " . $msg);
                }
                //array_push($query_args, $this->_query[classname]);
                $query_args[classname] = $this->_query[classname];
                break;
              case 'item':
                if (!$this->_query[classname]) {
                  $msg = "_query[vartype] == 'objects' requires _query[classname]";
                  user_error("GenericDataSource::query_data() - failed: " . $msg);
                }
                $query_args[guid] = $this->_query[ident];
                $query_args[classname] = $this->_query[classname];
                break;              
            }
            $args = array(
                          'data_type' => $this->_query[abstract_type],
                          'query_args' => $query_args
                          );
           break;

          // querySchema
          case 'schema':
            //print "Testing schema:" . "<br>";
            $command = 'querySchema';
            break;
        }
      
        
        /*
        $this->_query[rpc_command] = $command;
        $this->_query[rpc_args] = $command;
        */

        // methods!!!
        $this->_locator->_call[_method] = $command;
        $this->_locator->_call[_arguments] = $args;

      //$adapter = $this->get_adapter();
      
      // trace
        /*
        print Dumper(null, '<b>= = = = = = = = = = = = = = = = = = = = = =</b>');
        print Dumper('datasource_handler_buildoptions', array(
          "_locator" => $this->_locator,
          "_query" => $this->_query,
          "command" => '<b>' . $command . "</b>",
          "args" => $args
        ));
        */

    /*
    $this->_handler_options = array(
      method => $command,
      args => $args,
    );
    */
      
  }

        function &fetch_result() {
      
      $this->datasource_handler_buildoptions();

      $method = $this->_locator->_call[_method];
      $args = $this->_locator->_call[_arguments];
      
      // pre-flight checks
        if (!$method) {
          $msg = "Remote command could not be resolved, please pass in or check configuration.";
                        user_error("GenericDataSource::query_data() - failed: " . $msg);
          return;
        }

      //print "fetch_result: this->_handler=" . Dumper($this->_handler);

      // do remote call here and get result
      // FIXME: handle synchronous/asynchronous mode here!!!
        $this->datasource_handler_call($method, $args);
        
        
        // TODO: ... = $this->poll_handler_result  and  $this->get_handler_result
        $proxy = $this->get_proxy();
        $this->_result = $proxy->getResult();
        //print "result: " . Dumper($this->_result); exit;

        $this->_result_count = sizeof($this->_result);

      // trace
        if ($this->_debug[notice]) {
          //print "_result = " . Dumper($this->_result);
          print "DataSource::Generic->_result_count = " . $this->_result_count . "<br/>";
        }
        
        return $this->_result;

        }


  function &query_data() {
    //print "query!<br/>";
    return $this->fetch_result();
    //$this->handle_result();
  }

  function query_schema() {
    user_error("FIXME: query_schema");
    // $this->datasource_handler_call( ... );
  }
  
  function &get_result() {
    return $this->_result;
  }
        
}

?>
MailToCvsAdmin">MailToCvsAdmin	ViewVC Help
Powered by ViewVC 1.1.26