Ignore:
Timestamp:
May 25, 2007, 12:17:46 PM (14 years ago)
Author:
Nicklas Nordborg
Message:

References #551. Added section about FileUnpacker? plug-ins.

File:
1 edited

Legend:

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

    r3371 r3383  
    17171717      <title>File unpacker plug-ins</title>
    17181718      <para>
    1719         TODO
     1719        The BASE web client has integrated support for unpacking of
     1720        compressed files. See <xref linkend="file_system.handling.upload" />.
     1721        Behind the scenes, this support is provided by plug-ins. The standard
     1722        BASE distribution comes with support for ZIP files
     1723        (<classname>net.sf.basedb.plugins.ZipFileUnpacker</classname>).
    17201724      </para>
     1725      <para>
     1726        To add support for additional compressed formats you have to create a plug-in that
     1727        implements the <interfacename>net.sf.basedb.util.zip.FileUnpacker</interfacename>
     1728        interface. The best way to do this is to extend the
     1729        <classname>net.sf.basedb.util.zip.AbstractFileUnpacker</classname> which
     1730        implements all methods in the <interfacename>Plugin</interfacename>
     1731        and <interfacename>InteractivePlugin</interfacename>
     1732        interfaces except <methodname>Plugin.getAbout()</methodname>. This leaves
     1733        you with the actual unpacking of the files as the only thing to implement.
     1734      </para>
     1735     
     1736      <note>
     1737        <title>No support for configurations</title>
     1738        The integrated upload in the web interface only works with plug-ins that
     1739        doesn't require a configuration to run.
     1740      </note>
     1741     
     1742      <variablelist>
     1743        <title>Methods in the <interfacename>FileUnpacker</interfacename> interface</title>
     1744        <varlistentry>
     1745          <term>
     1746            <methodsynopsis language="java">
     1747              <modifier>public</modifier>
     1748              <type>String</type>
     1749              <methodname>getFormatName</methodname>
     1750            </methodsynopsis>
     1751          </term>
     1752          <listitem>
     1753            <para>
     1754            Return a short string naming the file format. For example:
     1755            <constant>ZIP files</constant> or <constant>TAR files</constant>.
     1756            </para>
     1757          </listitem>
     1758        </varlistentry>
     1759           
     1760        <varlistentry>
     1761          <term>
     1762            <methodsynopsis language="java">
     1763              <modifier>public</modifier>
     1764              <type>Set&lt;String&gt;</type>
     1765              <methodname>getExtensions</methodname>
     1766            </methodsynopsis>
     1767          </term>
     1768          <listitem>
     1769            <para>
     1770            Return a set of strings with the file extensions that
     1771            are most commonly used with the compressed file format.
     1772            For example: <constant>[zip, jar]</constant>. Do not include
     1773            the dot in the extensions. The web client and the
     1774            <methodname>AbstractFlatFileUnpacker.isInContext()</methodname> method
     1775            will use this information to automatically guess which plug-in to
     1776            use for unpacking the files.
     1777            </para>
     1778          </listitem>
     1779        </varlistentry>
     1780       
     1781        <varlistentry>
     1782          <term>
     1783            <methodsynopsis language="java">
     1784              <modifier>public</modifier>
     1785              <type>Set&lt;String&gt;</type>
     1786              <methodname>getMimeTypes</methodname>
     1787            </methodsynopsis>
     1788          </term>
     1789          <listitem>
     1790            <para>
     1791            Return a set of string with the MIME types that commonly used with
     1792            the compressed file format. For example:
     1793            <constant>[application/zip, application/java-archive]</constant>.
     1794            This information is used by the
     1795            <methodname>AbstractFlatFileUnpacker.isInContext()</methodname>
     1796            method to automatically guess which plug-in to use for unpacking
     1797            the files.
     1798            </para>
     1799          </listitem>
     1800        </varlistentry>
     1801       
     1802        <varlistentry>
     1803          <term>
     1804            <methodsynopsis language="java">
     1805              <modifier>public</modifier>
     1806              <type>int</type>
     1807              <methodname>unpack</methodname>
     1808              <methodparam>
     1809                <type>DbControl</type>
     1810                <parameter>dc</parameter>
     1811              </methodparam>
     1812              <methodparam>
     1813                <type>Directory</type>
     1814                <parameter>dir</parameter>
     1815              </methodparam>
     1816              <methodparam>
     1817                <type>InputStream</type>
     1818                <parameter>in</parameter>
     1819              </methodparam>
     1820              <methodparam>
     1821                <type>boolean</type>
     1822                <parameter>overwrite</parameter>
     1823              </methodparam>
     1824              <methodparam>
     1825                <type>AbsoluteProgressReporter</type>
     1826                <parameter>progress</parameter>
     1827              </methodparam>
     1828              <exceptionname>IOException</exceptionname>
     1829              <exceptionname>BaseException</exceptionname>
     1830            </methodsynopsis>
     1831          </term>
     1832          <listitem>
     1833            <para>
     1834            Unpack the files and store them in the BASE file system.
     1835           
     1836            <itemizedlist>
     1837            <listitem>
     1838              <para>
     1839              Do not <methodname>close()</methodname> or
     1840              <methodname>commit()</methodname> the
     1841              <classname>DbControl</classname> passed to this method.
     1842              This is done automatically by the
     1843              <classname>AbstractFileUnpacker</classname> or by the web client.
     1844              </para>
     1845            </listitem>
     1846           
     1847            <listitem>
     1848              <para>
     1849              The <varname>dir</varname> parameter is the root directory where
     1850              the unpacked files should be placed. If the compressed file
     1851              contains subdirectory the plug-in must create those subdirectories
     1852              unless they already exists.
     1853              </para>
     1854            </listitem>
     1855           
     1856            <listitem>
     1857              <para>
     1858              If the <varname>overwrite</varname> parameter is
     1859              <constant>FALSE</constant> no existing file should be overwritten
     1860              unless the file is <systemitem>OFFLINE</systemitem>.
     1861              </para>
     1862            </listitem>
     1863           
     1864            <listitem>
     1865              <para>
     1866              The <varname>in</varname> parameter is the stream
     1867              containing the compressed data. The stream may come
     1868              directly from the web upload or from an existing
     1869              file in the BASE file system.
     1870              </para>
     1871            </listitem>
     1872           
     1873            <listitem>
     1874              <para>
     1875              The <varname>progress</varname> parameter, if not
     1876              <constant>null</constant>, should be used to reporter the
     1877              progress back to the calling code. The plug-in should count
     1878              the number of bytes read from the <varname>in</varname>
     1879              stream.
     1880              </para>
     1881            </listitem>
     1882            </itemizedlist>
     1883           
     1884            </para>
     1885          </listitem>
     1886        </varlistentry>
     1887      </variablelist>
     1888     
     1889      <para>
     1890        When the compressed file is uncompressed during the file upload
     1891        from the web interface, the call sequence to the plug-in is slightly
     1892        altered from the standard call sequence described in
     1893        <xref linkend="plugin_developer.api.callsequence.execute" />.
     1894       
     1895        <itemizedlist>
     1896        <listitem>
     1897          <para>
     1898          After the plug-in instance has been created, the
     1899          <methodname>Plugin.init()</methodname> method is called with <constant>null</constant>
     1900          values for both the <varname>configuration</varname> and <varname>job</varname>
     1901          parameters.
     1902          </para>
     1903        </listitem>
     1904       
     1905        <listitem>
     1906          <para>
     1907          Then, the <methodname>unpack()</methodname> method is called. The
     1908          <methodname>Plugin.run()</methodname> method is never called in this case.
     1909          The <methodname>Plugin.done()</methodname> method is also never called.
     1910          </para>
     1911        </listitem>
     1912       
     1913        </itemizedlist>
     1914       
     1915      </para>
     1916     
    17211917    </sect2>
    17221918  </sect1>
Note: See TracChangeset for help on using the changeset viewer.