<component prefix="ZODB.config">

  <!-- TODO needs descriptions for everything -->

  <abstracttype name="ZODB.storage"/>
  <abstracttype name="ZODB.database"/>

  <sectiontype name="filestorage" datatype=".FileStorage"
               implements="ZODB.storage">
    <key name="path" required="yes" datatype="existing-dirpath">
      <description>
        Path name to the main storage file.  The names for
        supplemental files, including index and lock files, will be
        computed from this.
      </description>
    </key>
    <key name="blob-dir" required="no" datatype="existing-dirpath">
      <description>
        If supplied, the file storage will provide blob support and this
        is the name of a directory to hold blob data.  The directory will
        be created if it doeesn't exist.  If no value (or an empty value)
        is provided, then no blob support will be provided. (You can still
        use a BlobStorage to provide blob support.)
      </description>
    </key>
    <key name="create" datatype="boolean" default="false">
      <description>
        Flag that indicates whether the storage should be truncated if
        it already exists.
      </description>
    </key>
    <key name="read-only" datatype="boolean" default="false">
      <description>
        If true, only reads may be executed against the storage.  Note
        that the "pack" operation is not considered a write operation
        and is still allowed on a read-only filestorage.
      </description>
    </key>
    <key name="quota" datatype="byte-size">
      <description>
        Maximum allowed size of the storage file.  Operations which
        would cause the size of the storage to exceed the quota will
        result in a ZODB.FileStorage.FileStorageQuotaError being
        raised.
      </description>
    </key>
    <key name="packer" datatype="dotted-name">
      <description>
        The dotten name (dotten module name and object name) of a
        packer object.  This is used to provide an alternative pack
        implementation.
      </description>
    </key>
    <key name="pack-gc" datatype="boolean" default="true">
      <description>
         If false, then no garbage collection will be performed when
         packing.  This can make packing go much faster and can avoid
         problems when objects are referenced only from other
         databases.
      </description>
    </key>
    <key name="pack-keep-old" datatype="boolean" default="true">
      <description>
         If true, a copy of the database before packing is kept in a
         ".old" file.
      </description>
    </key>
  </sectiontype>

  <sectiontype name="mappingstorage" datatype=".MappingStorage"
               implements="ZODB.storage">
    <key name="name" default="Mapping Storage"/>
  </sectiontype>

  <!-- The BDB storages probably need to be revised somewhat still.
       The extension relationship seems a little odd.
    -->
  <sectiontype name="fullstorage" datatype=".BDBFullStorage"
               implements="ZODB.storage">
    <key name="envdir" required="yes" />
    <key name="interval" datatype="time-interval" default="2m" />
    <key name="kbyte" datatype="integer" default="0" />
    <key name="min" datatype="integer" default="0" />
    <key name="logdir" />
    <key name="cachesize" datatype="byte-size" default="128MB" />
    <key name="frequency" datatype="time-interval" default="0" />
    <key name="packtime" datatype="time-interval" default="4h" />
    <key name="gcpack" datatype="integer" default="0" />
    <key name="read-only" datatype="boolean" default="off"/>
  </sectiontype>

  <sectiontype name="minimalstorage" datatype=".BDBMinimalStorage"
               implements="ZODB.storage" extends="fullstorage"/>

  <sectiontype name="zeoclient" datatype=".ZEOClient"
               implements="ZODB.storage">
    <multikey name="server" datatype="socket-connection-address" required="yes"/>
    <key name="blob-dir" required="no">
      <description>
        Path name to the blob cache directory.
      </description>
    </key>
    <key name="shared-blob-dir" required="no" default="no"
        datatype="boolean">
      <description>
          Tells whether the cache is a shared writable directory
          and that the ZEO protocol should not transfer the file
          but only the filename when committing.
      </description>
    </key>
    <key name="blob-cache-size" required="no" datatype="byte-size">
      <description>
            Maximum size of the ZEO blob cache, in bytes.  If not set, then
            the cache size isn't checked and the blob directory will
            grow without bound.

            This option is ignored if shared_blob_dir is true.
      </description>
    </key>
    <key name="blob-cache-size-check" required="no" datatype="integer">
      <description>
            ZEO check size as percent of blob_cache_size.  The ZEO
            cache size will be checked when this many bytes have been
            loaded into the cache. Defaults to 10% of the blob cache
            size.   This option is ignored if shared_blob_dir is true.
      </description>
    </key>
    <key name="storage" default="1">
      <description>
        The name of the storage that the client wants to use.  If the
        ZEO server serves more than one storage, the client selects
        the storage it wants to use by name.  The default name is '1',
        which is also the default name for the ZEO server.
      </description>
    </key>
    <key name="cache-size" datatype="byte-size" default="20MB">
      <description>
        The maximum size of the client cache, in bytes, KB or MB.
      </description>
    </key>
    <key name="name" default="">
      <description>
        The storage name.  If unspecified, the address of the server
        will be used as the name.
      </description>
    </key>
    <key name="client">
      <description>
        Enables persistent cache files.  The string passed here is
        used to construct the cache filenames.  If it is not
        specified, the client creates a temporary cache that will
        only be used by the current object.
      </description>
    </key>
    <key name="var">
      <description>
        The directory where persistent cache files are stored.  By
        default cache files, if they are persistent, are stored in
        the current directory.
      </description>
    </key>
    <key name="min-disconnect-poll" datatype="integer" default="5">
      <description>
        The minimum delay in seconds between attempts to connect to
        the server, in seconds.  Defaults to 5 seconds.
      </description>
    </key>
    <key name="max-disconnect-poll" datatype="integer" default="300">
      <description>
        The maximum delay in seconds between attempts to connect to
        the server, in seconds.  Defaults to 300 seconds.
      </description>
    </key>
    <key name="wait" datatype="boolean" default="on">
      <description>
        A boolean indicating whether the constructor should wait
        for the client to connect to the server and verify the cache
        before returning.  The default is true.
      </description>
    </key>
    <key name="read-only" datatype="boolean" default="off">
      <description>
        A flag indicating whether this should be a read-only storage,
        defaulting to false (i.e. writing is allowed by default).
      </description>
    </key>
    <key name="read-only-fallback" datatype="boolean" default="off">
      <description>
        A flag indicating whether a read-only remote storage should be
        acceptable as a fallback when no writable storages are
        available.  Defaults to false.  At most one of read_only and
        read_only_fallback should be true.
      </description>
    </key>
    <key name="username" required="no">
      <description>
        The authentication username of the server.
      </description>
    </key>
    <key name="password" required="no">
      <description>
        The authentication password of the server.
      </description>
    </key>
    <key name="realm" required="no">
      <description>
        The authentication realm of the server.  Some authentication
        schemes use a realm to identify the logic set of usernames
        that are accepted by this server.
      </description>
    </key>
    <!-- DM 2008-05-15: added -->
    <key name="drop-cache-rather-verify" datatype="boolean" default="off">
      <description>
        A flag indicating whether the client cache should be dropped
        instead of an expensive verification.
      </description>
    </key>
  </sectiontype>

  <sectiontype name="demostorage" datatype=".DemoStorage"
               implements="ZODB.storage">
    <key name="name" />
    <multisection type="ZODB.storage" name="*" attribute="factories" />
  </sectiontype>


  <sectiontype name="zodb" datatype=".ZODBDatabase"
               implements="ZODB.database">
    <section type="ZODB.storage" name="*" attribute="storage"/>
    <key name="cache-size" datatype="integer" default="5000"/>
      <description>
        Target size, in number of objects, of each connection's
        object cache.
      </description>
    <key name="cache-size-bytes" datatype="byte-size" default="0">
      <description>
        Target size, in total estimated size for objects, of each connection's
        object cache.
        "0" means no limit.
      </description>
    </key>
    <key name="pool-size" datatype="integer" default="7"/>
      <description>
        The expected maximum number of simultaneously open connections.
        There is no hard limit (as many connections as are requested
        will be opened, until system resources are exhausted).  Exceeding
        pool-size connections causes a warning message to be logged,
        and exceeding twice pool-size connections causes a critical
        message to be logged.
      </description>
    <key name="pool-timeout" datatype="time-interval"/>
      <description>
        The minimum interval that an unused (non-historical)
        connection should be kept.
      </description>
    <key name="historical-pool-size" datatype="integer" default="3"/>
      <description>
        The expected maximum total number of historical connections
        simultaneously open.
      </description>
    <key name="historical-cache-size" datatype="integer" default="1000"/>
      <description>
        Target size, in number of objects, of each historical connection's
        object cache.
      </description>
    <key name="historical-cache-size-bytes" datatype="byte-size" default="0">
      <description>
        Target size, in total estimated size of objects, of each historical connection's
        object cache.
      </description>
    </key>
    <key name="historical-timeout" datatype="time-interval"
         default="5m">
      <description>
        The minimum interval that an unused historical connection should be
        kept.
      </description>
    </key>
    <key name="database-name">
      <description>
        When multidatabases are in use, this is the name given to this
        database in the collection.  The name must be unique across all
        databases in the collection.  The collection must also be given
        a mapping from its databases' names to their databases, but that
        cannot be specified in a ZODB config file.  Applications using
        multidatabases typical supply a way to configure the mapping in
        their own config files, using the "databases" parameter of a DB
        constructor.
      </description>
    </key>
    <key name="allow-implicit-cross-references" datatype="boolean">
      <description>
        If set to false, implicit cross references (the only kind
        currently possible) are disallowed.
      </description>
    </key>

  </sectiontype>

  <sectiontype name="blobstorage" datatype=".BlobStorage"
    implements="ZODB.storage">
    <key name="blob-dir" required="yes">
      <description>
        Path name to the blob storage directory.
      </description>
    </key>
    <section type="ZODB.storage" name="*" attribute="base"/>
  </sectiontype>



</component>
