Ignore:
Timestamp:
Oct 26, 2011, 10:47:20 AM (11 years ago)
Author:
Nicklas Nordborg
Message:

References #1590: Documentation cleanup

Updated diagram and text about how the Extensions API is designed.

File:
1 edited

Legend:

Unmodified
Added
Removed

  • trunk/doc/src/docbook/developer/base_api.xml

    r5818 r5826  
    32433243        part and a web client specific part. The core part can be found in the
    32443244        <package>net.sf.basedb.util.extensions</package> package and it's sub-packages,
    3245         and consists of three sub-parts:
     3245        and consists of two sub-parts:
    32463246      </para>
    32473247     
    … …  
    32493249      <listitem>
    32503250        <para>
     3251        An <classname docapi="net.sf.basedb.util.extensions.manager">ExtensionsManager</classname>
     3252        that keeps track of the JAR files on the file system containing extensions code.
     3253        The manager can detect new, updated and deleted files and is used to
     3254        load metadata information about the extensions and register them in the <classname
     3255        docapi="net.sf.basedb.util.extensions">Registry</classname> so that they can be used.
     3256        The manager is also used to install plug-ins.
     3257        </para>
     3258      </listitem>
     3259
     3260      <listitem>
     3261        <para>
    32513262        A set of interface definitions which forms the core of the Extensions API.
    32523263        The interfaces defines, for example, what an <interfacename
    3253         docapi="net.sf.basedb.util.extensions">Extension</interfacename> is and
     3264        docapi="net.sf.basedb.util.extensions">Extension</interfacename> is,
    32543265        what an <interfacename
    3255         docapi="net.sf.basedb.util.extensions">ActionFactory</interfacename> should do.
    3256         </para>
    3257       </listitem>
    3258      
    3259       <listitem>
    3260         <para>
    3261         A <classname docapi="net.sf.basedb.util.extensions">Registry</classname> that is
    3262         used to keep track of installed extensions. The registry also provides
    3263         functionality for invoking and using the extensions.
    3264         </para>
    3265       </listitem>
    3266      
    3267       <listitem>
    3268         <para>
    3269         Utility classes that are useful when implementation a client application
    3270         that can be extendable. The most useful example is the <classname
    3271         docapi="net.sf.basedb.util.extensions.xml">XmlLoader</classname> which can
    3272         read extension definitions from XML files and create the proper factories,
    3273         etc.
     3266        docapi="net.sf.basedb.util.extensions">ActionFactory</interfacename> should do
     3267        and a few other things.
    32743268        </para>
    32753269      </listitem>
    32763270      </itemizedlist>
    32773271     
     3272      <para>
     3273        Let's start by looking at the extensions manager and related classes.
     3274      </para>
     3275     
     3276      <figure id="extensions_api.figures.manager">
     3277        <title>The extensions manager</title>
     3278        <screenshot>
     3279          <mediaobject>
     3280            <imageobject>
     3281              <imagedata
     3282                align="center"
     3283                fileref="figures/uml/corelayer.extensions_manager.png" format="PNG" />
     3284            </imageobject>
     3285          </mediaobject>
     3286        </screenshot>
     3287      </figure>
     3288     
     3289      <para>
     3290      The BASE application is using a single manager and a single registry (handled by the
     3291      <classname docapi="net.sf.basedb.core">Application</classname>) class.
     3292      The manager has been configured to look for extensions and plug-ins in the directory
     3293      specified by the <property>plugins.dir</property> setting in
     3294      <filename>base.config</filename>. Theoretically, a single manager can handle
     3295      multiple directories, but we do not use that feature. The BASE core also
     3296      include some special files that are added with the <methodname>addURI()</methodname>
     3297      method. They contain definitions for the core extensions and core plug-ins
     3298      and are shipped as XML files that reside inside the BASE core JAR files.
     3299      </para>
     3300     
     3301      <para>
     3302      The <methodname>ExtensionsManager.scanForChanges()</methodname>
     3303      method is called to initiate a check for new, updated and deleted files. The
     3304      manager uses the <classname docapi="net.sf.basedb.util.extensions.xml">XmlLoader</classname>
     3305      to find information about each JAR or XML file it find in the directory.
     3306      After the scan, the <methodname>ExtensionsManager.getFiles()</methodname>
     3307      method can be used to find more information about each individual file, for example,
     3308      if it is a new or modified file, if it contains valid extension definitions and
     3309      information about the author, etc. This information is used by the installation
     3310      wizard in the web client to display a dialog were the user can select which extensions
     3311      to intall. See <xref linkend="plugins.figures.installwizard" />.
     3312      Note that no installation or other actions take place at this stage.
     3313      </para>
     3314     
     3315      <para>
     3316      The <methodname>ExtensionsManager.processFiles()</methodname> method is called to actually do
     3317      something. It needs an <interfacename docapi="net.sf.basedb.util.extensions.manager"
     3318      >ExtensionsFileProcessor</interfacename> implementation as an argument. As you can see
     3319      in the diagram above there are multiple implementations (all are not
     3320      shown in the diagram), each with a very specific task.  A processor is usually
     3321      also paired with a filter to target it at files that fulfil some criteria, for example,
     3322      only at valid extension files that has been updated. Typically, the
     3323      <methodname>ExtensionsManager.processFiles()</methodname> method need to be
     3324      called multiple times with different processor implementations to perform a full
     3325      installation of an extension or plug-in. Here is a list of the various processors
     3326      currently in use in BASE.
     3327      </para>
     3328     
     3329      <variablelist>
     3330        <varlistentry>
     3331          <term><classname docapi="net.sf.basedb.util.extensions.manager.processor"
     3332            >RegisterExtensionsProcessor</classname></term>
     3333          <listitem>
     3334          <para>
     3335            Is used to register
     3336            extensions with the registry. Can be paired with different filters
     3337            depending on when it is used. At BASE startup an <classname
     3338            docapi="net.sf.basedb.util.extensions.manager.filter">InstalledFilter</classname>
     3339            is used so that only installed extensions are registered.
     3340          </para>
     3341          </listitem>
     3342        </varlistentry>
     3343
     3344        <varlistentry>
     3345          <term><classname docapi="net.sf.basedb.util.extensions.manager.processor"
     3346            >UnregisterExtensionsProcessor</classname></term>
     3347          <listitem>
     3348          <para>
     3349            Is used to unregister
     3350            extensions when a file has been deleted. This should always be paired with
     3351            for example, a <classname docapi="net.sf.basedb.util.extensions.manager.filter"
     3352            >DeletedFilter</classname>.
     3353          </para>
     3354          </listitem>
     3355        </varlistentry>
     3356
     3357        <varlistentry>
     3358          <term><classname docapi="net.sf.basedb.util.extensions.manager.processor"
     3359            >UnregisterExtensionsProcessor</classname></term>
     3360          <listitem>
     3361          <para>
     3362            Is used to unregister
     3363            extensions when a file has been deleted. This should always be paired with
     3364            for example, a <classname docapi="net.sf.basedb.util.extensions.manager.filter"
     3365            >DeletedFilter</classname>.
     3366          </para>
     3367          </listitem>
     3368        </varlistentry>
     3369
     3370        <varlistentry>
     3371          <term><classname docapi="net.sf.basedb.util.extensions.manager.processor"
     3372            >ExtractResourcesProcessor</classname></term>
     3373          <listitem>
     3374          <para>
     3375            Is used to extract
     3376            files from the JAR file to a local directory. This is currently used
     3377            by the web client to extract JSP files, images, etc. that are
     3378            needed by web client extensions.
     3379          </para>
     3380          </listitem>
     3381        </varlistentry>
     3382
     3383        <varlistentry>
     3384          <term><classname docapi="net.sf.basedb.util.extensions.manager.processor"
     3385            >DeleteResourcesProcessor</classname></term>
     3386          <listitem>
     3387          <para>
     3388            The opposite of
     3389            <classname>ExtractResourcesProcessor</classname>.
     3390          </para>
     3391          </listitem>
     3392        </varlistentry>
     3393
     3394        <varlistentry>
     3395          <term><classname docapi="net.sf.basedb.util.extensions.manager.processor"
     3396            >PluginInstallationProcessor</classname></term>
     3397          <listitem>
     3398          <para>
     3399            Is used to install and register plug-ins.
     3400          </para>
     3401          </listitem>
     3402        </varlistentry>
     3403       
     3404        <varlistentry>
     3405          <term><classname docapi="net.sf.basedb.util.extensions.manager.processor"
     3406            >DisablePluginsProcessor</classname></term>
     3407          <listitem>
     3408          <para>
     3409            Is used to disable plug-ins
     3410            from extensions that have been removed.
     3411          </para>
     3412          </listitem>
     3413        </varlistentry>
     3414       
     3415        <varlistentry>
     3416          <term><classname docapi="net.sf.basedb.util.extensions.manager.processor"
     3417            >MarkAsProcessedProcessor</classname></term>
     3418       
     3419          <listitem>
     3420          <para>
     3421            This is usually the final
     3422            processor that is called and reset the timestamp on all processed files
     3423            so that the next time <methodname>ExtensionsManger.scanForChanges()</methodname>
     3424            is called it will know what has been modified.
     3425          </para>
     3426          </listitem>
     3427        </varlistentry>
     3428      </variablelist>
     3429     
     3430      <note>
     3431        <para>
     3432        This list contains the core processors only. The web client part
     3433        is using some additional processors to perform, for example, servlet
     3434        registration.
     3435        </para>
     3436      </note>
     3437     
     3438      <para>
     3439      The result of the processing can be collected with a <classname
     3440      docapi="net.sf.basedb.util.extensions.manager">ProcessResults</classname> object
     3441      and is then displayed to the user as in <xref linkend="plugins.figures.installresults" />.
     3442      All of the above is only used when BASE is starting up and initializing the extensions
     3443      system or when the server administrator is performing a manual installation or update.
     3444      The next diagram shows the part of the extensions system that is used when
     3445      actually using the extensions for what they are intended to do (the web client adds some
     3446      extra features to this as well, but that is discussed later).
     3447      </para>
     3448     
     3449     
    32783450      <figure id="extensions_api.figures.core">
    3279         <title>The core part of the Extensions API</title>
     3451        <title>The main Extensions API</title>
    32803452        <screenshot>
    32813453          <mediaobject>
    … …  
    33993571        The web client specific parts of the Extensions API can be found
    34003572        in the <package>net.sf.basedb.client.web.extensions</package> package
    3401         and it's subpackages. The top-level package contains classes used to
    3402         administrate the extension system. Here is for example the
    3403         <classname docapi="net.sf.basedb.client.web.extensions">ExtensionsControl</classname>
    3404         class which is the master controller for the web client extensions. It:
    3405       </para>
    3406      
    3407       <itemizedlist>
    3408       <listitem>
    3409         <para>
    3410         Keeps track of installed extensions and which JAR or XML file they are
    3411         installed from.
    3412         </para>
    3413       </listitem>
    3414      
    3415       <listitem>
    3416         <para>
    3417         Can, manually or automatically, find and install new or
    3418         updated extensions and uninstall deleted extensions.
    3419         </para>
    3420       </listitem>
    3421      
    3422       <listitem>
    3423         <para>
    3424         Adds permission control to the extension system, so that only an
    3425         administrator is allowed to change settings, enable/disable extensions,
    3426         etc.
    3427         </para>
    3428       </listitem>
    3429       </itemizedlist>
     3573        and it's subpackages. The top-level package contains the
     3574        <classname docapi="net.sf.basedb.client.web.extensions">ExtensionsControl</classname>
     3575        class which is used to administrate the extension system. It is more or
     3576        less a wrapper around the <classname
     3577        docapi="net.sf.basedb.util.extensions.manager">ExtensionsManager</classname>
     3578        provided by the core, but adds permission control and a few other things.
     3579      </para>
    34303580     
    34313581      <para>
    … …  
    34343584        For example, we recommend that all action factories extend the <classname
    34353585        docapi="net.sf.basedb.client.web.extensions">AbstractJspActionFactory</classname>
    3436         class.
     3586        class. All web client extension points use the <classname
     3587        docapi="net.sf.basedb.client.web.extensions">JspContext</classname> class instead of
     3588        <classname docapi="net.sf.basedb.util.extensions">ClientContext</classname>.
     3589        The JSP context provides some extra information about the current request.
    34373590      </para>
    34383591     
    … …  
    34433596        package, for example, contains classes that are/can be used for extensions
    34443597        adding menu items to the <menuchoice><guimenu>Extensions</guimenu></menuchoice>
    3445         menu.
     3598        menu. See <xref linkend="extensions_developer.base_extension_points" />
     3599        for more information about the extension points defined by BASE.
    34463600      </para>
    34473601     
    … …  
    34703624        Initialise the extensions system by calling
    34713625        <methodname>ExtensionsControl.init()</methodname>. This will result in
    3472         an initial scan for installed extensions, which is equivalent to doing
    3473         a manual scan with the force update setting to false. This means that
     3626        an initial scan for installed extensions. This means that
    34743627        the extension system is up an running as soon as the first user log's
    3475         in to BASE.
    3476         </para>
     3628        in to BASE. The processing scheme is slightly different from what is done
     3629        when the core is setting up the initial manager. The major additions are:
     3630        </para>
     3631       
     3632        <itemizedlist>
     3633          <listitem>
     3634            <para>
     3635            The <classname docapi="net.sf.basedb.client.web.extensions"
     3636            >LoadServletsProcessor</classname> is used to load servlets that
     3637            has been defined in <filename>META-INF/servlets.xml</filename>.
     3638            </para>
     3639          </listitem>
     3640          <listitem>
     3641            <para>
     3642            The <classname docapi="net.sf.basedb.util.extensions.manager.processor"
     3643            >ExtractResourcesProcessor</classname> is used to extract all files
     3644            from <filename>resources/*</filename> in the JAR file to
     3645            <filename>www/extensions/jar-name.jar/</filename>
     3646            in Tomcat's web application directory.
     3647            </para>
     3648          </listitem>
     3649        </itemizedlist>
     3650       
    34773651      </listitem>
    34783652     
    … …  
    34843658        will extract the name of the extension's JAR file from the
    34853659        URL, get the corresponding <classname
    3486         docapi="net.sf.basedb.client.web.extensions">ExtensionsFile</classname>
    3487         and <classname docapi="net.sf.basedb.client.web.extensions">ServletWrapper</classname>
     3660        docapi="net.sf.basedb.client.web.extensions">ServletWrapper</classname>
    34883661        and then invoke the custom servlet. More information can be found in
    34893662        <xref linkend="extensions_developer.servlets" />.
    … …  
    35133686        To get information about the installed extensions, 
    35143687        change settings, enabled/disable extensions, performing a manual
    3515         scan, etc. use the <methodname>ExtensionsControl.get()</methodname>
     3688        installation, etc. use the <methodname>ExtensionsControl.get()</methodname>
    35163689        method. This will create a permission-controlled object. All
    35173690        users has read permission, administrators has write permission.
    … …  
    35343707        The <classname docapi="net.sf.basedb.clients.web.extensions">XJspCompiler</classname>
    35353708        is mapped to handle the compilation <code>.xjsp</code> files
    3536         which are regular JSP files with a different extension. This feature is
    3537         experimental and requires installing an extra JAR into Tomcat's lib
     3709        which are regular JSP files with a different extension. The difference is that
     3710        the XJSP compiler include the extension's JAR file on the class path, which
     3711        means that the JSP file can use classes that would otherwise be impossible.
     3712        This feature is experimental and requires installing an extra JAR into Tomcat's lib
    35383713        directory. See <xref linkend="plugins.installation.xjspcompiler" /> for
    35393714        more information.
Note: See TracChangeset for help on using the changeset viewer.