Changeset 3643

Timestamp:

Aug 8, 2007, 2:32:47 PM (16 years ago)

Author:

Nicklas Nordborg

Message:

Fixes #451: Zipped download

Added user and plug-in developer documentation

Location:

trunk

Files:

• doc/src/docbook/developerdoc/plugin_developer.xml (modified) (2 diffs)
• doc/src/docbook/userdoc/file_system.xml (modified) (1 diff)
• src/core/net/sf/basedb/util/zip/Bzip2FilePacker.java (modified) (1 diff)
• src/core/net/sf/basedb/util/zip/FilePacker.java (modified) (1 diff)
• src/core/net/sf/basedb/util/zip/GzipFilePacker.java (modified) (1 diff)
• src/core/net/sf/basedb/util/zip/TarFilePacker.java (modified) (1 diff)
• src/plugins/core/net/sf/basedb/plugins/PackedFileExporter.java (modified) (2 diffs)

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

@@ -3602 +3602 @@
         BASE distribution comes with support for ZIP files 
         (<classname>net.sf.basedb.plugins.ZipFileUnpacker</classname>)
-        and TAR files (<classname>net.sf.basedb.plugins.ZipFileUnpacker</classname>).
+        and TAR files (<classname>net.sf.basedb.plugins.TarFileUnpacker</classname>).
       </para>
       <para>
@@ -3798 +3798 @@
       
     </sect2>
+    
+    <sect2 id="plugin_developer.other.packer">
+      <title>File packer plug-ins</title>
+    
+      <para>
+        BASE has support for compressing and downloading a set of selected files and/or
+        directories. This functionality is provided by a plug-in, the 
+        <classname>PackedFileExporter</classname>. This plug-in doesn't do the actual
+        packing itself. This is delegated to classes implementing the 
+        <interfacename>net.sf.basedb.util.zip.FilePacker</interfacename> interface.
+      </para>
+      
+      <para>
+        BASE ships with a number of packing methods, including ZIP and TAR. To
+        add support for other methods you have to provide an implementation
+        of the <interfacename>FilePacker</interfacename>
+        interface. Then, create a new configuration for the <classname>PackerFileExporter</classname>
+        and enter the name of your class in the configuration wizard.
+      </para>
+      
+      <para>
+        The <interfacename>FilePacker</interfacename> interface is not a regular
+        plug-in interface (ie. it is not a subinterface to 
+        <interfacename>Plugin</interfacename>). This means that you don't have to
+        mess with configuration or job parameters. Another difference is that your
+        class must be installed in Tomcat's classpath (ie. in one of the 
+        <filename>WEB-INF/classes</filename> or <filename>WEB-INF/lib</filename>
+        folders).
+      </para>
+      
+      <variablelist>
+        <title>Methods in the <interfacename>FilePacker</interfacename> interface</title>
+        <varlistentry>
+          <term>
+            <methodsynopsis language="java">
+              <modifier>public</modifier>
+              <type>String</type>
+              <methodname>getDescription</methodname>
+            </methodsynopsis>
+          </term>
+          <listitem>
+            <para>
+            Return a short description the file format that is suitable for use
+            in dropdown lists in client applications. For example:
+            <constant>Zip-archive (.zip)</constant> or <constant>TAR-archive (.tar)</constant>.
+            </para>
+          </listitem>
+        </varlistentry>
+        <varlistentry>
+          <term>
+            <methodsynopsis language="java">
+              <modifier>public</modifier>
+              <type>String</type>
+              <methodname>getFileExtension</methodname>
+            </methodsynopsis>
+          </term>
+          <listitem>
+            <para>
+            Return the default file extension of the packed format. The returned
+            value should not include the dot. For example:
+            <constant>zip</constant> or <constant>tar</constant>.
+            </para>
+          </listitem>
+        </varlistentry>
+        <varlistentry>
+          <term>
+            <methodsynopsis language="java">
+              <modifier>public</modifier>
+              <type>String</type>
+              <methodname>getMimeType</methodname>
+            </methodsynopsis>
+          </term>
+          <listitem>
+            <para>
+            Return the standard MIME type of the packed file format.
+            For example: 
+            <constant>application/zip</constant> or <constant>application/x-tar</constant>.
+            </para>
+          </listitem>
+        </varlistentry>
+        <varlistentry>
+          <term>
+            <methodsynopsis language="java">
+              <modifier>public</modifier>
+              <void />
+              <methodname>setOutputStream</methodname>
+              <methodparam>
+                <type>OutputStream</type>
+                <parameter>out</parameter>
+              </methodparam>
+              <exceptionname>IOException</exceptionname>
+            </methodsynopsis>
+          </term>
+          <listitem>
+            <para>
+            Sets the outputstream that the packer should write the packed
+            files to.
+            </para>
+          </listitem>
+        </varlistentry>
+        <varlistentry>
+          <term>
+            <methodsynopsis language="java">
+              <modifier>public</modifier>
+              <void />
+              <methodname>pack</methodname>
+              <methodparam>
+                <type>String</type>
+                <parameter>entryName</parameter>
+              </methodparam>
+              <methodparam>
+                <type>InputStream</type>
+                <parameter>in</parameter>
+              </methodparam>
+              <methodparam>
+                <type>long</type>
+                <parameter>size</parameter>
+              </methodparam>
+              <methodparam>
+                <type>long</type>
+                <parameter>lastModified</parameter>
+              </methodparam>
+              <exceptionname>IOException</exceptionname>
+            </methodsynopsis>
+          </term>
+          <listitem>
+            <para>
+            Add another file or directory to the packed file. The 
+            <parameter>entryName</parameter> is the name of the new entry, including
+            path information. The <parameter>in</parameter> is the stream to read
+            the file data from. If <parameter>in</parameter> is <constant>null</constant>
+            then the entry denotes a directory. The <parameter>size</parameter> parameter
+            gives the size in bytes of the file (zero for empty files or directories). 
+            The <parameter>lastModified</parameter>
+            is that time the file was last modified or 0 if not known.
+            </para>
+          </listitem>
+        </varlistentry>
+        <varlistentry>
+          <term>
+            <methodsynopsis language="java">
+              <modifier>public</modifier>
+              <void />
+              <methodname>close</methodname>
+              <exceptionname>IOException</exceptionname>
+            </methodsynopsis>
+          </term>
+          <listitem>
+            <para>
+            Finish the packing. The packer should release any resources, flush
+            all data. It should not close the <varname>out</varname> stream
+            set in the <methodname>setOutputStream</methodname> method since
+            this is done by the calling code.
+            </para>
+          </listitem>
+        </varlistentry>
+        
+      </variablelist>
+      
+    </sect2>
   </sect1>
   

