Changeset 3591


Ignore:
Timestamp:
Jul 23, 2007, 2:04:24 PM (14 years ago)
Author:
Nicklas Nordborg
Message:

References #551. Moved doc about secondary storage controllers from old to new documentation.

File:
1 edited

Legend:

Unmodified
Added
Removed
  • trunk/doc/src/docbook/developerdoc/plugin_developer.xml

    r3585 r3591  
    32953295    <sect2 id="plugin_developer.other.secondary">
    32963296      <title>Secondary file storage plugins</title>
    3297       <para>
    3298         This documentation is only available in the old format.
    3299         See <ulink url="http://base.thep.lu.se/chrome/site/doc/development/plugins/storage/index.html"
    3300           >http://base.thep.lu.se/chrome/site/doc/development/plugins/storage/index.html</ulink>
    3301       </para>
     3297     
     3298      <sect3 id="plugin_developer.other.secondary.vsprimary">
     3299        <title>Primary vs. secondary storage</title>
     3300        <para>
     3301          BASE has support for storing files in two locations, the primary storage and
     3302          the secondary storage. The primary storage is always disk-based and must be
     3303          accessible by the BASE server as a path on the file system. The path to the
     3304          primary storage is configured by the <varname>userfiles</varname> setting in the
     3305          <filename>base.config</filename> file. The primary storage is internal to
     3306          the core. Client applications don't get access to read or manipulate the
     3307          files directly from the file system.
     3308        </para>
     3309       
     3310        <para>
     3311          The secondary storage can be anything that can store files. It could, for
     3312          example, be another directory, a remote FTP server, or a tape based archiving
     3313          system. A file located in the secondary storage is not accessible by the
     3314          core, client applications or plug-ins. The secondary storage can only be accessed
     3315          by the secondary storage controller. The core (and client) applications uses
     3316          flags on the file items to handle the interaction with the secondary storage.
     3317        </para>
     3318       
     3319        <para>
     3320          Each file has an <property>action</property> attribute which default's to
     3321          <constant>File.Action.NOTHING</constant>. It can take two other values:
     3322        </para>
     3323       
     3324        <orderedlist>
     3325        <listitem>
     3326          <para>
     3327          <constant>File.Action.MOVE_TO_SECONDARY</constant>
     3328          </para>
     3329        </listitem>
     3330        <listitem>
     3331          <para>
     3332          <constant>File.Action.MOVE_TO_PRIMARY</constant>
     3333          </para>
     3334        </listitem>
     3335        </orderedlist>
     3336       
     3337        <para>
     3338          All files with the action attribute set to <constant>MOVE_TO_SECONDARY</constant>
     3339          should be moved to the secondary storage by the controller, and all files
     3340          with the action attribute set to <constant>MOVE_TO_PRIMARY</constant> should be
     3341          brought back to primary storage.
     3342        </para>
     3343       
     3344        <para>
     3345          The moving of files between primary and secondary storage doesn't happen
     3346          immediately. It is up to the server administrator to configure how often and
     3347          at what times the controller should check for files that should be moved.
     3348          This is configured by the <varname>secondary.storage.interval</varname>
     3349          and <varname>secondary.storage.time</varname> settings in the
     3350          <filename>base.config</filename> file.       
     3351        </para>
     3352      </sect3>
     3353     
     3354      <sect3 id="plugin_developer.other.secondary.interface">
     3355        <title>The SecondaryStorageController interface</title>
     3356       
     3357        <para>
     3358          All you have to do to create a secondary storage controller is to
     3359          create a class that implements the
     3360          <interfacename>net.sf.basedb.core.SecondaryStorageController</interfacename>
     3361          interface. In your <filename>base.config</filename> file you then specify the
     3362          class name in the <varname>secondary.storage.driver</varname> setting and it's
     3363          initialisation parameters in the <varname>secondary.storage.init</varname> setting.
     3364        </para>
     3365
     3366        <para>
     3367          Your class must have a public no-argument constructor.
     3368          The BASE application will create only one instance of the class for
     3369          lifetime of the BASE server. Here are the methods that you must implement:
     3370        </para>
     3371       
     3372        <variablelist>
     3373        <varlistentry>
     3374          <term>
     3375          <methodsynopsis language="java">
     3376            <modifier>public</modifier>
     3377            <void />
     3378            <methodname>init</methodname>
     3379            <methodparam>
     3380              <type>String</type>
     3381              <parameter>settings</parameter>
     3382            </methodparam>
     3383          </methodsynopsis>
     3384          </term>
     3385          <listitem>
     3386            <para>
     3387            This method is called just after the object has been created with it's argument
     3388            taken from the <varname>secondary.storage.init</varname> setting in your
     3389            <filename>base.config</filename> file. This method is only called once for
     3390            an object.
     3391            </para>
     3392          </listitem>
     3393        </varlistentry>
     3394        <varlistentry>
     3395          <term>
     3396          <methodsynopsis language="java">
     3397            <modifier>public</modifier>
     3398            <void />
     3399            <methodname>run</methodname>
     3400          </methodsynopsis>
     3401          </term>
     3402          <listitem>
     3403            <para>
     3404            This method is called whenever the core thinks it is time to do some
     3405            management of the secondary storage. How often the <methodname>run()</methodname>
     3406            method is called is controlled by the <varname>secondary.storage.interval</varname>
     3407            and <varname>secondary.storage.time</varname> settings in the
     3408            <filename>base.config</filename> file.
     3409            When this method is called the controller should:
     3410            </para>
     3411           
     3412            <itemizedlist>
     3413            <listitem>
     3414              <para>
     3415              Move all files which has <constant>action=MOVE_TO_SECONDARY</constant> to
     3416              the secondary storage. When the file has been moved call
     3417              <methodname>File.setLocation(Location.SECONDARY)</methodname> to tell the
     3418              core that the file is now in the secondary storage. You should also call
     3419              <methodname>File.setAction(File.Action.NOTHING)</methodname> to reset the
     3420              action attribute.
     3421              </para>
     3422            </listitem>
     3423           
     3424            <listitem>
     3425              <para>
     3426              Restore all files which has <constant>action=MOVE_TO_PRIMARY</constant>.
     3427              The core will set the location attribute automatically, but you should
     3428              call <methodname>File.setAction(File.Action.NOTHING)</methodname> to reset
     3429              the action attribute.
     3430              </para>
     3431            </listitem>
     3432           
     3433            <listitem>
     3434              <para>
     3435              Delete all files from the secondary storage that are not present
     3436              in the database with <constant>location=Location.SECONDARY</constant>.
     3437              This includes files which has been deleted and files that have been
     3438              moved offline or re-uploaded.
     3439              </para>
     3440            </listitem>
     3441           
     3442            </itemizedlist>
     3443           
     3444            <para>
     3445              As a final act the method should send a message to each user owning
     3446              files that has been moved from one location to the other. The message
     3447              should include a list of files that has been moved to the secondary
     3448              storage and a list of files moved from the secondary storage and a
     3449              list of files that has been deleted due to some of the reasons above.
     3450            </para>
     3451          </listitem>
     3452        </varlistentry>       
     3453       
     3454        <varlistentry>
     3455          <term>
     3456          <methodsynopsis language="java">
     3457            <modifier>public</modifier>
     3458            <void />
     3459            <methodname>close()</methodname>
     3460          </methodsynopsis>
     3461          </term>
     3462          <listitem>
     3463            <para>
     3464            This method is called when the server is closing down. After this the object
     3465            is never used again.
     3466            </para>
     3467          </listitem>
     3468        </varlistentry>
     3469        </variablelist>
     3470      </sect3>
     3471     
     3472      <sect3 id="plugin_developer.other.secondary.settings">
     3473        <title>Configuration settings</title>
     3474       
     3475        <para>
     3476        The configuration settings for the secondary storage controller is located in the
     3477        <filename>base.config</filename> file. Here is an overview of the settings.
     3478        For more information read <xref linkend="appendix.base.config" />.
     3479        </para>
     3480       
     3481        <variablelist>
     3482        <varlistentry>
     3483          <term><property>secondary.storage.driver</property></term>
     3484          <listitem>
     3485            <para>
     3486            The class name of the secondary storage plug-in.
     3487            </para>
     3488          </listitem>
     3489        </varlistentry>
     3490        <varlistentry>
     3491          <term><property>secondary.storage.init</property></term>
     3492          <listitem>
     3493            <para>
     3494             Initialisation parameters sent to the plug-in by calling the
     3495             <methodname>init()</methodname> method.
     3496            </para>
     3497          </listitem>
     3498        </varlistentry>
     3499        <varlistentry>
     3500          <term><property>secondary.storage.interval</property></term>
     3501          <listitem>
     3502            <para>
     3503             Interval in seconds between each execution of the secondary storage
     3504             controller plug-in.
     3505            </para>
     3506          </listitem>
     3507        </varlistentry>
     3508        <varlistentry>
     3509          <term><property>secondary.storage.time</property></term>
     3510          <listitem>
     3511            <para>
     3512              Time points during the day when the secondary storage controller plugin
     3513              should be executed.
     3514            </para>
     3515          </listitem>
     3516        </varlistentry>
     3517        </variablelist>
     3518      </sect3>
    33023519    </sect2>
    33033520   
Note: See TracChangeset for help on using the changeset viewer.