Changeset 3169


Ignore:
Timestamp:
Mar 7, 2007, 3:18:52 PM (15 years ago)
Author:
Johan Enell
Message:

checked with aspell

File:
1 edited

Legend:

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

    r3168 r3169  
    169169            <para>
    170170              If this method returns true the plugin can have different
    171               configurations, (ie.
     171              configurations, (i.e.
    172172              <classname>PluginConfiguration</classname>
    173173              ). Note that this method may return true even if the
     
    434434        <interfacename>InteractivePlugin</interfacename>
    435435        has three main tasks: tell a client application where the plugin should be plugged
    436         in, ask users for parameters, and validate and store those parameters. It requiers
    437         the impementation of four method.
     436        in, ask users for parameters, and validate and store those parameters. It requires
     437        the implementation of four method.
    438438      </para>
    439439      <variablelist>
     
    491491            </para>
    492492            <para>
    493               A typical implementation creates a static unmodifable
     493              A typical implementation creates a static unmodifiable
    494494              <classname>Set</classname>
    495495              which is returned by this method. It is important that the returned set
     
    640640                  <listitem>
    641641                    <para>
    642                       Used when an administator is initiating a configuration
     642                      Used when an administrator is initiating a configuration
    643643                      of the plugin.
    644644                    </para>
     
    667667            <example id="net.sf.basedb.core.plugin.InteractivePlugin.getRequestInformation_1">
    668668              <title>
    669                 When runing an import plugin it needs to ask for the file to import
     669                When running an import plugin it needs to ask for the file to import
    670670                from and if existing items should be updated or not
    671671              </title>
    672672              <programlisting>
    673673// The complete request information
    674 private RequestInformation configureJob;
     674private RequestInformation configure Job;
    675675
    676676// The parameter that asks for a file to import from
    677 private PluginParameter&lt;File&gt; fileParameter;
     677private PluginParameter&lt;File&gt; file Parameter;
    678678
    679679// The parameter that asks if existing items should be updated or not
     
    769769            <note>
    770770              <para>
    771                 Most parameter types include support for suppying a predefined list
     771                Most parameter types include support for supplying a predefined list
    772772                of options to select from. In that case the list will be displayed
    773773                as a drop-down list for the user, otherwise a free input field is
     
    887887        </varlistentry>
    888888        <varlistentry>
    889           <term><methodsynopsis language="java">
    890               <methodname></methodname>
    891               <methodparam>
    892                 <parameter></parameter>
    893               </methodparam>
    894             </methodsynopsis></term>
     889          <term>
     890            <methodsynopsis language="java">
     891              <modifier>public</modifier>
     892              <void />
     893              <methodname>configure</methodname>
     894              <methodparam>
     895                <type>GuiContext</type>
     896                <parameter>context</parameter>
     897              </methodparam>
     898              <methodparam>
     899                <type>Request</type>
     900                <parameter>request</parameter>
     901              </methodparam>
     902              <methodparam>
     903                <type>Response</type>
     904                <parameter>response</parameter>
     905              </methodparam>
     906            </methodsynopsis>
     907          </term>
    895908          <listitem>
    896             <para></para>
    897            
     909            <para>
     910              Sends parameter values entered by the user for processing by the plugin.
     911              Typically the plugin should validate that the parameter values are
     912              correct and then store them in database.
     913            </para>
     914            <para>
     915              No validation is done by the core, except converting the input to the
     916              correct object type, i.e. if the parameter asked for a
     917              <classname>Float</classname>
     918              the input string is parsed and converted to a Float. If you have
     919              extended the
     920              <classname>AbstractPlugin</classname>
     921              class it is very easy to validate the parameters using it's
     922              <methodname>validateRequestParameters</methodname>
     923              () method. This method takes the same list of
     924              <classname>PluginParameter</classname>
     925              's used in the
     926              <classname>RequestInformation</classname>
     927              object and uses that information for validation. It returns null or a
     928              list of
     929              <exceptionname>Throwable</exceptionname>
     930              .
     931            </para>
     932            <para>
     933              When the parameters have been validated they need to be stored. Once
     934              again, it is very easy if you use one of the
     935              <classname>AbstractPlugin.</classname>
     936              <methodname>storeValue</methodname>
     937              () or
     938              <classname>AbstractPlugin.</classname>
     939              <methodname>storeValues</methodname>
     940              () methods.
     941            </para>
     942            <para>
     943              The configure method works much like the
     944              <classname>Plugin.</classname>
     945              <methodname>run</methodname>
     946              () method. It must return the result in the
     947              <classname>Response</classname>
     948              object, i.e. it shouldn't trow any exceptions.
     949            </para>
     950            <example id="net.sf.basedb.core.plugin.InteractivePlugin.configure">
     951              <title>
     952                Configuration implementation building on the examples above
     953              </title>
     954              <programlisting>
     955public void configure(GuiContext context, Request request, Response response)
     956{
     957   String command = request.getCommand();
     958   try
     959   {
     960      if (command.equals(Request.COMMAND_CONFIGURE_PLUGIN))
     961      {
     962         // TODO
     963      }
     964      else if (command.equals(Request.COMMAND_CONFIGURE_JOB))
     965      {
     966         // Validate user input
     967         List&lt;Throwable&gt; errors =
     968            validateRequestParameters(getConfigureJob().getParameters(), request);
     969         if (errors != null)
     970         {
     971            response.setError(errors.size() +
     972               " invalid parameter(s) were found in the request", errors);
     973            return;
     974         }
     975         
     976         // Store user input
     977         storeValue(job, request, fileParameter);
     978         storeValue(job, request, updateExistingParameter);
     979         
     980         // We are happy and done
     981         response.setDone("Job configuration complete", Job.ExecutionTime.SHORT);
     982         // TODO - check file size to make a better estimate of execution time
     983      }
     984   }
     985   catch (Throwable ex)
     986   {
     987      response.setError(ex.getMessage(), Arrays.asList(ex));
     988   }
     989}
     990              </programlisting>
     991            </example>
     992            <para>
     993              Note that the
     994              <methodname>setDone</methodname>
     995              () has a second parameter
     996              <classname>Job.ExecutionTime</classname>
     997              . It is an indication about how long time it will take to execute the
     998              plugin. This is of interest for job queue managers which probably
     999              doesn't want to start too many long-running jobs at the same time
     1000              blocking the entire system. Please try to use this parameter wisely and
     1001              not use the
     1002              <constant>SHORT</constant>
     1003              value out of old habit all the time.
     1004            </para>
     1005            <para>
     1006              The response also has a
     1007              <methodname>setContinue</methodname>
     1008              () method which tells the core that the plugin needs more parameters,
     1009              i.e. the core will then call
     1010              <methodname>getRequestInformation</methodname>
     1011              () again with the new command, let the user enter values, and the call
     1012              <methodname>configure</methodname>
     1013              () with the new values. This process is repeated until the plugin
     1014              reports that it is done or an error occurs.
     1015            </para>
     1016            <para>
     1017              An important note is that during this iteration it is the same instance
     1018              of the plugin that is used. However, no parameter values are stored in
     1019              the database until
     1020              <methodname>setDone</methodname>
     1021              () is called. Then, the plugin instance is usually discarded. The
     1022              execution of the plugin happens in a new instance and maybe on a
     1023              different server.
     1024            </para>
     1025            <tip>
     1026                <para>
     1027                  You don't have to store all values the plugin asked for in the
     1028                  first place. You may even choose to store different values than
     1029                  those that were entered. For example, you might ask for the mass
     1030                  and height of a person and then only store the body mass index,
     1031                  which is calculated from those values.
     1032                </para>
     1033            </tip>
    8981034          </listitem>
    8991035        </varlistentry>
Note: See TracChangeset for help on using the changeset viewer.