trunk/doc/src/docbook/userdoc/file_system.xml

@@ -685 +685 @@
         </para>
       </sect3>
+      <sect3 id="file_system.handling.actions.zippeddownload">
+        <title>Download/compress multiple files</title>
+        
+        <para>
+        You can download multiple files/directories at the same time. First,
+        from the file browser, select one or more files/directories. Then, click
+        on the &gbExport; button. Select the <userinput>Packed file exporter</userinput>
+        plug-in and choose one of the file formats below it. On the &gbNext;
+        page you can specify other options for the download:
+        </para>
+        
+        <itemizedlist>
+        <listitem>
+          <para>
+            <guilabel>Save as</guilabel>: The path to a file on the BASE file system
+            where the selected files and directories should be packed. Leave this 
+            field empty to download the files to your own computer.
+          </para>
+        </listitem>
+        <listitem>
+          <para>
+            <guilabel>Overwrite</guilabel>: If you are saving to the BASE file system
+            you may select if it is allowed to overwrite an existing file or not.
+          </para>
+        </listitem>
+        <listitem>
+          <para>
+            <guilabel>Remove files/directories</guilabel>: If you select this option
+            the selected files and directories will be marked as removed. You must still
+            go to the <guilabel>Trashcan</guilabel> and remove the items permanently.
+          </para>
+        </listitem>
+        </itemizedlist>
+        
+      </sect3>
     </sect2>
     <sect2 id="file_system.handling.directories">

trunk/src/core/net/sf/basedb/util/zip/Bzip2FilePacker.java

@@ -56 +56 @@
   */
   /**
-    @return "BZipped Tar-archive (.tar.bz2)"
+    @return "BZipped TAR-archive (.tar.bz2)"
   */
   public String getDescription()
   {
-    return "BZipped Tar-archive (.tar.bz2)";
+    return "BZipped TAR-archive (.tar.bz2)";
   }
   /**

trunk/src/core/net/sf/basedb/util/zip/FilePacker.java

@@ -75 +75 @@
     Compress the uncompressed input stream to an entry with the given
     name into the outputstream.
-    @param entryName The name of the packed resource
+    @param entryName The name of the packed resource, including path 
+      information
       @param in The input stream to read uncompressed data from, or null
         if the entry represents a directory

trunk/src/core/net/sf/basedb/util/zip/GzipFilePacker.java

@@ -54 +54 @@
   */
   /**
-    @return "GZipped Tar-archive (.tar.gz)"
+    @return "GZipped TAR-archive (.tar.gz)"
   */
   public String getDescription()
   {
-    return "GZipped Tar-archive (.tar.gz)";
+    return "GZipped TAR-archive (.tar.gz)";
   }
   /**

trunk/src/core/net/sf/basedb/util/zip/TarFilePacker.java

@@ -57 +57 @@
   */
   /**
-    @return "Tar-archive (.tar)"
+    @return "TAR-archive (.tar)"
   */
   public String getDescription()
   {
-    return "Tar-archive (.tar)";
+    return "TAR-archive (.tar)";
   }
   /**

trunk/src/plugins/core/net/sf/basedb/plugins/PackedFileExporter.java

@@ -26 +26 @@
 
 import net.sf.basedb.core.BaseException;
+import net.sf.basedb.core.BasicItem;
 import net.sf.basedb.core.BooleanParameterType;
 import net.sf.basedb.core.DbControl;
@@ -269 +270 @@
         // Verify that all selected files and directories are children to the root directory
         Directory root = (Directory)request.getParameterValue("root");
-        for (Nameable item : selectedFilesAndDirs)
-        {
-          Directory dir = null;
-          if (item.getType() == Item.FILE)
+        DbControl dc = sc.newDbControl();
+        try
+        {
+          for (Nameable item : selectedFilesAndDirs)
           {
-            dir = ((File)item).getDirectory();
+            dc.reattachItem((BasicItem)item);
+            Directory dir = null;
+            if (item.getType() == Item.FILE)
+            {
+              dir = ((File)item).getDirectory();
+            }
+            else
+            {
+              dir = ((Directory)item).getParent();
+            }
+            if (!root.equals(dir))
+            {
+              response.setError(item.getType().toString() + " is not located in root directory: " + root.getPath().toString(), null);
+              return;
+            }
           }
-          else
-          {
-            dir = ((Directory)item).getParent();
-          }
-          if (!root.equals(dir))
-          {
-            response.setError(item.getType().toString() + " is not located in root directory: " + root.getPath().toString(), null);
-            return;
-          }
+        }
+        finally
+        {
+          if (dc != null) dc.close();
         }