<!-- $Id: ref-stores.sgml,v 1.1 1999/05/24 09:25:26 rob Exp $ -->
<chapter id="ref-stores">
  <title>Stores</title>
  
  <para>
    Databases can be located in many different places: on a connected
    handheld, in a local directory, or even on an SQL server.  Support
    for specific database access methods is provided by plug-ins in
    the <literal/Store/ collection.  The core code for all
    <literal/Store/ plug-ins is found in the <classname/Pyrite.Store/
    module.
  </para>

  <para>
    <literal/Store/ plug-ins operate in a two-tiered fashion.  Each
    plug-in represents a general type of database storage, and can be
    used to generate objects representing a particular "live" instance
    of that storage.  For example, the <classname/Directory/ plug-in
    represents the general concept "databases stored in a local
    directory", and it generates store objects which can be used to
    access a specific, existing directory.  The base class for
    <literal/Store/ plug-ins is <classname/Pyrite.Store.Store/; the
    base class for live store objects is
    <classname/Pyrite.Store.BaseStore/.
  </para>

  <sect1 id="ref-stores-store">
    <title>Class: Store</title>

    <para>
      The <classname/Store/ class is a subclass of
      <classname/Pyrite.Plugin/, which is a subclass of
      <classname/Sulfur.Plugin/.
    </para>
    
    <sect2 id="ref-stores-store-classattributes">
      <title>Class Attributes</title>
      
      <variablelist>
	<varlistentry>
	  <term><structfield/store_class/ (<type/class object/)</term>
	  <listitem>
	    <para>The class from which to generate live store objects
	      by default.</para>
	  </listitem>
	</varlistentry>
      </variablelist>
    </sect2>
    
    <sect2 id="ref-stores-store-methods">
      <title>Methods</title>
      
      <variablelist>
	<varlistentry>
	  <term><function/__call__/ (<parameter/*/, <parameter/**/)</term>
	  <listitem>
	    <para>Create a live store object.  All parameters are
	      passed to that object's <function/__init__/
	      method.</para>
	  </listitem>
	</varlistentry>
      </variablelist>
    </sect2>
  </sect1>
  
  <sect1 id="ref-stores-basestore">
    <title>Class: BaseStore</title>
    
    <sect2 id="ref-stores-basestore-methods">
      <title>Methods</title>
      
      <variablelist>
	<varlistentry>
	  <term><function/open/ (<parameter/name/,
	    <parameter/mode/='rws',
	    <parameter/dbclass/=<classname/Pyrite.Database/,
	    <parameter/**/)
	  </term>
	  <listitem>
	    <para>Open an existing database.  The <parameter/mode/ is
	      a string which can include the characters <literal/r/
	      for reading, <literal/w/ for writing, <literal/s/ for
	      access to records marked "secret", and/or <literal/x/
	      for exclusive access.</para>
	    
	    <important>
	      <para>Not all stores support all combinations of
		modes.</para>
	    </important>

	    <para>The <parameter/dbclass/ parameter specifies a
	      subclass of <classname/Pyrite.Database/ (or a class
	      exhibiting the same interface) to use for this
	      database.</para>
	  </listitem>
	</varlistentry>
	
	<varlistentry>
	  <term><function/create/ (<parameter/name/,
	    <parameter/creator/, <parameter/type/,
	    <parameter/flags/=0, <parameter/version/=1,
	    <parameter/dbclass/=<classname/Pyrite.Database/,
	    <parameter/**/)</term>
	  <listitem>
	    <para>Create a new database, with the specified header
	      information.  The resulting database is opened and
	      returned as an object of class
	      <parameter/dbclass/.</para>
	  </listitem>
	</varlistentry>
	
	<varlistentry>
	  <term><function/delete/ (<parameter/name/, <parameter/**/)</term>
	  <listitem>
	    <para>Delete a database.</para>
	  </listitem>
	</varlistentry>
	
	<varlistentry>
	  <term><function/info/ (<parameter/name/, <parameter/**/)</term>
	  <listitem>
	    <para>Return a database's header, as a dictionary.</para>
	  </listitem>
	</varlistentry>
	
	<varlistentry>
	  <term><function/list/ (<parameter/**/)</term>
	  <listitem>
	    <para>Return a list of the names of all databases in the
	      store.</para>
	  </listitem>
	</varlistentry>
	
	<varlistentry>
	  <term><function/listinfo/ (<parameter/name/=None,
	    <parameter/creator/=None, <parameter/type/=None,
	    <parameter/**/)</term>
	  <listitem>
	    <para>Return a list of the headers of databases in the
	      store.  By default, all available databases are listed;
	      however, if one or more of <parameter/name/,
	      <parameter/creator/, or <parameter/type/ are supplied,
	      only databases matching the supplied values are
	      listed.</para>
	    
	    <tip>
	      <para>The <parameter/name/ parameter might seem kind of
		useless given the existence of the <function/info/
		method, but it can actually be quite useful as part of
		a one-step test to see if a particular database both
		exists and matches a particular application.
	      </para>
	    </tip>
	  </listitem>
	</varlistentry>
	
	<varlistentry>
	  <term><function/copy/ (<parameter/store/, <parameter/name/)</term>
	  <listitem>
	    <para>Copy the named database from this store to another
	      one..</para>
	  </listitem>
	</varlistentry>
	
	<varlistentry>
	  <term><function/install/ (<parameter/store/, <parameter/name/)</term>
	  <listitem>
	    <para>Copy the named database from another store to this
	      one.</para>
	    
	    <important>
	      <para>The reason for the existence of both
		<function/copy/ and <function/install/ is because
		certain stores (<literal/DLP/, for example) require
		different behavior depending on whether they are the
		source or target of a database copy.  Whenever
		possible, your code should use <function/install/
		instead of <function/copy/ when working with stores of
		unknown type.</para>
	    </important>
	  </listitem>
	</varlistentry>
      </variablelist>
    </sect2>
  </sect1>
</chapter>

<!--Local Variables: -->
<!--sgml-parent-document: ("prg.sgml" "chapter") -->
<!--sgml-doctype: "prg.sgml" -->
<!--End: -->