antville/helma
antville/helma
1
1
Fork 0
Code Issues 5 Pull requests 5 Projects Releases 5 Activity Actions

* added JsDoc compatible inline documentation

Browse source 
* added missing toString methods
* minor code beautification
This commit is contained in:
grob 2007-01-30 17:31:13 +00:00
parent dcc0accdb3
commit 14ee73a230
1 changed files with 193 additions and 104 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

297
helma/Zip.js
View file

@ -9,39 +9,52 @@
* Copyright 1998-2006 Helma Software. All Rights Reserved. * Copyright 1998-2006 Helma Software. All Rights Reserved.
* *
* $RCSfile: Zip.js,v $ * $RCSfile: Zip.js,v $
* $Author: czv $ * $Author: hannes $
* $Revision: 1.2 $ * $Revision: 1.3 $
* $Date: 2006/04/24 07:02:17 $ * $Date: 2006/06/02 15:46:20 $
*/
/**
* @fileoverview Fields and methods of the helma.Zip class.
*/ */
// take care of any dependencies // take care of any dependencies
app.addRepository('modules/helma/File.js'); app.addRepository('modules/helma/File.js');
// define the helma namespace, if not existing
if (!global.helma) { if (!global.helma) {
global.helma = {}; global.helma = {};
} }
/** /**
* constructor function for Zip Objects * Constructs a new helma.Zip instance
* @param either * @class Instances of this class represent a single zip archive
* - (Object) a File object * and provide various methods for extracting entries or manipulating
* - (Object) an instance of Helma.File * the contents of the archive.
* - (Object) an instance of java.io.File * @param {helma.File|java.io.File|String} file Either
* - (String) the path to the zip file * a file object representing the .zip file on disk, or the
* path to the .zip file as string.
* @constructor
* @returns A newly created instance of helma.Zip.
* @author Robert Gaggl <robert@nomatic.org>
*/ */
helma.Zip = function (file) { helma.Zip = function(file) {
/** /**
* private function that extracts the data of a file * Private method that extracts the data of a single file
* in a .zip archive. If a destination Path is given it * in a .zip archive. If a destination path is given it
* writes the extracted data directly to disk using the * writes the extracted data directly to disk using the
* name of the ZipEntry Object, otherwise it returns the * name of the ZipEntry Object, otherwise it returns the
* byte array containing the extracted data * byte array containing the extracted data.
* @param Object jAva.util.zip.ZipFile Object * @param {java.util.zip.ZipFile} zFile The zip archive to extract
* @param Object java.util.zip.ZipEntry Object to extract * the file from.
* @param String destination path to extract ZipEntry Object to * @param {java.util.zip.ZipEntry} entry The zip entry to extract
* @return Object ByteArray containing the data of the ZipEntry * @param {String} destPath The destination path where the extracted
* file should be stored.
* @returns If no destination path is given, this method returns
* the contents of the extracted file as ByteArray, otherwise
* it returns null.
* @private
*/ */
var extractEntry = function(zFile, entry, destPath) { var extractEntry = function(zFile, entry, destPath) {
var size = entry.getSize(); var size = entry.getSize();
@ -76,12 +89,16 @@ helma.Zip = function (file) {
}; };
/** /**
* private function for adding a single file to the .zip archive * Private method for adding a single file to the Zip archive
* @param Object java.util.zip.ZipOutputStream * represented by this helma.Zip instance
* @param Object instance of java.io.File representing the file to be added * @param {java.util.zip.ZipOutputStream} zOutStream The output
* @param Int compression-level (0-9) * stream to write to
* @param String path of the directory in the archive to which the * @param {java.io.File} f The file that should be added to the
* file should be added (optional) * Zip archive.
* @param {Number} level The compression-level between 0-9.
* @param {String} pathPrefix The path of the directory within the
* Zip archive where the file should be added (optional).
* @private
*/ */
var addFile = function(zOutStream, f, level, pathPrefix) { var addFile = function(zOutStream, f, level, pathPrefix) {
var fInStream = new java.io.BufferedInputStream(new java.io.FileInputStream(f)); var fInStream = new java.io.BufferedInputStream(new java.io.FileInputStream(f));
@ -106,52 +123,60 @@ helma.Zip = function (file) {
zOutStream.write(buf, 0, buf.length); zOutStream.write(buf, 0, buf.length);
zOutStream.closeEntry(); zOutStream.closeEntry();
fInStream.close(); fInStream.close();
return true; return;
}; };
/** /**
* private function that constructs an instance * Private helper method that converts the argument into
* of java.io.File based on a JS File or Helma.File object * an instance of java.io.File.
* @param Object either a string or an instance of java.io.File, File or Helma.File * @param {helma.File|java.io.File} f Either a file object or
* @return Object instance of java.io.File * the path to a file as string
* @return The argument converted into a file object
* @type java.io.File
* @private
*/ */
var evalFile = function(f) { var evalFile = function(f) {
if (f instanceof java.io.File)
return f;
var result; var result;
if (typeof f == "string") if (f instanceof java.io.File) {
result = f;
} else if (f instanceof helma.File || typeof(f) == "string") {
result = new java.io.File(f); result = new java.io.File(f);
else }
result = new java.io.File(f.getAbsolutePath()); if (!result.exists()) {
if (!result.exists()) throw "Error creating Zip Object: File '" + f + "' doesn't exist.";
throw("Error creating Zip Object: File '" + f + "' doesn't exist."); }
return result; return result;
}; };
/** /**
* returns an array containing the entries of a .zip file as objects * Returns an array containing the entries of the archive
* (see Entry for description) * represented by this helma.Zip instance.
* @param Object File object representing the .zip file on disk * @returns The entries stored in the zip archive
* @return Object result object * @type helma.Zip.Content
*/ */
this.list = function() { this.list = function() {
var result = new helma.Zip.Content(); var result = new helma.Zip.Content();
var zFile = new java.util.zip.ZipFile(file); var zFile = new java.util.zip.ZipFile(file);
var entries = zFile.entries(); var entries = zFile.entries();
while (entries.hasMoreElements()) while (entries.hasMoreElements()) {
result.add(new helma.Zip.Entry(entries.nextElement())); result.add(new helma.Zip.Entry(entries.nextElement()));
}
zFile.close(); zFile.close();
return result; return result;
}; };
/** /**
* extracts a single file from a .zip archive * Extracts a single file from the zip archive represented
* if a destination path is given it directly writes * by this helma.Zip instance. If a destination path is given it
* the extracted file to disk * writes the extracted data directly to disk using the
* @param Object File object representing the .zip file on disk * name of the zip entry, otherwise the resulting entry object
* @param String Name of the file to extract * contains the extracted data in the property <code>data</code>.
* @param String (optional) destination path to write file to * @param {String} name The name of the file to extract
* @return Object JS Object (see Entry for description) * @param {String} destPath An optional destination path where
* the extracted file should be stored.
* @returns An object containing the entry's properties
* @type helma.Zip.Entry
* @see helma.Zip.Entry
*/ */
this.extract = function(name, destPath) { this.extract = function(name, destPath) {
var zFile = new java.util.zip.ZipFile(file); var zFile = new java.util.zip.ZipFile(file);
@ -165,13 +190,17 @@ helma.Zip = function (file) {
}; };
/** /**
* extracts all files in a .zip archive * Extracts all files within the zip archive represented by
* if a destination path is given it directly writes * this helma.Zip instance. If a destination path is given it
* the extracted files to disk (preserves directory structure * stores the files directly on disk, while preserving any directory
* of .zip archive if existing!) * structure within the archive. If no destination path is given,
* @param String (optional) destination path to write file to * the resulting entry objects will contain the extracted data
* @return Object Array containing JS objects for each entry * in their property <code>data</code>.
* (see Entry for description) * @param {String} destPath An optional destination path where the
* files in the zip archive should be stored.
* @returns An object containing the extracted entries.
* @type helma.Zip.Content
* @see helma.Zip.Entry
*/ */
this.extractAll = function(destPath) { this.extractAll = function(destPath) {
var result = new helma.Zip.Content(); var result = new helma.Zip.Content();
@ -188,15 +217,14 @@ helma.Zip = function (file) {
}; };
/** /**
* adds a single file or a whole directory (recursive!) to the .zip archive * Adds a single file or a whole directory (recursive!) to the zip archive
* @param either * @param {helma.File|java.io.File|String} f Either a file object
* - (Object) a File object * or the path to a file or directory on disk that should be added to the
* - (Object) an instance of java.io.File * archive. If the argument represents a directory, its contents will be added
* - (String) the path to the file that should be added * <em>recursively</em> to the archive.
* @param Int Level to use for compression (default: 9 = best compression) * @param {Number} level An optional compression level to use. The argument
* @param String name of the directory in the archive into which the * must be between zero and 9 (default: 9 = best compression).
* file should be added (optional) * @param {String} pathPrefix An optional path prefix to use within the archive.
* @return Boolean true
*/ */
this.add = function (f, level, pathPrefix) { this.add = function (f, level, pathPrefix) {
var f = evalFile(f); var f = evalFile(f);
@ -228,34 +256,39 @@ helma.Zip = function (file) {
addFile(zOutStream, fAdd, level, p); addFile(zOutStream, fAdd, level, p);
} }
} }
} else } else {
addFile(zOutStream, f, level, pathPrefix); addFile(zOutStream, f, level, pathPrefix);
return true; }
return;
}; };
/** /**
* adds a new entry to the zip file * Adds a new entry to the zip file.
* @param Object byte[] containing the data to add * @param {ByteArray} buf A byte array containing the data to add
* @param String name of the file to add * to the archive.
* @param Int compression level (0-9, default: 9) * @param {String} name The name of the file to add, containing
* @return Boolean true * an optional path prefix
* @param {Number} level The compression level to use (0-9, defaults to 9).
*/ */
this.addData = function(buf, name, level) { this.addData = function(buf, name, level) {
var entry = new java.util.zip.ZipEntry(name); var entry = new java.util.zip.ZipEntry(name);
entry.setSize(buf.length); entry.setSize(buf.length);
entry.setTime(new Date()); entry.setTime(new Date());
if (level == null || isNaN(level)) if (level == null || isNaN(level)) {
zOutStream.setLevel(9); zOutStream.setLevel(9);
else } else {
zOutStream.setLevel(Math.max(0, Math.min(9, parseInt(level, 10)))); zOutStream.setLevel(Math.max(0, Math.min(9, parseInt(level, 10))));
}
zOutStream.putNextEntry(entry); zOutStream.putNextEntry(entry);
zOutStream.write(buf, 0, buf.length); zOutStream.write(buf, 0, buf.length);
zOutStream.closeEntry(); zOutStream.closeEntry();
return true; return;
}; };
/** /**
* closes the ZipOutputStream * Closes the zip archive. This method should be called when
* all operations have been finished, to ensure that no open
* file handles are left.
*/ */
this.close = function() { this.close = function() {
zOutStream.close(); zOutStream.close();
@ -263,17 +296,18 @@ helma.Zip = function (file) {
}; };
/** /**
* returns the binary data of the zip file * Returns the binary data of the zip archive.
* @return Object ByteArray containing the binary data of the zip file * @returns A ByteArray containing the binary data of the zip archive
* @type ByteArray
*/ */
this.getData = function() { this.getData = function() {
return bOutStream.toByteArray(); return bOutStream.toByteArray();
}; };
/** /**
* saves the archive by closing the output stream * Saves the archive.
* @param String path (including the name) to save the zip file to * @param {String} dest The full destination path including the name
* @return Boolean true * where the zip archive should be saved.
*/ */
this.save = function(dest) { this.save = function(dest) {
if (!dest) if (!dest)
@ -287,14 +321,16 @@ helma.Zip = function (file) {
} finally { } finally {
outStream.close(); outStream.close();
} }
return true; return;
}; };
/** @ignore */
this.toString = function() { this.toString = function() {
if (file) if (file) {
return "[Zip Object " + file.getAbsolutePath() + "]"; return "[helma.Zip " + file.getAbsolutePath() + "]";
else } else {
return "[Zip Object]"; return "[helma.Zip]";
}
}; };
/** /**
@ -313,30 +349,45 @@ helma.Zip = function (file) {
} }
/** /**
* constructor for Content Objects * Creates a new helma.Zip.Content instance
* @class Instances of this class represent the content
* of a zip archive.
* @constructor
* @returns A newly created instance of helma.Zip.Content
*/ */
helma.Zip.Content = function() { helma.Zip.Content = function() {
/**
* The table of contents of the archive
* @type Array
*/
this.toc = []; this.toc = [];
/**
* The files contained in the zip archive, where
* each directory level is a separate object containing
* the entries (files and directories) as properties.
*/
this.files = {}; this.files = {};
/** /**
* adds a Zip Entry object to the table of contents * Adds a zip entry object to the table of contents
* and the files collection * and the files collection
* @param Object instance of helma.Zip.Entry * @param {helma.Zip.Entry} entry The entry to add to the
* zip archive
*/ */
this.add = function(entry) { this.add = function(entry) {
// add the file to the table of contents array // add the file to the table of contents array
this.toc.push(entry); this.toc[this.toc.length] = entry;
// plus add it to the files tree // plus add it to the files tree
var re = /[\\\/]/; var arr = entry.name.split(/[\\\/]/);
var arr = entry.name.split(re);
var cnt = 0; var cnt = 0;
var curr = this.files; var curr = this.files;
var propName; var propName;
while (cnt < arr.length-1) { while (cnt < arr.length-1) {
propName = arr[cnt++]; propName = arr[cnt++];
if (!curr[propName]) if (!curr[propName]) {
curr[propName] = new Object(); curr[propName] = {};
}
curr = curr[propName]; curr = curr[propName];
} }
curr[arr[cnt]] = entry; curr[arr[cnt]] = entry;
@ -350,32 +401,70 @@ helma.Zip.Content = function() {
}; };
/** @ignore */
helma.Zip.Content.prototype.toString = function() {
return "[helma.Zip.Content]";
}
/** /**
* constructor for Entry objects holding the meta-data of a zip entry: * Creates a new instance of helma.Zip.Entry
* .name (String) name of the entry * @class Instances of this class represent a single zip archive entry,
* .size (Int) decompressed size of the entry in bytes * containing the (meta)data of the entry.
* .time (Date) last modification timestamp of the entry or null * @param {java.util.zip.ZipEntry} entry The zip entry object whose metadata
* .isDirectory (Boolean) true in case entry is a directory, false otherwise * should be stored in this instance
* .data (ByteArray) ByteArray containing the data of the entry * @constructor
* @param Object java.util.zip.ZipEntry Object * @returns A newly created helma.Zip.Entry instance.
*/ */
helma.Zip.Entry = function(entry) { helma.Zip.Entry = function(entry) {
/**
* The name of the zip archive entry
* @type String
*/
this.name = entry.getName(); this.name = entry.getName();
/**
* The size of the entry in bytes
* @type Number
*/
this.size = entry.getSize(); this.size = entry.getSize();
/**
* The file date of the entry
* @type Date
*/
this.time = entry.getTime() ? new Date(entry.getTime()) : null; this.time = entry.getTime() ? new Date(entry.getTime()) : null;
/**
* True if the entry is a directory, false otherwise
* @type Boolean
*/
this.isDirectory = entry.isDirectory(); this.isDirectory = entry.isDirectory();
/**
* The data of the zip entry
* @type ByteArray
*/
this.data = null; this.data = null;
for (var i in this) for (var i in this)
this.dontEnum(i); this.dontEnum(i);
return this; return this;
}; };
/** @ignore */
helma.Zip.Entry.prototype.toString = function() {
return "[helma.Zip.Entry]";
}
/** /**
* extract all files in a ByteArray passed as argument * Extracts all files in the zip archive data passed as argument
* and return them as result Array * and returns them.
* @param Object ByteArray containing the data of the .zip File * @param {ByteArray} zipData A ByteArray containing the data of the zip archive
* @return Object instance of helma.Zip.Content * @returns The entries of the zip archive
* @type helma.Zip.Content
*/ */
helma.Zip.extractData = function(zipData) { helma.Zip.extractData = function(zipData) {
var zInStream = new java.util.zip.ZipInputStream(new java.io.ByteArrayInputStream(zipData)); var zInStream = new java.util.zip.ZipInputStream(new java.io.ByteArrayInputStream(zipData));