Changeset 3175 for trunk/doc/src/docbook


Ignore:
Timestamp:
Mar 8, 2007, 10:57:25 AM (16 years ago)
Author:
Johan Enell
Message:

fixed linkes
fixed some methodname tags

Location:
trunk/doc/src/docbook
Files:
2 edited

Legend:

Unmodified
Added
Removed

  • trunk/doc/src/docbook/admindoc/plugin_installation.xml

    r3161 r3175  
    2828
    2929<chapter id="plugin_installation">
    30   <title>Installing plugins</title>
    31     <sect1>
    32       <title></title>
    33       <para></para>
    34     </sect1>
     30  <title id="plugin_installation.title">Installing plugins</title>
     31
     32  <para>
     33    We recommend that each plugin or group of related plugins are compiled separately. To be
     34    able to use the plugin it must be put in a JAR file. Place the JAR file on the server
     35    <emphasis>outside</emphasis>
     36    the web servers classpath, ie. not in the
     37    <filename class="directory">WEB-INF/lib</filename>
     38    . Our recommendation is to place the plugin JAR in
     39    <filename class="directory">
     40      <replaceable>&lt;base-dir&gt;</replaceable>
     41      /plugins/
     42      <replaceable>&lt;name-of-plugin&gt;</replaceable>
     43      /
     44    </filename>
     45  </para>
     46
     47  <para>
     48    The main benefit from placing the JAR file outside the classpath is that
     49    Base uses it's own classloader that supports unloading of the classes as well.
     50    This means that you may replace the JAR file with a new version without
     51    restarting the web server.
     52  </para>
     53 
     54  <para>
     55    Then, to install the plugin log in a an administrator and go to the
     56    <menuchoice>
     57      <guimenu>Administrate</guimenu>
     58      <guisubmenu>Plugins</guisubmenu>
     59      <guimenuitem>Definitions</guimenuitem>
     60    </menuchoice>
     61    page. Click the
     62    <guibutton>New</guibutton>
     63    button and enter the class name and the path to the JAR file in the form that opens in the
     64    popup window.
     65  </para>
     66
     67  <para>
     68    When you click save, the Base class loader will load the specified JAR file and class and
     69    check that it implements the
     70    <interfacename>Plugin</interfacename>
     71    interface. Then, it creates an instance of that class, calls
     72    <methodname>Plugin.getAbout()</methodname>
     73    and
     74    <methodname>Plugin.getMainType()</methodname>
     75    . If it is an
     76    <interfacename>InteractivePlugin</interfacename>
     77    it will also call
     78    <methodname>InteractivePlugin.getGuiContexts()</methodname>
     79    . This information is stored in the database.
     80  </para>
     81
     82  <para>
     83    The installation will do one more thing. It will check which other interfaces the plugin
     84    implements and check against the list of registered
     85    <classname>PluginType</classname>
     86    s. The
     87    <classname>PluginType</classname>
     88    system has not really been put into use yet. The core defines the
     89    <interfacename>AutoDetectingImporter</interfacename>
     90    which can be used for all import plugins that supports automatic detection of file formats.
     91    Read more about this in the
     92    <xref linkend="plugin_developer.import_plugins"/>
     93    chapter.
     94  </para>
     95
     96
     97  <para>
     98    Now the administrator may continue by creating a new configuration for the plugin (assuming
     99    that is an
     100    <interfacename>InteractivePlugin</interfacename>
     101    ). When the administrator starts the configuration sequence the following will happen:
     102  </para>
     103
     104  <itemizedlist>
     105    <listitem>
     106      <simpara>The core creates a new instance of the plugin.</simpara>
     107    </listitem>
     108    <listitem>
     109      <simpara>
     110        Call the
     111        <methodname>Plugin.init</methodname>
     112        () method.
     113      </simpara>
     114    </listitem>
     115    <listitem>
     116      <simpara>
     117        Call the
     118        <methodname>InteractivePlugin.getRequestInformation()</methodname>
     119        method, with
     120        <varname>command</varname>
     121        <literal>=</literal>
     122        <constant>Request.COMMAND_CONFIGURE_PLUGIN</constant>
     123        and a null
     124        <classname>GuiContext</classname>
     125        .
     126      </simpara>
     127    </listitem>
     128    <listitem>
     129      <simpara>Display the list of parameters and let the user enter values.</simpara>
     130    </listitem>
     131    <listitem>
     132      <simpara>
     133        Call
     134        <methodname>InteractivePlugin.configure()</methodname>
     135        .
     136      </simpara>
     137    </listitem>
     138    <listitem>
     139      <simpara>
     140        If the plugin wants more parameters the above two steps are repeated but with the
     141        command returned in the response. Note! Be careful so you don't create infinite
     142        loops.
     143      </simpara>
     144    </listitem>
     145    <listitem>
     146      <simpara>
     147        If the plugin reports that it is done,
     148        <methodsynopsis>
     149          <methodname>done</methodname>
     150          <void/>
     151        </methodsynopsis>
     152        <methodname>Plugin.done()</methodname>
     153        is called and the plugin instance is discarded.
     154      </simpara>
     155    </listitem>
     156  </itemizedlist>
     157
     158  <para>
     159    The steps for creating a new job follows the same procedure except that the first command is
     160    <classname>Request.</classname>
     161    <constant>COMMAND_CONFIGURE_JOB</constant>
     162    and the
     163    <classname>GuiContext</classname>
     164    isn't null.
     165  </para>
     166
    35167</chapter>

  • trunk/doc/src/docbook/developerdoc/plugin_developer.xml

    r3170 r3175  
    335335              failed. Not setting a response is considered a failure by the core. From
    336336              the run method it is only allowed to use the
    337               <methodname>setDone</methodname>
    338               () or the
    339               <methodname>setError</methodname>
    340               () methods.
     337              <methodname>setDone()</methodname>
     338              or the
     339              <methodname>setError()</methodname>
     340              methods.
    341341            </para>
    342342            <example id="net.sf.basedb.core.plugin.Plugin.run">
    … …  
    344344                Here is a skeleton that we recommend each plugin to use in it's
    345345                implementation of the
    346                 <methodname>run</methodname>
     346                <methodname>run()</methodname>
    347347                method
    348348              </title>
    … …  
    397397                contains an implementation of this method which simply sets the
    398398                parameters passed to the
    399                 <methodname>init</methodname>
     399                <methodname>init()</methodname>
    400400                method to null
    401401              </title>
    … …  
    459459              <classname>net.sf.basedb.core.Item</classname>
    460460              enumeration and the type is either
    461               <classname>Type.LIST</classname>
     461              <constant>Type.LIST</constant>
    462462              or
    463               <classname>Type.ITEM</classname>
     463              <constant>Type.ITEM</constant>
    464464              .
    465465            </para>
    … …  
    467467              For example, the
    468468              <varname>GuiContext</varname>
    469               = (
     469              <literal>= (</literal>
    470470              <constant>Item.REPORTER</constant>
    471               ,
     471              <literal>,</literal>
    472472              <constant>Type.LIST</constant>
    473               ) tells a client application that this plugin can be plugged in whenever
    474               a list of reporters is displayed. The
     473              <literal>)</literal>
     474              tells a client application that this plugin can be plugged in whenever a
     475              list of reporters is displayed. The
    475476              <varname>GuiContext</varname>
    476477              = (
    … …  
    910911              <classname>AbstractPlugin</classname>
    911912              class it is very easy to validate the parameters using it's
    912               <methodname>validateRequestParameters</methodname>
    913               () method. This method takes the same list of
     913              <methodname>validateRequestParameters()</methodname>
     914              method. This method takes the same list of
    914915              <classname>PluginParameter</classname>
    915916              's used in the
    … …  
    923924              When the parameters have been validated they need to be stored. Once
    924925              again, it is very easy if you use one of the
    925               <classname>AbstractPlugin.</classname>
    926               <methodname>storeValue</methodname>
    927               () or
    928               <classname>AbstractPlugin.</classname>
    929               <methodname>storeValues</methodname>
    930               () methods.
     926              <methodname>AbstractPlugin.storeValue()</methodname>
     927              or
     928              <methodname>AbstractPlugin.storeValues()</methodname>
     929              methods.
    931930            </para>
    932931            <para>
    933932              The configure method works much like the
    934               <classname>Plugin.</classname>
    935               <methodname>run</methodname>
    936               () method. It must return the result in the
     933              <methodname>Plugin.run()</methodname>
     934              method. It must return the result in the
    937935              <classname>Response</classname>
    938936              object, i.e. it shouldn't trow any exceptions.
    … …  
    982980            <para>
    983981              Note that the
    984               <methodname>setDone</methodname>
    985               () has a second parameter
     982              <methodname>setDone()</methodname>
     983              has a second parameter
    986984              <classname>Job.ExecutionTime</classname>
    987985              . It is an indication about how long time it will take to execute the
    … …  
    990988              blocking the entire system. Please try to use this parameter wisely and
    991989              not use the
    992               <constant>SHORT</constant>
     990              <constant>Job.ExecutionTime.SHORT</constant>
    993991              value out of old habit all the time.
    994992            </para>
    995993            <para>
    996994              The response also has a
    997               <methodname>setContinue</methodname>
    998               () method which tells the core that the plugin needs more parameters,
     995              <methodname>setContinue()</methodname>
     996              method which tells the core that the plugin needs more parameters,
    999997              i.e. the core will then call
    1000               <methodname>getRequestInformation</methodname>
    1001               () again with the new command, let the user enter values, and the call
    1002               <methodname>configure</methodname>
    1003               () with the new values. This process is repeated until the plugin
     998              <methodname>getRequestInformation()</methodname>
     999              again with the new command, let the user enter values, and the call
     1000              <methodname>configure()</methodname>
     1001              with the new values. This process is repeated until the plugin
    10041002              reports that it is done or an error occurs.
    10051003            </para>
    … …  
    10081006              of the plugin that is used. However, no parameter values are stored in
    10091007              the database until
    1010               <methodname>setDone</methodname>
    1011               () is called. Then, the plugin instance is usually discarded. The
    1012               execution of the plugin happens in a new instance and maybe on a
    1013               different server.
     1008              <methodname>setDone()</methodname>
     1009              is called. Then, the plugin instance is usually discarded. The execution
     1010              of the plugin happens in a new instance and maybe on a different server.
    10141011            </para>
    10151012            <tip>
    … …  
    10591056    </sect2>
    10601057   
    1061     <sect2 id="plugin_developer.organize.build">
     1058    <sect2 id="plugin_developer.organize.ant">
    10621059      <title>Ant build file</title>
    10631060      <para>
    … …  
    11251122    </sect2>
    11261123     
    1127     <sect2>
     1124    <sect2 id="plugin_developer.organize.build">
    11281125      <title>Building the plugin</title>
    11291126      <para>
    … …  
    11381135        files (if any). Place all files together in the same directory. Then follow the
    11391136        instructions in chapter
    1140         <link linkend="plugin_installation" endterm="plugin_installation.title"></link>
     1137        <xref linkend="plugin_installation" />
    11411138        .
    11421139      </para>
    … …  
    12381235  </sect1>
    12391236
     1237  <sect1 id="plugin_developer.import_plugins">
     1238    <title id="plugin_developer.import_plugins.title">Plugins for importing data</title>
     1239    <para></para>
     1240  </sect1>
     1241
    12401242</chapter>
Note: See TracChangeset for help on using the changeset viewer.