Changeset 3406
- Timestamp:
- May 30, 2007, 11:52:03 AM (16 years ago)
- File:
-
- 1 edited
Legend:
- Unmodified
- Added
- Removed
-
trunk/doc/src/docbook/developerdoc/plugin_developer.xml
r3394 r3406 1656 1656 <sect1 id="plugin_developer.export"> 1657 1657 <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> 1659 1667 1660 1668 <sect2 id="plugin_developer.export.download"> 1661 1669 <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 1663 1850 </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> 1875 public 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 ... 1898 List<PluginParameter<?>> parameters = 1899 new ArrayList<PluginParameter<?>>(); 1900 ... 1901 PluginDefinition pd = job.getPluginDefinition(); 1902 boolean requireFile = pd == null ? 1903 false : !pd.getAllowImmediateExecution(); 1904 1905 parameters.add(getSaveAsParameter(null, null, defaultPath, requireFile)); 1906 parameters.add(getOverwriteParameter(null, null)); 1907 1908 configureJob = 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 .... 1917 return 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 1937 if (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 } 1949 else 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 1664 2019 </sect1> 1665 2020
Note: See TracChangeset
for help on using the changeset viewer.