Changeset 3406


Ignore:
Timestamp:
May 30, 2007, 11:52:03 AM (14 years ago)
Author:
Nicklas Nordborg
Message:

References #551. Added section about export plug-ins

File:
1 edited

Legend:

Unmodified
Added
Removed

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

    r3394 r3406  
    16561656  <sect1 id="plugin_developer.export">
    16571657    <title>Export plug-ins</title>
    1658     <para>TODO</para>
     1658   
     1659    <para>
     1660      Export plug-ins are plug-ins that takes data from BASE, and
     1661      prepares it for use with some external entity. Usually this
     1662      means that data is taken from the database and put into a file
     1663      with some well-defined file format.
     1664      An export plug-in should return <constant>MainType.EXPORT</constant> from
     1665      the <methodname>Plugin.getMainType()</methodname> method.
     1666    </para>
    16591667   
    16601668    <sect2 id="plugin_developer.export.download">
    16611669      <title>Immediate download of exported data</title>
    1662       <para>TODO</para>
     1670      <para>
     1671        An export plug-in may want to give the user a choice
     1672        between saving the exported data in the BASE file system
     1673        or to download it immediately to the client computer. With the basic
     1674        plug-in API the second option is not possible. The
     1675        <interfacename>ImmediateDownloadExporter</interfacename> is an
     1676        interface that extends the <interfacename>Plugin</interfacename>
     1677        interface to provide this functionality. If your export
     1678        plug-in wants to provide immediate download functionality it must
     1679        implement the <interfacename>ImmediateDownloadExporter</interfacename>
     1680        interface.
     1681      </para>
     1682     
     1683      <sect3 id="plugin_developer.export.immediatedownloadexporter">
     1684      <title>The ImmediateDownloadExporter interface</title>
     1685      <variablelist>
     1686      <varlistentry>
     1687        <term>
     1688          <methodsynopsis language="java">
     1689            <modifier>public</modifier>
     1690            <void/>
     1691            <methodname>doExport</methodname>
     1692            <methodparam>
     1693              <type>ExportOutputStream</type>
     1694              <parameter>out</parameter>
     1695            </methodparam>
     1696            <methodparam>
     1697              <type>ProgressReporter</type>
     1698              <parameter>progress</parameter>
     1699            </methodparam>
     1700          </methodsynopsis>
     1701        </term>
     1702        <listitem>
     1703          <para>
     1704          Perform the export. The plug-in should write the
     1705          exported data to the <varname>out</varname> stream.
     1706          If the <varname>progress</varname> parameter isn't null,
     1707          the progress should be reported at regular interval in the
     1708          same manner as in the <methodname>Plugin.run()</methodname>
     1709          method.
     1710          </para>
     1711        </listitem>
     1712      </varlistentry>
     1713      </variablelist>
     1714     
     1715      </sect3>
     1716     
     1717      <sect3 id="plugin_developer.export.exportoutputstream">
     1718      <title>The ExportOutputStream class</title>
     1719     
     1720      <para>
     1721        The <classname>ExportOutputStream</classname> is extends
     1722        <classname>java.io.OutputStream</classname>. Use the regular
     1723        <methodname>write()</methodname> methods to write data to it.
     1724        It also has three additional methods, which are used to generate
     1725        HTTP response headers.
     1726      </para>
     1727     
     1728      <note>
     1729        <para>
     1730        These methods must be called before starting to write data to
     1731        the <varname>out</varname> stream.
     1732        </para>
     1733      </note>
     1734     
     1735      <variablelist>
     1736      <varlistentry>
     1737        <term>
     1738          <methodsynopsis language="java">
     1739            <modifier>public</modifier>
     1740            <void/>
     1741            <methodname>setContentLength</methodname>
     1742            <methodparam>
     1743              <type>long</type>
     1744              <parameter>contentLength</parameter>
     1745            </methodparam>
     1746          </methodsynopsis>
     1747        </term>
     1748        <listitem>
     1749          <para>
     1750          Set the total size of the exported data (if known).
     1751          </para>
     1752        </listitem>
     1753      </varlistentry>
     1754      <varlistentry>
     1755        <term>
     1756          <methodsynopsis language="java">
     1757            <modifier>public</modifier>
     1758            <void/>
     1759            <methodname>setMimeType</methodname>
     1760            <methodparam>
     1761              <type>String</type>
     1762              <parameter>mimeType</parameter>
     1763            </methodparam>
     1764          </methodsynopsis>
     1765        </term>
     1766        <listitem>
     1767          <para>
     1768          Set the MIME type of the file that is beeing generated.
     1769          </para>
     1770        </listitem>
     1771      </varlistentry>
     1772      <varlistentry>
     1773        <term>
     1774          <methodsynopsis language="java">
     1775            <modifier>public</modifier>
     1776            <void/>
     1777            <methodname>setFilename</methodname>
     1778            <methodparam>
     1779              <type>String</type>
     1780              <parameter>filename</parameter>
     1781            </methodparam>
     1782          </methodsynopsis>
     1783        </term>
     1784        <listitem>
     1785          <para>
     1786          Set a suggested name of the file that is beeing
     1787          generated.
     1788          </para>
     1789        </listitem>
     1790      </varlistentry>
     1791      </variablelist>
     1792     
     1793      </sect3>
     1794     
     1795      <sect3 id="plugin_developer.export.callsequence">
     1796        <title>Call sequence during immediate download</title>
     1797
     1798      <para>
     1799        Supporting immediate download also means that the method call
     1800        sequence is a bit altered from the standard sequence described
     1801        in <xref linkend="plugin_developer.api.callsequence.execute" />.
     1802      </para>
     1803     
     1804      <itemizedlist>
     1805      <listitem>
     1806        <para>
     1807        The plug-in must call <methodname>Response.setDownloadImmediately()</methodname>
     1808        instead of <methodname>Response.setDone()</methodname> in <methodname>Plugin.configure()</methodname>
     1809        to to end the job configuration wizard. This requests that the core starts
     1810        an immediate download.
     1811        </para>
     1812       
     1813        <note>
     1814          <para>
     1815          Even if an immediate download is requested by the plug-in this feature
     1816          may have been disabled by the server administrator. If so, the plug-in
     1817          can choose if the job should be added to job queue or if this is an
     1818          error condition.
     1819          </para>
     1820        </note>
     1821      </listitem>
     1822     
     1823      <listitem>
     1824        <para>
     1825        If immediate download is granted the web client will keep the
     1826        same plug-in instance and call <methodname>ImmediateDownloadExporter.doExport()</methodname>.
     1827        In this case, the <methodname>Plugin.run()</methodname> is never called.
     1828       
     1829        <note>
     1830          <para>
     1831          The <methodname>Plugin.done()</methodname> method is also never
     1832          called. This is a bug which has been reported to the developers.
     1833          </para>
     1834        </note>
     1835        </para>
     1836       
     1837      </listitem>
     1838
     1839      <listitem>
     1840        <para>
     1841        If immediate download isn't granted and the job is added to the job queue
     1842        the regular job execution sequence is used. That is, the
     1843        <methodname>Plugin.run()</methodname> method is called.
     1844        </para>
     1845      </listitem>
     1846      </itemizedlist>
     1847     
     1848      </sect3>
     1849
    16631850    </sect2>
     1851   
     1852    <sect2 id="plugin_developer.export.abstractexporter">
     1853      <title>The AbstractExporterPlugin class</title>
     1854   
     1855      <para>
     1856        This is an abstract superclass that will make it easier
     1857        to implement export plug-ins that support immediate
     1858        download. It defines <classname>PluginParameter</classname>
     1859        objects for asking a user about a path where the exported
     1860        data should be saved and if existing files should be overwritten or not.
     1861        If the user leaves the path empty the immediate download functionality
     1862        should be used. It also contains implementations of both the
     1863        <methodname>Plugin.run()</methodname> method and the
     1864        <methodname>ImmediateDownloadExporter.doExport()</methodname> method.
     1865        Here is what you need to do in your own plug-in code (code examples are
     1866        take from the <classname>HelpExporter</classname>):
     1867      </para>
     1868     
     1869      <itemizedlist>
     1870      <listitem>
     1871        <para>
     1872          Your plug-in should extend the <classname>AbstractExporterPlugin</classname>
     1873          class:
     1874          <programlisting>
     1875public class HelpExporter
     1876  extends AbstractExporterPlugin
     1877  implements InteractivePlugin
     1878</programlisting>
     1879        </para>
     1880      </listitem>
     1881     
     1882      <listitem>
     1883        <para>
     1884          You need to implement the
     1885          <methodname>InteractivePlugin.getRequestInformation()</methodname>
     1886          method. Use the <methodname>getSaveAsParameter()</methodname>
     1887          and <methodname>getOverwriteParameter()</methodname> methods defined in the
     1888          superclass to create plug-in parameters that asks for the file name to save
     1889          to and if existing files can be overwritten or not.
     1890          You should also check if the administrator has enabled the immediate execution
     1891          functionality for your plug-in. If not, the only option is to
     1892          export to a file in the BASE file system and the filename is a
     1893          required parameter.
     1894         
     1895          <programlisting>
     1896// Selected parts of the getRequestConfiguration() method
     1897...
     1898List&lt;PluginParameter&lt;?&gt;&gt; parameters =
     1899   new ArrayList&lt;PluginParameter&lt;?&gt;&gt;();
     1900...
     1901PluginDefinition pd = job.getPluginDefinition();
     1902boolean requireFile = pd == null ?
     1903   false : !pd.getAllowImmediateExecution();
     1904
     1905parameters.add(getSaveAsParameter(null, null, defaultPath, requireFile));
     1906parameters.add(getOverwriteParameter(null, null));
     1907
     1908configureJob = new RequestInformation
     1909(
     1910   Request.COMMAND_CONFIGURE_JOB,
     1911   "Help exporter options",
     1912   "Set Client that owns the helptexts, " +
     1913     "the file path where the export file should be saved",
     1914   parameters
     1915);
     1916....
     1917return configureJob;
     1918</programlisting>
     1919        </para>
     1920      </listitem>
     1921
     1922      <listitem>
     1923        <para>
     1924        You must also implement the <methodname>configure()</methodname>
     1925        method and check the parameters. If no filename has been given,
     1926        you should check if immediate exection is allowed and set an
     1927        error if it isn't. If a filename is present, use the
     1928        <methodname>pathCanBeUsed()</methodname> method to check if
     1929        it is possible to save the data to a file with that name. If the
     1930        file already exists it can be overwritten if the <varname>OVERWRITE</varname>
     1931        is <constant>TRUE</constant> or if the file has been flagged for removal.
     1932        Don't forget to store the parameters with the <methodname>storeValue()</methodname>
     1933        method.
     1934
     1935        <programlisting>
     1936// Selected parts from the configure() method
     1937if (request.getParameterValue(SAVE_AS) == null)
     1938{
     1939   if (!request.isAllowedImmediateExecution())
     1940   {
     1941      response.setError("Immediate download is not allowed. " +
     1942         "Please specify a filename.", null);
     1943      return;
     1944   }
     1945   Client client = (Client)request.getParameterValue("client");
     1946   response.setDownloadImmediately("Export help texts for client application " +
     1947     client.getName(), ExecutionTime.SHORTEST, true);
     1948}
     1949else
     1950{
     1951   if (!pathCanBeUsed((String)request.getParameterValue(SAVE_AS),
     1952      (Boolean)request.getParameterValue(OVERWRITE)))
     1953   {
     1954      response.setError("File exists: " +
     1955         (String)request.getParameterValue(SAVE_AS), null);
     1956      return;
     1957   }
     1958   storeValue(job, request, ri.getParameter(SAVE_AS));
     1959   storeValue(job, request, ri.getParameter(OVERWRITE));
     1960   response.setDone("The job configuration is complete", ExecutionTime.SHORTEST);
     1961}
     1962</programlisting>
     1963       
     1964        </para>
     1965      </listitem>
     1966     
     1967      <listitem>
     1968        <para>
     1969        Implement the <methodname>performExport()</methodname> method.
     1970        This is defined as abstract in the <classname>AbstractExporterPlugin</classname>
     1971        class. It has the same parameters as the <methodname>ImmediateDownloadExporter.doExport()</methodname>
     1972        method and they have the same meaning. The only difference is that the
     1973        <varname>out</varname> stream can be linked to a file and not just to the
     1974        immediate download.
     1975        </para>
     1976      </listitem>
     1977     
     1978      <listitem>
     1979        <para>
     1980        Optionally, implement the <methodname>begin()</methodname>,
     1981        <methodname>end()</methodname> and <methodname>getSuccessMessage()</methodname>
     1982        methods. Theese methods do nothing by default.
     1983        </para>
     1984      </listitem>
     1985      </itemizedlist>
     1986     
     1987      <para>
     1988        The call sequence for plug-ins extending <classname>AbstractExporterPlugin</classname>
     1989        is:
     1990      </para>
     1991     
     1992      <orderedlist>
     1993      <listitem>
     1994        <para>
     1995        Call <methodname>begin()</methodname>.
     1996        </para>
     1997      </listitem>
     1998      <listitem>
     1999        <para>
     2000        Call <methodname>performExport()</methodname>.
     2001        </para>
     2002      </listitem>
     2003      <listitem>
     2004        <para>
     2005        Call <methodname>end()</methodname>.
     2006        </para>
     2007      </listitem>
     2008      <listitem>
     2009        <para>
     2010        Call <methodname>getSuccessMessage()</methodname> if running as a regular
     2011        job. This method is never called when doing an immediate download since there
     2012        is no place to show the message.
     2013        </para>
     2014      </listitem>
     2015      </orderedlist>
     2016     
     2017    </sect2>
     2018   
    16642019  </sect1>
    16652020 
Note: See TracChangeset for help on using the changeset viewer.