[Zope-CVS] CVS: Packages/Moztop/doc - DataSourceAndSitesManagerReq.txt:1.1

[Stephan Richter]

Update of /cvs-repository/Packages/Moztop/doc
In directory cvs.zope.org:/tmp/cvs-serv29193/doc

Added Files:
	DataSourceAndSitesManagerReq.txt 
Log Message:
Okay, here lands a major rewrite Paul and I were working on:

- Implemented DataSourceManager and refactored SitesManager.

- Datasources are now managed only from the tree directly, no private 
  copy is kept. 

- SitesManager makes now full use of the information found in rsd.xml.


Note: Not everything is working yet, so we need to keep digging:

- Gets wrong datasources for SitesManager

- Cannot add sites due to the problem above

- For some reason the content in Content and Packages is not displayed
  correctly. Some inspection of the RDF is necessary. On the other hand,
  fixing the above problems could fix this one too.


=== Added File Packages/Moztop/doc/DataSourceAndSitesManagerReq.txt ===

Email with requirements

Clearly we need to write down something and agree to it, before
jumping into code or doing checkins.  Below is a statement of the
problem and the beginning of a proposal to solve it.

I haven't gone too far into writing an API yet, as we should agree on
this part first.

--Paul


Summary

Moztop needs to manage the RDF datasources associated with each remote
Zope site.  This proposal covers the responsibilities needed by this
component and a proposed implementation.

Problem

The data in remote datasites is encoded in RDF and loaded as a
datasource in Moztop.  To make working with this RDF easier, we use
the RDFDataSource object from rdfds.js to provide an easier API.

However, Moztop still needs a way grab an RDFDataSource from a list of
all the datasources, as well as other operations.  Thus we need a
component that manages all the datasources.

Responsibilities

  Adding a datasource

    When the site developer adds a new Zope site to their Moztop, the
    component needs to retrieve the RDF, update the sites database,
    and update the tree.

  Reloading a datasource

    If the server data have been changed by someone other than the
    current user, then the RDF is out of date.  In this case, Moztop
    needs to reload the RDF data.  This will involve grabbing the
    datasource, retrieving the RDF, reloading the data, and
    reattaching the datasource to the tree.

    Note that this responsibility also applies when Moztop is
    restarted, thus making this responsibility a common and critical
    one.

  Removing a datasource

    If a user deletes a site, the datasource manager needs to ensure
    that the datasource is removed.  Also, when the Moztop is
    restarted, there shouldn't be a connection to the server to
    retrieve data that won't be displayed.

  Attaching a datasource to the tree

    This is a simple but common activity.  When a datasource is
    created, and also (I believe) when data have changed, the tree
    needs to be rebuilt.

    This is a visually painful process, as the tree collapses.  It
    would be interesting to find techniques to avoid this.

  Detatching a datasource

    There may be circumstances where a datasource is removed from the
    tree and removed from memory, but not permanently.  For instance,
    this might be as part of another sequence, such as reloading.

  Grabbing the appropriate datasource to make a change

    When the site developer makes a change to a resource, the RDF
    model must be updated.  While read-only operations can be made on
    the composite datasource, changes require grabbing the correct
    site datasource.

    Thus, this responsibility requires being given a resource, and
    giving back the datasource that contains that resource.

    There are other situations that require grabbing the correct
    datasource.  For instance, when a site developer selects a site
    and selects reload, the correct datasource for that site must be
    used.

  Saving a datasource

    For datasources where the RDF comes from a Zope server, there
    should be *no* circumstances under which the datasource should be
    saved.  All changes should be sent to the server, which is the
    authoritative copy of the content.  The datasource contents should
    be considered volatile.

    However, datasources such as the sites database are managed by
    Moztop in the local profile directory.  These will need to be
    flushed to disk as appropriate.

  Dumping a datasource

    When debugging, it is very important to see the contents of a
    datasource.  This responsibility can be fulfilled in a number of
    ways (using the dump command, logging something to the log
    manager, creating a visual inspector, etc.)

  Managing in-mem and remote datasources

    The classic Mozilla technique for remote datasources is to create
    a pair: a read-only datasource representing the remote content and
    an in-memory datasource where all local changes are made.  With a
    model like this, you never have to worry about losing changes when
    refreshing the remote content.

  Performing operations on all datasources

    Some of these operations will apply not just to one datasource,
    but to all datasources in the list.  For instance, dumping all
    datasource contents for debugging purposes is a very common
    activity.

Scenarios

  Site developer adds site

  Site developer deletes site

  Site developer reloads site contents

  Site developer restarts Moztop

  Site developer choses "Debug->Dump Datsources"

Proposed Architecture

  I propose an architecture where we create a JavaScript prototype
  called DataSourceManager.  It will be located in its own JavaScript
  module stored in a top-level "lib" directory.

  An instance of this called "dsm" will be declared as a global in
  moztop.js and initialized in initMoztop (which is called by
  moztop.xul as the onload action).  The initialization happens after
  the initialization of the global logging service, thus allowing dsm
  to log messages during its initialization.

  The dsm variable will be global to all scripts in the main window.
  Like the log manager, it will need to be passed explicitly to
  dialogs and wizards.

  The central architectural idea for dsm is that you "lookup" a
  datasource via a method, instead of directly accessing it via a
  property or variable.  This allows dsm to use a datasource attached
  to tree.database and return an instance of RDFDataSource.

Proposed DataSourceManager API

  constructor() -> return null

    Does this do all the work to open the sites database, retrieve all
    the remote RDF, create all the datsources, attach to tree, etc.?