You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@harmony.apache.org by nd...@apache.org on 2009/04/24 04:23:50 UTC
svn commit: r768128 [1/2] - in
/harmony/enhanced/classlib/trunk/modules/archive/src/main/java/java/util:
jar/ zip/
Author: ndbeyer
Date: Fri Apr 24 02:23:48 2009
New Revision: 768128
URL: http://svn.apache.org/viewvc?rev=768128&view=rev
Log:
Apply patch for HARMONY-6173 - Javadoc for java.util.jar* and java.util.zip.*
Modified:
harmony/enhanced/classlib/trunk/modules/archive/src/main/java/java/util/jar/Attributes.java
harmony/enhanced/classlib/trunk/modules/archive/src/main/java/java/util/jar/JarEntry.java
harmony/enhanced/classlib/trunk/modules/archive/src/main/java/java/util/jar/JarException.java
harmony/enhanced/classlib/trunk/modules/archive/src/main/java/java/util/jar/JarFile.java
harmony/enhanced/classlib/trunk/modules/archive/src/main/java/java/util/jar/JarInputStream.java
harmony/enhanced/classlib/trunk/modules/archive/src/main/java/java/util/jar/JarOutputStream.java
harmony/enhanced/classlib/trunk/modules/archive/src/main/java/java/util/jar/JarVerifier.java
harmony/enhanced/classlib/trunk/modules/archive/src/main/java/java/util/jar/Manifest.java
harmony/enhanced/classlib/trunk/modules/archive/src/main/java/java/util/jar/Pack200.java
harmony/enhanced/classlib/trunk/modules/archive/src/main/java/java/util/zip/Adler32.java
harmony/enhanced/classlib/trunk/modules/archive/src/main/java/java/util/zip/CRC32.java
harmony/enhanced/classlib/trunk/modules/archive/src/main/java/java/util/zip/CheckedInputStream.java
harmony/enhanced/classlib/trunk/modules/archive/src/main/java/java/util/zip/CheckedOutputStream.java
harmony/enhanced/classlib/trunk/modules/archive/src/main/java/java/util/zip/Checksum.java
harmony/enhanced/classlib/trunk/modules/archive/src/main/java/java/util/zip/DataFormatException.java
harmony/enhanced/classlib/trunk/modules/archive/src/main/java/java/util/zip/Deflater.java
harmony/enhanced/classlib/trunk/modules/archive/src/main/java/java/util/zip/DeflaterOutputStream.java
harmony/enhanced/classlib/trunk/modules/archive/src/main/java/java/util/zip/GZIPInputStream.java
harmony/enhanced/classlib/trunk/modules/archive/src/main/java/java/util/zip/GZIPOutputStream.java
harmony/enhanced/classlib/trunk/modules/archive/src/main/java/java/util/zip/Inflater.java
harmony/enhanced/classlib/trunk/modules/archive/src/main/java/java/util/zip/InflaterInputStream.java
harmony/enhanced/classlib/trunk/modules/archive/src/main/java/java/util/zip/ZipEntry.java
harmony/enhanced/classlib/trunk/modules/archive/src/main/java/java/util/zip/ZipException.java
harmony/enhanced/classlib/trunk/modules/archive/src/main/java/java/util/zip/ZipFile.java
harmony/enhanced/classlib/trunk/modules/archive/src/main/java/java/util/zip/ZipInputStream.java
harmony/enhanced/classlib/trunk/modules/archive/src/main/java/java/util/zip/ZipOutputStream.java
Modified: harmony/enhanced/classlib/trunk/modules/archive/src/main/java/java/util/jar/Attributes.java
URL: http://svn.apache.org/viewvc/harmony/enhanced/classlib/trunk/modules/archive/src/main/java/java/util/jar/Attributes.java?rev=768128&r1=768127&r2=768128&view=diff
==============================================================================
--- harmony/enhanced/classlib/trunk/modules/archive/src/main/java/java/util/jar/Attributes.java (original)
+++ harmony/enhanced/classlib/trunk/modules/archive/src/main/java/java/util/jar/Attributes.java Fri Apr 24 02:23:48 2009
@@ -26,65 +26,161 @@
import org.apache.harmony.archive.util.Util;
/**
- * The Attributes class is used to store values for Manifest entries. Attributes
- * keys are generally instances of Attributes.Name. Values associated with
- * Attributes keys are of type String.
+ * The {@code Attributes} class is used to store values for manifest entries.
+ * Attribute keys are generally instances of {@code Attributes.Name}. Values
+ * associated with attribute keys are of type {@code String}.
*/
public class Attributes implements Cloneable, Map<Object, Object> {
+ /**
+ * The {@code Attributes} as name/value pairs. Maps the attribute names (as
+ * {@link Attributes.Name}) of a JAR file manifest to arbitrary values. The
+ * attribute names thus are obtained from the {@link Manifest} for
+ * convenience.
+ */
protected Map<Object, Object> map;
+ /**
+ * The name part of the name/value pairs constituting an attribute as
+ * defined by the specification of the JAR manifest. May be composed of the
+ * following ASCII signs as defined in the EBNF below:
+ *
+ * <pre>
+ * name = alphanum *headerchar
+ * headerchar = alphanum | - | _
+ * alphanum = {A-Z} | {a-z} | {0-9}
+ * </pre>
+ */
public static class Name {
private final byte[] name;
private int hashCode;
+ /**
+ * The class path (a main attribute).
+ */
public static final Name CLASS_PATH = new Name("Class-Path"); //$NON-NLS-1$
+ /**
+ * The version of the manifest file (a main attribute).
+ */
public static final Name MANIFEST_VERSION = new Name("Manifest-Version"); //$NON-NLS-1$
+ /**
+ * The main class's name (for stand-alone applications).
+ */
public static final Name MAIN_CLASS = new Name("Main-Class"); //$NON-NLS-1$
+ /**
+ * Defines the signature version of the JAR file.
+ */
public static final Name SIGNATURE_VERSION = new Name(
"Signature-Version"); //$NON-NLS-1$
+ /**
+ * The {@code Content-Type} manifest attribute.
+ */
public static final Name CONTENT_TYPE = new Name("Content-Type"); //$NON-NLS-1$
+ /**
+ * The {@code Sealed} manifest attribute which may have the value
+ * {@code true} for sealed archives.
+ */
public static final Name SEALED = new Name("Sealed"); //$NON-NLS-1$
+ /**
+ * The {@code Implementation-Title} attribute whose value is a string
+ * that defines the title of the extension implementation.
+ */
public static final Name IMPLEMENTATION_TITLE = new Name(
"Implementation-Title"); //$NON-NLS-1$
+ /**
+ * The {@code Implementation-Version} attribute defining the version of
+ * the extension implementation.
+ */
public static final Name IMPLEMENTATION_VERSION = new Name(
"Implementation-Version"); //$NON-NLS-1$
+ /**
+ * The {@code Implementation-Vendor} attribute defining the organization
+ * that maintains the extension implementation.
+ */
public static final Name IMPLEMENTATION_VENDOR = new Name(
"Implementation-Vendor"); //$NON-NLS-1$
+ /**
+ * The {@code Specification-Title} attribute defining the title of the
+ * extension specification.
+ */
public static final Name SPECIFICATION_TITLE = new Name(
"Specification-Title"); //$NON-NLS-1$
+ /**
+ * The {@code Specification-Version} attribute defining the version of
+ * the extension specification.
+ */
public static final Name SPECIFICATION_VERSION = new Name(
"Specification-Version"); //$NON-NLS-1$
+ /**
+ * The {@code Specification-Vendor} attribute defining the organization
+ * that maintains the extension specification.
+ */
public static final Name SPECIFICATION_VENDOR = new Name(
"Specification-Vendor"); //$NON-NLS-1$
+ /**
+ * The {@code Extension-List} attribute defining the extensions that are
+ * needed by the applet.
+ */
public static final Name EXTENSION_LIST = new Name("Extension-List"); //$NON-NLS-1$
+ /**
+ * The {@code Extension-Name} attribute which defines the unique name of
+ * the extension.
+ */
public static final Name EXTENSION_NAME = new Name("Extension-Name"); //$NON-NLS-1$
+ /**
+ * The {@code Extension-Installation} attribute.
+ */
public static final Name EXTENSION_INSTALLATION = new Name(
"Extension-Installation"); //$NON-NLS-1$
+ /**
+ * The {@code Implementation-Vendor-Id} attribute specifies the vendor
+ * of an extension implementation if the applet requires an
+ * implementation from a specific vendor.
+ */
public static final Name IMPLEMENTATION_VENDOR_ID = new Name(
"Implementation-Vendor-Id"); //$NON-NLS-1$
+ /**
+ * The {@code Implementation-URL} attribute specifying a URL that can be
+ * used to obtain the most recent version of the extension if the
+ * required version is not already installed.
+ */
public static final Name IMPLEMENTATION_URL = new Name(
"Implementation-URL"); //$NON-NLS-1$
static final Name NAME = new Name("Name");
+ /**
+ * A String which must satisfy the following EBNF grammar to specify an
+ * additional attribute:
+ *
+ * <pre>
+ * name = alphanum *headerchar
+ * headerchar = alphanum | - | _
+ * alphanum = {A-Z} | {a-z} | {0-9}
+ * </pre>
+ *
+ * @param s
+ * The Attribute string.
+ * @exception IllegalArgumentException
+ * if the string does not satisfy the EBNF grammar.
+ */
public Name(String s) {
int i = s.length();
if (i == 0 || i > Manifest.LINE_LENGTH_LIMIT - 2) {
@@ -114,6 +210,11 @@
return name;
}
+ /**
+ * Returns this attribute name.
+ *
+ * @return the attribute name.
+ */
@Override
public String toString() {
try {
@@ -123,6 +224,14 @@
}
}
+ /**
+ * returns whether the argument provided is the same as the attribute
+ * name.
+ *
+ * @return if the attribute names correspond.
+ * @param object
+ * An attribute name to be compared with this name.
+ */
@Override
public boolean equals(Object object) {
if (object == null || object.getClass() != getClass()
@@ -133,6 +242,11 @@
return Util.equalsIgnoreCase(name, ((Name) object).name);
}
+ /**
+ * Computes a hash code of the name.
+ *
+ * @return the hash value computed from the name.
+ */
@Override
public int hashCode() {
if (hashCode == 0) {
@@ -151,18 +265,18 @@
}
/**
- * Constructs an Attributes instance
+ * Constructs an {@code Attributes} instance.
*/
public Attributes() {
map = new HashMap<Object, Object>();
}
/**
- * Constructs an Attributes instance obtaining keys and values from the
- * parameter Attributes, attrib
+ * Constructs an {@code Attributes} instance obtaining keys and values from
+ * the parameter {@code attrib}.
*
* @param attrib
- * The Attributes to obtain entries from.
+ * The attributes to obtain entries from.
*/
@SuppressWarnings("unchecked")
public Attributes(Attributes attrib) {
@@ -170,97 +284,97 @@
}
/**
- * Constructs an Attributes instance with initial capacity of size size
+ * Constructs an {@code Attributes} instance with initial capacity of size
+ * {@code size}.
*
* @param size
- * Initial size of this Attributes instance.
+ * Initial size of this {@code Attributes} instance.
*/
public Attributes(int size) {
map = new HashMap<Object, Object>(size);
}
/**
- * Removes all key/value pairs from this Attributes.
- *
+ * Removes all key/value pairs from this {@code Attributes}.
*/
public void clear() {
map.clear();
}
/**
- * Determines whether this Attributes contains the specified key
- *
+ * Determines whether this {@code Attributes} contains the specified key.
*
* @param key
* The key to search for.
- * @return true if the key is found, false otherwise
+ * @return {@code true} if the key is found, {@code false} otherwise.
*/
public boolean containsKey(Object key) {
return map.containsKey(key);
}
/**
- * Determines whether this Attributes contains the specified value
+ * Determines whether this {@code Attributes} contains the specified value.
*
* @param value
- * The value to search for.
- * @return true if the value is found, false otherwise
+ * the value to search for.
+ * @return {@code true} if the value is found, {@code false} otherwise.
*/
public boolean containsValue(Object value) {
return map.containsValue(value);
}
/**
- * Returns a set containing MapEntry's for each of the key/value pairs
- * contained in this Attributes.
+ * Returns a set containing map entries for each of the key/value pair
+ * contained in this {@code Attributes}.
*
- * @return a set of MapEntry's
+ * @return a set of Map.Entry's
*/
public Set<Map.Entry<Object, Object>> entrySet() {
return map.entrySet();
}
/**
- * Returns the value associated with the parameter key
+ * Returns the value associated with the parameter key.
*
* @param key
- * The key to search for.
- * @return Object associated with key, or null if key does not exist.
+ * the key to search for.
+ * @return Object associated with key, or {@code null} if key does not
+ * exist.
*/
public Object get(Object key) {
return map.get(key);
}
/**
- * Determines whether this Attributes contains any keys
+ * Determines whether this {@code Attributes} contains any keys.
*
- * @return true if one or more keys exist, false otherwise
+ * @return {@code true} if one or more keys exist, {@code false} otherwise.
*/
public boolean isEmpty() {
return map.isEmpty();
}
/**
- * Returns a Set containing all the keys found in this Attributes.
+ * Returns a {@code Set} containing all the keys found in this {@code
+ * Attributes}.
*
- * @return a Set of all keys
+ * @return a {@code Set} of all keys.
*/
public Set<Object> keySet() {
return map.keySet();
}
/**
- * Store value in this Attributes and associate it with key.
+ * Stores key/value pairs in this {@code Attributes}.
*
* @param key
- * The key to associate with value.
+ * the key to associate with value.
* @param value
- * The value to store in this Attributes
- * @return The value being stored
- *
+ * the value to store in this {@code Attributes}.
+ * @return the value being stored.
* @exception ClassCastException
- * when key is not an Attributes.Name or value is not a
- * String
+ * when key is not an {@code Attributes.Name} or value is not
+ * a {@code String}.
*/
@SuppressWarnings("cast")
// Require cast to force ClassCastException
@@ -269,10 +383,12 @@
}
/**
- * Store all the key.value pairs in the argument in this Attributes.
+ * Stores all the key/value pairs in the argument in this {@code
+ * Attributes}.
*
* @param attrib
- * the associations to store (must be of type Attributes).
+ * the associations to store (must be of type {@code
+ * Attributes}).
*/
public void putAll(Map<?, ?> attrib) {
if (attrib == null || !(attrib instanceof Attributes)) {
@@ -282,29 +398,33 @@
}
/**
- * Deletes the key/value pair with key key from this Attributes.
+ * Deletes the key/value pair with key {@code key} from this {@code
+ * Attributes}.
*
* @param key
- * The key to remove
- * @return the values associated with the removed key, null if not present.
+ * the key to remove.
+ * @return the values associated with the removed key, {@code null} if not
+ * present.
*/
public Object remove(Object key) {
return map.remove(key);
}
/**
- * Returns the number of key.value pairs associated with this Attributes.
+ * Returns the number of key/value pairs associated with this {@code
+ * Attributes}.
*
- * @return the size of this Attributes
+ * @return the size of this {@code Attributes}.
*/
public int size() {
return map.size();
}
/**
- * Returns a Collection of all the values present in this Attributes.
- *
- * @return a Collection of all values present
+ * Returns a collection of all the values present in this {@code
+ * Attributes}.
+ *
+ * @return a collection of all values present.
*/
public Collection<Object> values() {
return map.values();
@@ -324,9 +444,9 @@
}
/**
- * Returns the hashCode of this Attributes
+ * Returns the hash code of this {@code Attributes}.
*
- * @return the hashCode of this Object.
+ * @return the hash code of this object.
*/
@Override
public int hashCode() {
@@ -334,10 +454,14 @@
}
/**
- * Determines if this Attributes and the parameter Attributes are equal. Two
- * Attributes instances are equal if they contain the same keys and values.
- *
- * @return true if the Attributes are equals, false otherwise
+ * Determines if this {@code Attributes} and the parameter {@code
+ * Attributes} are equal. Two {@code Attributes} instances are equal if they
+ * contain the same keys and values.
+ *
+ * @param obj
+ * the object with which this {@code Attributes} is compared.
+ * @return {@code true} if the {@code Attributes} are equal, {@code false}
+ * otherwise.
*/
@Override
public boolean equals(Object obj) {
@@ -351,37 +475,39 @@
}
/**
- * Returns the value associated with the parameter Attributes.Name key.
+ * Returns the value associated with the parameter {@code Attributes.Name}
+ * key.
*
* @param name
- * The key to obtain the value for.
- * @return the String associated with name, or null if name is not a valid
- * key
+ * the key to obtain the value for.
+ * @return the {@code String} associated with name, or {@code null} if name
+ * is not a valid key.
*/
public String getValue(Attributes.Name name) {
return (String) map.get(name);
}
/**
- * Returns the String associated with the parameter name.
+ * Returns the string associated with the parameter name.
*
* @param name
- * The key to obtain the value for.
- * @return the String associated with name, or null if name is not a valid
- * key
+ * the key to obtain the value for.
+ * @return the string associated with name, or {@code null} if name is not a
+ * valid key.
*/
public String getValue(String name) {
return (String) map.get(new Attributes.Name(name));
}
/**
- * Stores value val against key name in this Attributes
+ * Stores the value {@code val} associated with the key {@code name} in this
+ * {@code Attributes}.
*
* @param name
- * The key to store against.
+ * the key to store.
* @param val
- * The value to store in this Attributes
- * @return the Value being stored
+ * the value to store in this {@code Attributes}.
+ * @return the value being stored.
*/
public String putValue(String name, String val) {
return (String) map.put(new Attributes.Name(name), val);
Modified: harmony/enhanced/classlib/trunk/modules/archive/src/main/java/java/util/jar/JarEntry.java
URL: http://svn.apache.org/viewvc/harmony/enhanced/classlib/trunk/modules/archive/src/main/java/java/util/jar/JarEntry.java?rev=768128&r1=768127&r2=768128&view=diff
==============================================================================
--- harmony/enhanced/classlib/trunk/modules/archive/src/main/java/java/util/jar/JarEntry.java (original)
+++ harmony/enhanced/classlib/trunk/modules/archive/src/main/java/java/util/jar/JarEntry.java Fri Apr 24 02:23:48 2009
@@ -31,8 +31,9 @@
import javax.security.auth.x500.X500Principal;
/**
- * JarEntry represents an entry in a JAR file.
- *
+ * Represents a single file in a JAR archive together with the manifest
+ * attributes and digital signatures associated with it.
+ *
* @see JarFile
* @see JarInputStream
*/
@@ -49,17 +50,17 @@
private boolean isFactoryChecked = false;
/**
- * Create a new JarEntry named name
+ * Creates a new {@code JarEntry} named name.
*
* @param name
- * The name of the new JarEntry
+ * The name of the new {@code JarEntry}.
*/
public JarEntry(String name) {
super(name);
}
/**
- * Create a new JarEntry using the values obtained from entry.
+ * Creates a new {@code JarEntry} using the values obtained from entry.
*
* @param entry
* The ZipEntry to obtain values from.
@@ -69,12 +70,13 @@
}
/**
- * Returns the Attributes object associated with this entry or null if none
- * exists.
+ * Returns the {@code Attributes} object associated with this entry or
+ * {@code null} if none exists.
*
- * @return java.util.jar.Attributes Attributes for this entry
- * @exception java.io.IOException
- * If an error occurs obtaining the Attributes
+ * @return the {@code Attributes} for this entry.
+ * @exception IOException
+ * If an error occurs obtaining the {@code Attributes}.
+ * @see Attributes
*/
public Attributes getAttributes() throws IOException {
if (attributes != null || parentJar == null) {
@@ -88,10 +90,13 @@
}
/**
- * Returns an array of Certificate Objects associated with this entry or
- * null if none exist.
+ * Returns an array of {@code Certificate} Objects associated with this
+ * entry or {@code null} if none exists. Make sure that the everything is
+ * read from the input stream before calling this method, or else the method
+ * returns {@code null}.
*
- * @return java.security.cert.Certificate[] Certificates for this entry
+ * @return the certificate for this entry.
+ * @see java.security.cert.Certificate
*/
public Certificate[] getCertificates() {
if (null == parentJar) {
@@ -109,10 +114,11 @@
}
/**
- * Create a new JarEntry using the values obtained from je.
+ * Create a new {@code JarEntry} using the values obtained from the
+ * argument.
*
* @param je
- * The JarEntry to obtain values from
+ * The {@code JarEntry} to obtain values from.
*/
public JarEntry(JarEntry je) {
super(je);
@@ -122,12 +128,13 @@
}
/**
- * Returns the code signers for the jar entry. If there is no such code
- * signers, returns null. Only when the jar entry has been completely
- * verified by reading till the end of the jar entry, can the method be
- * called. Or else the method will return null.
+ * Returns the code signers for the digital signatures associated with the
+ * JAR file. If there is no such code signer, it returns {@code null}. Make
+ * sure that the everything is read from the input stream before calling
+ * this method, or else the method returns {@code null}.
*
- * @return the code signers for the jar entry.
+ * @return the code signers for the JAR entry.
+ * @see CodeSigner
*/
public CodeSigner[] getCodeSigners() {
if (null == signers) {
Modified: harmony/enhanced/classlib/trunk/modules/archive/src/main/java/java/util/jar/JarException.java
URL: http://svn.apache.org/viewvc/harmony/enhanced/classlib/trunk/modules/archive/src/main/java/java/util/jar/JarException.java?rev=768128&r1=768127&r2=768128&view=diff
==============================================================================
--- harmony/enhanced/classlib/trunk/modules/archive/src/main/java/java/util/jar/JarException.java (original)
+++ harmony/enhanced/classlib/trunk/modules/archive/src/main/java/java/util/jar/JarException.java Fri Apr 24 02:23:48 2009
@@ -28,18 +28,18 @@
private static final long serialVersionUID = 7159778400963954473L;
/**
- * Constructs a new instance of this class with its walkback filled in.
+ * Constructs a new {@code JarException} instance.
*/
public JarException() {
super();
}
/**
- * Constructs a new instance of this class with its walkback and message
- * filled in.
- *
+ * Constructs a new {@code JarException} instance with the specified
+ * message.
+ *
* @param detailMessage
- * String The detail message for the exception.
+ * the detail message for the exception.
*/
public JarException(String detailMessage) {
super(detailMessage);
Modified: harmony/enhanced/classlib/trunk/modules/archive/src/main/java/java/util/jar/JarFile.java
URL: http://svn.apache.org/viewvc/harmony/enhanced/classlib/trunk/modules/archive/src/main/java/java/util/jar/JarFile.java?rev=768128&r1=768127&r2=768128&view=diff
==============================================================================
--- harmony/enhanced/classlib/trunk/modules/archive/src/main/java/java/util/jar/JarFile.java (original)
+++ harmony/enhanced/classlib/trunk/modules/archive/src/main/java/java/util/jar/JarFile.java Fri Apr 24 02:23:48 2009
@@ -28,13 +28,17 @@
import org.apache.harmony.archive.util.Util;
/**
- * JarFile is used to read jar entries and their associated data from jar files.
+ * {@code JarFile} is used to read jar entries and their associated data from
+ * jar files.
*
* @see JarInputStream
* @see JarEntry
*/
public class JarFile extends ZipFile {
+ /**
+ * The MANIFEST file name.
+ */
public static final String MANIFEST_NAME = "META-INF/MANIFEST.MF"; //$NON-NLS-1$
static final String META_DIR = "META-INF/"; //$NON-NLS-1$
@@ -120,26 +124,26 @@
}
/**
- * Create a new JarFile using the contents of file.
+ * Create a new {@code JarFile} using the contents of the specified file.
*
* @param file
- * java.io.File
- * @exception java.io.IOException
- * If the file cannot be read.
+ * the JAR file as {@link File}.
+ * @throws IOException
+ * If the file cannot be read.
*/
public JarFile(File file) throws IOException {
this(file, true);
}
/**
- * Create a new JarFile using the contents of file.
+ * Create a new {@code JarFile} using the contents of the specified file.
*
* @param file
- * java.io.File
+ * the JAR file as {@link File}.
* @param verify
- * verify a signed jar file
- * @exception java.io.IOException
- * If the file cannot be read.
+ * if this JAR file is signed whether it must be verified.
+ * @throws IOException
+ * If the file cannot be read.
*/
public JarFile(File file, boolean verify) throws IOException {
super(file);
@@ -150,16 +154,17 @@
}
/**
- * Create a new JarFile using the contents of file.
+ * Create a new {@code JarFile} using the contents of file.
*
* @param file
- * java.io.File
+ * the JAR file as {@link File}.
* @param verify
- * verify a signed jar file
+ * if this JAR filed is signed whether it must be verified.
* @param mode
- * the mode to use, either OPEN_READ or OPEN_READ | OPEN_DELETE
- * @exception java.io.IOException
- * If the file cannot be read.
+ * the mode to use, either {@link ZipFile#OPEN_READ OPEN_READ} or
+ * {@link ZipFile#OPEN_DELETE OPEN_DELETE}.
+ * @throws IOException
+ * If the file cannot be read.
*/
public JarFile(File file, boolean verify, int mode) throws IOException {
super(file, mode);
@@ -170,12 +175,13 @@
}
/**
- * Create a new JarFile from the contents of the file specified by filename.
+ * Create a new {@code JarFile} from the contents of the file specified by
+ * filename.
*
* @param filename
- * java.lang.String
- * @exception java.io.IOException
- * If fileName cannot be opened for reading.
+ * the file name referring to the JAR file.
+ * @throws IOException
+ * if file name cannot be opened for reading.
*/
public JarFile(String filename) throws IOException {
this(filename, true);
@@ -183,14 +189,15 @@
}
/**
- * Create a new JarFile from the contents of the file specified by filename.
+ * Create a new {@code JarFile} from the contents of the file specified by
+ * {@code filename}.
*
* @param filename
- * java.lang.String
+ * the file name referring to the JAR file.
* @param verify
- * verify a signed jar file
- * @exception java.io.IOException
- * If fileName cannot be opened for reading.
+ * if this JAR filed is signed whether it must be verified.
+ * @throws IOException
+ * If file cannot be opened or read.
*/
public JarFile(String filename, boolean verify) throws IOException {
super(filename);
@@ -201,11 +208,12 @@
}
/**
- * Return an enumeration containing the JarEntrys contained in this JarFile.
+ * Return an enumeration containing the {@code JarEntrys} contained in this
+ * {@code JarFile}.
*
- * @return java.util.Enumeration
- * @exception java.lang.IllegalStateException
- * If this JarFile has been closed.
+ * @return the {@code Enumeration} containing the JAR entries.
+ * @throws IllegalStateException
+ * if this {@code JarFile} is closed.
*/
@Override
public Enumeration<JarEntry> entries() {
@@ -233,21 +241,27 @@
}
/**
- * Return the JarEntry specified by name or null if no such entry exists.
+ * Return the {@code JarEntry} specified by its name or {@code null} if no
+ * such entry exists.
*
* @param name
- * the name of the entry in the jar file
- * @return java.util.jar.JarEntry
+ * the name of the entry in the JAR file.
+ * @return the JAR entry defined by the name.
*/
public JarEntry getJarEntry(String name) {
return (JarEntry) getEntry(name);
}
/**
- * Returns the Manifest object associated with this JarFile or null if no
- * manifest entry exists.
+ * Returns the {@code Manifest} object associated with this {@code JarFile}
+ * or {@code null} if no MANIFEST entry exists.
*
- * @return java.util.jar.Manifest
+ * @return the MANIFEST.
+ * @throws IOException
+ * if an error occurs reading the MANIFEST file.
+ * @throws IllegalStateException
+ * if the jar file is closed.
+ * @see Manifest
*/
public Manifest getManifest() throws IOException {
if (manifest != null) {
@@ -318,13 +332,14 @@
}
/**
- * Return an InputStream for reading the decompressed contents of ze.
+ * Return an {@code InputStream} for reading the decompressed contents of
+ * ZIP entry.
*
* @param ze
- * the ZipEntry to read from
- * @return java.io.InputStream
- * @exception java.io.IOException
- * If an error occurred while creating the InputStream.
+ * the ZIP entry to be read.
+ * @return the input stream to read from.
+ * @throws IOException
+ * if an error occurred while creating the input stream.
*/
@Override
public InputStream getInputStream(ZipEntry ze) throws IOException {
@@ -361,11 +376,12 @@
}
/**
- * Return the JarEntry specified by name or null if no such entry exists
+ * Return the {@code JarEntry} specified by name or {@code null} if no such
+ * entry exists.
*
* @param name
- * the name of the entry in the jar file
- * @return java.util.jar.JarEntry
+ * the name of the entry in the JAR file.
+ * @return the ZIP entry extracted.
*/
@Override
public ZipEntry getEntry(String name) {
Modified: harmony/enhanced/classlib/trunk/modules/archive/src/main/java/java/util/jar/JarInputStream.java
URL: http://svn.apache.org/viewvc/harmony/enhanced/classlib/trunk/modules/archive/src/main/java/java/util/jar/JarInputStream.java?rev=768128&r1=768127&r2=768128&view=diff
==============================================================================
--- harmony/enhanced/classlib/trunk/modules/archive/src/main/java/java/util/jar/JarInputStream.java (original)
+++ harmony/enhanced/classlib/trunk/modules/archive/src/main/java/java/util/jar/JarInputStream.java Fri Apr 24 02:23:48 2009
@@ -26,6 +26,12 @@
import org.apache.harmony.luni.util.Util;
+/**
+ * The input stream from which the JAR file to be read may be fetched. It is
+ * used like the {@code ZipInputStream}.
+ *
+ * @see ZipInputStream
+ */
public class JarInputStream extends ZipInputStream {
private Manifest manifest;
@@ -43,7 +49,15 @@
private OutputStream verStream;
/**
- * Constructs a new JarInputStream from stream
+ * Constructs a new {@code JarInputStream} from an input stream.
+ *
+ * @param stream
+ * the input stream containing the JAR file.
+ * @param verify
+ * if the file should be verified with a {@code JarVerifier}.
+ * @throws IOException
+ * If an error occurs reading entries from the input stream.
+ * @see ZipInputStream#ZipInputStream(InputStream)
*/
public JarInputStream(InputStream stream, boolean verify)
throws IOException {
@@ -85,32 +99,55 @@
}
}
+ /**
+ * Constructs a new {@code JarInputStream} from an input stream.
+ *
+ * @param stream
+ * the input stream containing the JAR file.
+ * @throws IOException
+ * If an error occurs reading entries from the input stream.
+ * @see ZipInputStream#ZipInputStream(InputStream)
+ */
public JarInputStream(InputStream stream) throws IOException {
this(stream, true);
}
/**
- * Returns the Manifest object associated with this JarInputStream or null
- * if no manifest entry exists.
+ * Returns the {@code Manifest} object associated with this {@code
+ * JarInputStream} or {@code null} if no manifest entry exists.
*
- * @return java.util.jar.Manifest
+ * @return the MANIFEST specifying the contents of the JAR file.
*/
public Manifest getManifest() {
return manifest;
}
/**
- * Returns the next JarEntry contained in this stream or null if no more
- * entries are present.
+ * Returns the next {@code JarEntry} contained in this stream or {@code
+ * null} if no more entries are present.
*
- * @return java.util.jar.JarEntry
- * @exception java.io.IOException
- * If an error occurs while reading the entry
+ * @return the next JAR entry.
+ * @throws IOException
+ * if an error occurs while reading the entry.
*/
public JarEntry getNextJarEntry() throws IOException {
return (JarEntry) getNextEntry();
}
+ /**
+ * Reads up to {@code length} of decompressed data and stores it in
+ * {@code buffer} starting at {@code offset}.
+ *
+ * @param buffer
+ * Buffer to store into
+ * @param offset
+ * offset in buffer to store at
+ * @param length
+ * number of bytes to store
+ * @return Number of uncompressed bytes read
+ * @throws IOException
+ * if an IOException occurs.
+ */
@Override
public int read(byte[] buffer, int offset, int length) throws IOException {
if (mEntry != null) {
@@ -143,12 +180,12 @@
}
/**
- * Returns the next ZipEntry contained in this stream or null if no more
- * entries are present.
+ * Returns the next {@code ZipEntry} contained in this stream or {@code
+ * null} if no more entries are present.
*
- * @return java.util.zip.ZipEntry
- * @exception java.io.IOException
- * If an error occurs while reading the entry
+ * @return the next extracted ZIP entry.
+ * @throws IOException
+ * if an error occurs while reading the entry.
*/
@Override
public ZipEntry getNextEntry() throws IOException {
Modified: harmony/enhanced/classlib/trunk/modules/archive/src/main/java/java/util/jar/JarOutputStream.java
URL: http://svn.apache.org/viewvc/harmony/enhanced/classlib/trunk/modules/archive/src/main/java/java/util/jar/JarOutputStream.java?rev=768128&r1=768127&r2=768128&view=diff
==============================================================================
--- harmony/enhanced/classlib/trunk/modules/archive/src/main/java/java/util/jar/JarOutputStream.java (original)
+++ harmony/enhanced/classlib/trunk/modules/archive/src/main/java/java/util/jar/JarOutputStream.java Fri Apr 24 02:23:48 2009
@@ -23,23 +23,24 @@
import java.util.zip.ZipOutputStream;
/**
- * The JarOutputStream is used to output data in JarFile format.
+ * The {@code JarOutputStream} is used to write data in the {@code JarFile}
+ * format to an arbitrary output stream
*/
public class JarOutputStream extends ZipOutputStream {
private Manifest manifest;
/**
- * Constructs a new JarOutputStream using os as the underlying stream.
- * Manifest information for the JarFile to be written is obtained from the
- * parameter Manifest, mf.
+ * Constructs a new {@code JarOutputStream} using an output stream. The
+ * content of the {@code Manifest} must match the JAR entry information
+ * written subsequently to the stream.
*
* @param os
- * The OutputStream to write to
+ * the {@code OutputStream} to write to
* @param mf
- * The Manifest to output for this Jar.
- * @exception IOException
- * If an error occurs creating the JarOutputStream
+ * the {@code Manifest} to output for this JAR file.
+ * @throws IOException
+ * if an error occurs creating the {@code JarOutputStream}.
*/
public JarOutputStream(OutputStream os, Manifest mf) throws IOException {
super(os);
@@ -54,12 +55,13 @@
}
/**
- * Constructs a new JarOutputStream using os as the underlying stream.
+ * Constructs a new {@code JarOutputStream} using an arbitrary output
+ * stream.
*
* @param os
- * The OutputStream to write to
- * @exception IOException
- * If an error occurs creating the JarOutputStream
+ * the {@code OutputStream} to write to.
+ * @throws IOException
+ * if an error occurs creating the {@code JarOutputStream}.
*/
@SuppressWarnings("unused")
public JarOutputStream(OutputStream os) throws IOException {
@@ -67,14 +69,14 @@
}
/**
- * Writes the specified entry to the underlying stream. The previous entry
- * is closed if it is still open.
- *
+ * Writes the specified ZIP entry to the underlying stream. The previous
+ * entry is closed if it is still open.
*
* @param ze
- * The ZipEntry to write
- * @exception IOException
- * If an error occurs writing the entry
+ * the {@code ZipEntry} to write to.
+ * @throws IOException
+ * if an error occurs writing to the entry.
+ * @see ZipEntry
*/
@Override
public void putNextEntry(ZipEntry ze) throws IOException {
Modified: harmony/enhanced/classlib/trunk/modules/archive/src/main/java/java/util/jar/JarVerifier.java
URL: http://svn.apache.org/viewvc/harmony/enhanced/classlib/trunk/modules/archive/src/main/java/java/util/jar/JarVerifier.java?rev=768128&r1=768127&r2=768128&view=diff
==============================================================================
--- harmony/enhanced/classlib/trunk/modules/archive/src/main/java/java/util/jar/JarVerifier.java (original)
+++ harmony/enhanced/classlib/trunk/modules/archive/src/main/java/java/util/jar/JarVerifier.java Fri Apr 24 02:23:48 2009
@@ -39,18 +39,16 @@
/**
* Non-public class used by {@link JarFile} and {@link JarInputStream} to manage
- * the verification of signed jars. <code>JarFile</code> and
- * <code>JarInputStream</code> objects will be expected to have a
- * <code>JarVerifier</code> instance member which can be used to carry out the
- * tasks associated with verifying a signed jar. These tasks would typically
- * include:
+ * the verification of signed JARs. {@code JarFile} and {@code JarInputStream}
+ * objects are expected to have a {@code JarVerifier} instance member which
+ * can be used to carry out the tasks associated with verifying a signed JAR.
+ * These tasks would typically include:
* <ul>
* <li>verification of all signed signature files
- * <li>confirmation that all signed data was signed only by the party or
- * parties specified in the signature block data
- * <li>verification that the contents of all signature files (i.e.
- * <code>.SF</code> files) agree with the jar entries information found in the
- * jar manifest.
+ * <li>confirmation that all signed data was signed only by the party or parties
+ * specified in the signature block data
+ * <li>verification that the contents of all signature files (i.e. {@code .SF}
+ * files) agree with the JAR entries information found in the JAR manifest.
* </ul>
*/
class JarVerifier {
@@ -134,24 +132,24 @@
}
/**
- * Constructs and answers with a new instance of JarVerifier.
+ * Constructs and returns a new instance of {@code JarVerifier}.
*
* @param name
- * the name of the jar file being verified.
+ * the name of the JAR file being verified.
*/
JarVerifier(String name) {
jarName = name;
}
/**
- * Called for each new jar entry read in from the input stream. This method
- * constructs and returns a new {@link VerifierEntry} which contains the
- * certificates used to sign the entry and its hash value as specified in
- * the jar manifest.
+ * Invoked for each new JAR entry read operation from the input
+ * stream. This method constructs and returns a new {@link VerifierEntry}
+ * which contains the certificates used to sign the entry and its hash value
+ * as specified in the JAR MANIFEST format.
*
* @param name
- * the name of an entry in a jar file which is <b>not</b> in the
- * <code>META-INF</code> directory.
+ * the name of an entry in a JAR file which is <b>not</b> in the
+ * {@code META-INF} directory.
* @return a new instance of {@link VerifierEntry} which can be used by
* callers as an {@link OutputStream}.
*/
@@ -224,16 +222,16 @@
}
/**
- * Add a new meta entry to the internal collection of data held on each jar
- * entry in the <code>META-INF</code> directory including the manifest
- * file itself. Files associated with the signing of a jar would also be
+ * Add a new meta entry to the internal collection of data held on each JAR
+ * entry in the {@code META-INF} directory including the manifest
+ * file itself. Files associated with the signing of a JAR would also be
* added to this collection.
*
* @param name
- * the name of the file located in the <code>META-INF</code>
+ * the name of the file located in the {@code META-INF}
* directory.
* @param buf
- * the file bytes for the file called <code>name</code>.
+ * the file bytes for the file called {@code name}.
* @see #removeMetaEntries()
*/
void addMetaEntry(String name, byte[] buf) {
@@ -241,19 +239,19 @@
}
/**
- * If the associated jar file is signed, check on the validity of all of the
+ * If the associated JAR file is signed, check on the validity of all of the
* known signatures.
*
- * @return <code>true</code> if the associated jar is signed and an
- * internal check verifies the validity of the signature(s).
- * <code>false</code> if the associated jar file has no entries at
- * all in its <code>META-INF</code> directory. This situation is
- * indicative of an invalid jar file.
+ * @return {@code true} if the associated JAR is signed and an internal
+ * check verifies the validity of the signature(s). {@code false} if
+ * the associated JAR file has no entries at all in its {@code
+ * META-INF} directory. This situation is indicative of an invalid
+ * JAR file.
* <p>
- * Will also return true if the jar file is <i>not</i> signed.
- * </p>
+ * Will also return {@code true} if the JAR file is <i>not</i>
+ * signed.
* @throws SecurityException
- * if the jar file is signed and it is determined that a
+ * if the JAR file is signed and it is determined that a
* signature block file contains an invalid signature for the
* corresponding signature file.
*/
@@ -301,7 +299,7 @@
new ByteArrayInputStream(sBlockBytes));
/*
* Recursive call in loading security provider related class which
- * is in a signed jar.
+ * is in a signed JAR.
*/
if (null == metaEntries) {
return;
@@ -434,11 +432,11 @@
/**
* Returns all of the {@link java.security.cert.Certificate} instances that
- * were used to verify the signature on the jar entry called
- * <code>name</code>.
+ * were used to verify the signature on the JAR entry called
+ * {@code name}.
*
* @param name
- * the name of a jar entry.
+ * the name of a JAR entry.
* @return an array of {@link java.security.cert.Certificate}.
*/
Certificate[] getCertificates(String name) {
@@ -451,7 +449,7 @@
/**
* Remove all entries from the internal collection of data held about each
- * jar entry in the <code>META-INF</code> directory.
+ * JAR entry in the {@code META-INF} directory.
*
* @see #addMetaEntry(String, byte[])
*/
@@ -460,23 +458,21 @@
}
/**
- * Returns a <code>Vector</code> of all of the
+ * Returns a {@code Vector} of all of the
* {@link java.security.cert.Certificate}s that are associated with the
* signing of the named signature file.
*
* @param signatureFileName
- * the name of a signature file
+ * the name of a signature file.
* @param certificates
- * a <code>Map</code> of all of the certificate chains
- * discovered so far while attempting to verify the jar that
- * contains the signature file <code>signatureFileName</code>.
- * This object will have been previously set in the course of one
- * or more calls to
+ * a {@code Map} of all of the certificate chains discovered so
+ * far while attempting to verify the JAR that contains the
+ * signature file {@code signatureFileName}. This object is
+ * previously set in the course of one or more calls to
* {@link #verifyJarSignatureFile(String, String, String, Map, Map)}
- * where it was passed in as the last argument.
- * @return all of the <code>Certificate</code> entries for the signer of
- * the jar whose actions led to the creation of the named signature
- * file.
+ * where it was passed as the last argument.
+ * @return all of the {@code Certificate} entries for the signer of the JAR
+ * whose actions led to the creation of the named signature file.
*/
public static Vector<Certificate> getSignerCertificates(
String signatureFileName, Map<String, Certificate[]> certificates) {
Modified: harmony/enhanced/classlib/trunk/modules/archive/src/main/java/java/util/jar/Manifest.java
URL: http://svn.apache.org/viewvc/harmony/enhanced/classlib/trunk/modules/archive/src/main/java/java/util/jar/Manifest.java?rev=768128&r1=768127&r2=768128&view=diff
==============================================================================
--- harmony/enhanced/classlib/trunk/modules/archive/src/main/java/java/util/jar/Manifest.java (original)
+++ harmony/enhanced/classlib/trunk/modules/archive/src/main/java/java/util/jar/Manifest.java Fri Apr 24 02:23:48 2009
@@ -34,8 +34,8 @@
import org.apache.harmony.luni.util.ThreadLocalCache;
/**
- * The Manifest class is used to obtain attribute information for a JarFile and
- * its entries.
+ * The {@code Manifest} class is used to obtain attribute information for a
+ * {@code JarFile} and its entries.
*/
public class Manifest implements Cloneable {
static final int LINE_LENGTH_LIMIT = 72;
@@ -75,21 +75,20 @@
private int mainEnd;
/**
- * Constructs a new Manifest instance.
+ * Creates a new {@code Manifest} instance.
*/
public Manifest() {
super();
}
/**
- * Constructs a new Manifest instance using the attributes obtained from is.
+ * Creates a new {@code Manifest} instance using the attributes obtained
+ * from the input stream.
*
* @param is
- * InputStream to parse for attributes
- *
+ * {@code InputStream} to parse for attributes.
* @throws IOException
- * if an IO error occurs while creating this Manifest
- *
+ * if an IO error occurs while creating this {@code Manifest}
*/
public Manifest(InputStream is) throws IOException {
super();
@@ -97,11 +96,11 @@
}
/**
- * Constructs a new Manifest instance. The new instance will have the same
- * attributes as those found in the parameter Manifest.
+ * Creates a new {@code Manifest} instance. The new instance will have the
+ * same attributes as those found in the parameter {@code Manifest}.
*
* @param man
- * Manifest instance to obtain attributes from
+ * {@code Manifest} instance to obtain attributes from.
*/
@SuppressWarnings("unchecked")
public Manifest(Manifest man) {
@@ -118,8 +117,8 @@
}
/**
- * Resets the both the mainAttributes as well as the entry Attributes
- * associated with this Manifest.
+ * Resets the both the main attributes as well as the entry attributes
+ * associated with this {@code Manifest}.
*/
public void clear() {
im = null;
@@ -128,20 +127,23 @@
}
/**
- * Returns the Attributes associated with the parameter entry name
+ * Returns the {@code Attributes} associated with the parameter entry
+ * {@code name}.
*
* @param name
- * The name of the entry to obtain Attributes for.
- * @return The Attributes for the entry or null if the entry does not exist.
+ * the name of the entry to obtain {@code Attributes} from.
+ * @return the Attributes for the entry or {@code null} if the entry does
+ * not exist.
*/
public Attributes getAttributes(String name) {
return getEntries().get(name);
}
/**
- * Returns a Map containing the Attributes for each entry in the Manifest.
+ * Returns a map containing the {@code Attributes} for each entry in the
+ * {@code Manifest}.
*
- * @return A Map of entry attributes
+ * @return the map of entry attributes.
*/
public Map<String, Attributes> getEntries() {
initEntries();
@@ -161,19 +163,20 @@
}
/**
- * Returns the main Attributes of the JarFile.
+ * Returns the main {@code Attributes} of the {@code JarFile}.
*
- * @return Main Attributes associated with the source JarFile
+ * @return main {@code Attributes} associated with the source {@code
+ * JarFile}.
*/
public Attributes getMainAttributes() {
return mainAttributes;
}
/**
- * Creates a copy of this Manifest. The returned Manifest will equal the
- * Manifest from which it was cloned.
+ * Creates a copy of this {@code Manifest}. The returned {@code Manifest}
+ * will equal the {@code Manifest} from which it was cloned.
*
- * @return A copy of the receiver.
+ * @return a copy of this instance.
*/
@Override
public Object clone() {
@@ -182,26 +185,25 @@
/**
* Writes out the attribute information of the receiver to the specified
- * OutputStream
+ * {@code OutputStream}.
*
* @param os
- * The OutputStream to write to.
- *
+ * The {@code OutputStream} to write to.
* @throws IOException
- * If an error occurs writing the Manifest
+ * If an error occurs writing the {@code Manifest}.
*/
public void write(OutputStream os) throws IOException {
write(this, os);
}
/**
- * Constructs a new Manifest instance obtaining Attribute information from
- * the parameter InputStream.
+ * Constructs a new {@code Manifest} instance obtaining attribute
+ * information from the specified input stream.
*
* @param is
- * The InputStream to read from
+ * The {@code InputStream} to read from.
* @throws IOException
- * If an error occurs reading the Manifest.
+ * If an error occurs reading the {@code Manifest}.
*/
public void read(InputStream is) throws IOException {
byte[] buf;
@@ -272,9 +274,9 @@
}
/**
- * Returns the hashCode for this instance.
+ * Returns the hash code for this instance.
*
- * @return This Manifest's hashCode
+ * @return this {@code Manifest}'s hashCode.
*/
@Override
public int hashCode() {
@@ -282,14 +284,13 @@
}
/**
- * Determines if the receiver is equal to the parameter Object. Two
- * Manifests are equal if they have identical main Attributes as well as
- * identical entry Attributes.
+ * Determines if the receiver is equal to the parameter object. Two {@code
+ * Manifest}s are equal if they have identical main attributes as well as
+ * identical entry attributes.
*
* @param o
- * The Object to compare against.
- * @return <code>true</code> if the manifests are equal,
- * <code>false</code> otherwise
+ * the object to compare against.
+ * @return {@code true} if the manifests are equal, {@code false} otherwise
*/
@Override
public boolean equals(Object o) {
@@ -318,16 +319,15 @@
}
/**
- * Writes out the attribute information of the receiver to the specified
- * OutputStream
+ * Writes out the attribute information of the specified manifest to the
+ * specified {@code OutputStream}
*
* @param manifest
- * the attribute information of the receiver
+ * the manifest to write out.
* @param out
- * The OutputStream to write to.
- *
+ * The {@code OutputStream} to write to.
* @throws IOException
- * If an error occurs writing the Manifest
+ * If an error occurs writing the {@code Manifest}.
*/
static void write(Manifest manifest, OutputStream out) throws IOException {
CharsetEncoder encoder = ThreadLocalCache.utf8Encoder.get();
Modified: harmony/enhanced/classlib/trunk/modules/archive/src/main/java/java/util/jar/Pack200.java
URL: http://svn.apache.org/viewvc/harmony/enhanced/classlib/trunk/modules/archive/src/main/java/java/util/jar/Pack200.java?rev=768128&r1=768127&r2=768128&view=diff
==============================================================================
--- harmony/enhanced/classlib/trunk/modules/archive/src/main/java/java/util/jar/Pack200.java (original)
+++ harmony/enhanced/classlib/trunk/modules/archive/src/main/java/java/util/jar/Pack200.java Fri Apr 24 02:23:48 2009
@@ -26,9 +26,7 @@
import java.util.SortedMap;
/**
- * Class that initialize Packer and Unpacker
- *
- * See JSR200
+ * Class factory for {@link Pack200.Packer} and {@link Pack200.Unpacker}.
*/
public abstract class Pack200 {
@@ -44,11 +42,14 @@
}
/**
- * The method first read from system property for the classname of a Packer,
- * if such property exists, the class shall be initialized; or the default
- * Packer will be returned
+ * Returns a new instance of a packer engine.
+ * <p>
+ * The implementation of the packer engine is defined by the system property
+ * {@code 'java.util.jar.Pack200.Packer'}. If this system property is
+ * defined an instance of the specified class is returned, otherwise the
+ * system's default implementation is returned.
*
- * @return a instance of Packer
+ * @return an instance of {@code Packer}
*/
public static Pack200.Packer newPacker() {
return (Packer) AccessController
@@ -71,11 +72,14 @@
}
/**
- * The method first read from system property for the classname of a
- * Unpacker, if such property exists, the class shall be initialized; or the
- * default Unpacker will be returned
+ * Returns a new instance of a unpacker engine.
+ * <p>
+ * The implementation of the unpacker engine is defined by the system
+ * property {@code 'java.util.jar.Pack200.Unpacker'}. If this system
+ * property is defined an instance of the specified class is returned,
+ * otherwise the system's default implementation is returned.
*
- * @return a instance of Unpacker
+ * @return a instance of {@code Unpacker}.
*/
public static Pack200.Unpacker newUnpacker() {
return (Unpacker) AccessController
@@ -95,24 +99,23 @@
}
/**
- * interface of Packer
- *
- * See JSR 200 specification
+ * The interface defining the API for converting a JAR file to an output
+ * stream in the Pack200 format.
*/
public static interface Packer {
/**
- * the format of a class attribute name
+ * the format of a class attribute name.
*/
static final String CLASS_ATTRIBUTE_PFX = "pack.class.attribute."; //$NON-NLS-1$
/**
- * the format of a code attribute name
+ * the format of a code attribute name.
*/
static final String CODE_ATTRIBUTE_PFX = "pack.code.attribute."; //$NON-NLS-1$
/**
- * the deflation hint to set in the output archive
+ * the deflation hint to set in the output archive.
*/
static final String DEFLATE_HINT = "pack.deflate.hint";//$NON-NLS-1$
@@ -122,48 +125,48 @@
static final String EFFORT = "pack.effort";//$NON-NLS-1$
/**
- * a String of error
+ * a String representation for {@code error}.
*/
static final String ERROR = "error";//$NON-NLS-1$
/**
- * a String of false
+ * a String representation of {@code false}.
*/
static final String FALSE = "false";//$NON-NLS-1$
/**
- * the format of a field attribute name
+ * the format of a field attribute name.
*/
static final String FIELD_ATTRIBUTE_PFX = "pack.field.attribute.";//$NON-NLS-1$
/**
- * a String of keep
+ * a String representation for {@code keep}.
*/
static final String KEEP = "keep";//$NON-NLS-1$
/**
- * decide if all elements shall transmit in their original order
+ * decide if all elements shall transmit in their original order.
*/
static final String KEEP_FILE_ORDER = "pack.keep.file.order";//$NON-NLS-1$
/**
- * a String of latest
+ * a String representation for {@code latest}.
*/
static final String LATEST = "latest";//$NON-NLS-1$
/**
- * the format of a method attribute name
+ * the format of a method attribute name.
*/
static final String METHOD_ATTRIBUTE_PFX = "pack.method.attribute.";//$NON-NLS-1$
/**
- * Packer shall attempt to determine the latest modification time if
- * this is set to LASTEST
+ * if it shall attempt to determine the latest modification time if this
+ * is set to {@code LATEST}.
*/
static final String MODIFICATION_TIME = "pack.modification.time";//$NON-NLS-1$
/**
- * a String of pass
+ * a String representation of {@code pass}.
*/
static final String PASS = "pass";//$NON-NLS-1$
@@ -173,7 +176,7 @@
static final String PASS_FILE_PFX = "pack.pass.file.";//$NON-NLS-1$
/**
- * packer progress as a percentage
+ * packer progress as a percentage.
*/
static final String PROGRESS = "pack.progress";//$NON-NLS-1$
@@ -183,12 +186,12 @@
static final String SEGMENT_LIMIT = "pack.segment.limit";//$NON-NLS-1$
/**
- * a String of strip
+ * a String representation of {@code strip}.
*/
static final String STRIP = "strip";//$NON-NLS-1$
/**
- * a String of true
+ * a String representation of {@code true}.
*/
static final String TRUE = "true";//$NON-NLS-1$
@@ -198,32 +201,34 @@
static final String UNKNOWN_ATTRIBUTE = "pack.unknown.attribute";//$NON-NLS-1$
/**
- *
- * @return the properties of packer
+ * Returns a sorted map of the properties of this packer.
+ *
+ * @return the properties of the packer.
*/
SortedMap<String, String> properties();
/**
- * Pack jarfile with pack arithmetic
+ * Pack the specified JAR file to the specified output stream.
*
* @param in
- * jarfile to be compact
+ * JAR file to be compressed.
* @param out
- * stream of compact data
+ * stream of compressed data.
* @throws IOException
- * if I/O exception occurs
+ * if I/O exception occurs.
*/
void pack(JarFile in, OutputStream out) throws IOException;
/**
- * Pack jarStream with pack arithmetic
+ * Pack the data from the specified jar input stream to the specified
+ * output stream.
*
* @param in
- * stream of uncompact jar data
+ * stream of uncompressed JAR data.
* @param out
- * stream of compact data
+ * stream of compressed data.
* @throws IOException
- * if I/O exception occurs
+ * if I/O exception occurs.
*/
void pack(JarInputStream in, OutputStream out) throws IOException;
@@ -245,81 +250,83 @@
}
/**
- * interface of unpacker
- *
- * See JSR 200 specification
+ * The interface defining the API for converting a packed stream in the
+ * Pack200 format to a JAR file.
*/
public static interface Unpacker {
/**
* The String indicating if the unpacker should ignore all transmitted
- * values,can be replaced by either true or false
+ * values,can be replaced by either {@code true} or {@code false}.
*/
static final String DEFLATE_HINT = "unpack.deflate.hint";//$NON-NLS-1$
/**
- * a String of false
+ * a String representation of {@code false}.
*/
static final String FALSE = "false";//$NON-NLS-1$
/**
- * a String of keep
+ * a String representation of {@code keep}.
*/
static final String KEEP = "keep";//$NON-NLS-1$
/**
- * the progress as a percentage
+ * the progress as a {@code percentage}.
*/
static final String PROGRESS = "unpack.progress";//$NON-NLS-1$
/**
- * a String of true
+ * a String representation of {@code true}.
*/
static final String TRUE = "true";//$NON-NLS-1$
/**
- *
- * @return the properties of unpacker
+ * Returns a sorted map of the properties of this unpacker.
+ *
+ * @return the properties of unpacker.
*/
SortedMap<String, String> properties();
/**
- * unpack stream into jarfile with pack arithmetic
+ * Unpack the specified stream to the specified JAR output stream.
*
* @param in
- * stream to uncompact
+ * stream to uncompressed.
* @param out
- * jarstream of uncompact data
+ * JAR output stream of uncompressed data.
* @throws IOException
- * if I/O exception occurs
+ * if I/O exception occurs.
*/
void unpack(InputStream in, JarOutputStream out) throws IOException;
/**
- * unpack File into jarfile with pack arithmetic
+ * Unpack the contents of the specified {@code File} to the specified
+ * JAR output stream.
*
* @param in
- * file to be uncompact
+ * file to be uncompressed.
* @param out
- * jarstream of uncompact data
+ * JAR output stream of uncompressed data.
* @throws IOException
- * if I/O exception occurs
+ * if I/O exception occurs.
*/
void unpack(File in, JarOutputStream out) throws IOException;
/**
- * add a listener for PropertyChange events
+ * add a listener for {@code PropertyChange} events.
*
* @param listener
- * the listener to listen if PropertyChange events occurs
+ * the listener to listen if {@code PropertyChange} events
+ * occurs.
*/
void addPropertyChangeListener(PropertyChangeListener listener);
/**
- * remove a listener
+ * remove a listener.
*
* @param listener
- * listener to remove
+ * listener to remove.
*/
void removePropertyChangeListener(PropertyChangeListener listener);
}
Modified: harmony/enhanced/classlib/trunk/modules/archive/src/main/java/java/util/zip/Adler32.java
URL: http://svn.apache.org/viewvc/harmony/enhanced/classlib/trunk/modules/archive/src/main/java/java/util/zip/Adler32.java?rev=768128&r1=768127&r2=768128&view=diff
==============================================================================
--- harmony/enhanced/classlib/trunk/modules/archive/src/main/java/java/util/zip/Adler32.java (original)
+++ harmony/enhanced/classlib/trunk/modules/archive/src/main/java/java/util/zip/Adler32.java Fri Apr 24 02:23:48 2009
@@ -18,58 +18,66 @@
package java.util.zip;
/**
- * The Adler32 class is used to compute the Adler32 Checksum from a set of data.
+ * The Adler-32 class is used to compute the {@code Adler32} checksum from a set
+ * of data. Compared to the CRC-32 algorithm it trades reliabilty for speed.
+ * Refer to RFC 1950 for the specification.
+ *
+ * @see CRC32
*/
public class Adler32 implements java.util.zip.Checksum {
private long adler = 1;
/**
- * Returns the Adler32 checksum for all input received
+ * Returns the {@code Adler32} checksum for all input received.
*
- * @return The checksum for this instance
+ * @return The checksum for this instance.
*/
public long getValue() {
return adler;
}
/**
- * Reset this instance to its initial checksum
+ * Reset this instance to its initial checksum.
*/
public void reset() {
adler = 1;
}
/**
- * Update this Adler32 checksum using val.
+ * Update this {@code Adler32} checksum with the single byte provided as
+ * argument.
*
* @param i
- * byte to update checksum with
+ * the byte to update checksum with.
*/
public void update(int i) {
adler = updateByteImpl(i, adler);
}
/**
- * Update this Adler32 checksum using the contents of buf.
+ * Update this {@code Adler32} checksum using the contents of {@code buf}.
*
* @param buf
- * bytes to update checksum with
+ * bytes to update checksum with.
*/
public void update(byte[] buf) {
update(buf, 0, buf.length);
}
/**
- * Update this Adler32 checksum with the contents of buf, starting from
- * offset and using nbytes of data.
+ * Update this {@code Adler32} checksum with the contents of {@code buf},
+ * starting from the offset provided and reading n bytes of data.
*
* @param buf
- * buffer to obtain dat from
+ * buffer to obtain data from.
* @param off
- * offset i buf to copy from
+ * offset in {@code buf} to start reading from.
* @param nbytes
- * number of bytes from buf to use
+ * number of bytes from {@code buf} to use.
+ * @throws ArrayIndexOutOfBoundsException
+ * if {@code offset > buf.length} or {@code nbytes} is negative
+ * or {@code offset + nbytes > buf.length}.
*/
public void update(byte[] buf, int off, int nbytes) {
// avoid int overflow, check null buf
Modified: harmony/enhanced/classlib/trunk/modules/archive/src/main/java/java/util/zip/CRC32.java
URL: http://svn.apache.org/viewvc/harmony/enhanced/classlib/trunk/modules/archive/src/main/java/java/util/zip/CRC32.java?rev=768128&r1=768127&r2=768128&view=diff
==============================================================================
--- harmony/enhanced/classlib/trunk/modules/archive/src/main/java/java/util/zip/CRC32.java (original)
+++ harmony/enhanced/classlib/trunk/modules/archive/src/main/java/java/util/zip/CRC32.java Fri Apr 24 02:23:48 2009
@@ -18,7 +18,8 @@
package java.util.zip;
/**
- * The CRC32 class is used to compute a CRC32 Checksum from a set of data.
+ * The CRC32 class is used to compute a CRC32 checksum from data provided as
+ * input value.
*/
public class CRC32 implements java.util.zip.Checksum {
@@ -27,16 +28,16 @@
long tbytes = 0L;
/**
- * Returns the CRC32 Checksum for all input received.
+ * Returns the CRC32 checksum for all input received.
*
- * @return The checksum for this instance
+ * @return The checksum for this instance.
*/
public long getValue() {
return crc;
}
/**
- * Returns the CRC32 checksum to it initial state.
+ * Resets the CRC32 checksum to it initial state.
*/
public void reset() {
tbytes = crc = 0;
@@ -44,32 +45,35 @@
}
/**
- * Updates this Checksum with value val
+ * Updates this checksum with the byte value provided as integer.
+ *
+ * @param val
+ * represents the byte to update the checksum.
*/
public void update(int val) {
crc = updateByteImpl((byte) val, crc);
}
/**
- * Updates this Checksum with the bytes contained in buffer buf.
+ * Updates this checksum with the bytes contained in buffer {@code buf}.
*
* @param buf
- * Buffer to update Checksum
+ * the buffer holding the data to update the checksum with.
*/
public void update(byte[] buf) {
update(buf, 0, buf.length);
}
/**
- * Updates this Checksum with nbytes of data from buffer buf, starting at
- * offset off.
+ * Updates this checksum with n bytes of data obtained from buffer {@code
+ * buf}, starting at offset {@code off}.
*
* @param buf
- * Buffer to update Checksum
+ * the buffer to update the checksum.
* @param off
- * Offset in buf to obtain data from
+ * the offset in {@code buf} to obtain data from.
* @param nbytes
- * Number of bytes to read from buf
+ * the number of bytes to read from {@code buf}.
*/
public void update(byte[] buf, int off, int nbytes) {
// avoid int overflow, check null buf
Modified: harmony/enhanced/classlib/trunk/modules/archive/src/main/java/java/util/zip/CheckedInputStream.java
URL: http://svn.apache.org/viewvc/harmony/enhanced/classlib/trunk/modules/archive/src/main/java/java/util/zip/CheckedInputStream.java?rev=768128&r1=768127&r2=768128&view=diff
==============================================================================
--- harmony/enhanced/classlib/trunk/modules/archive/src/main/java/java/util/zip/CheckedInputStream.java (original)
+++ harmony/enhanced/classlib/trunk/modules/archive/src/main/java/java/util/zip/CheckedInputStream.java Fri Apr 24 02:23:48 2009
@@ -21,21 +21,24 @@
import java.io.InputStream;
/**
- * The CheckedInputStream class is used to maintain a running Checksum of all
- * data read from a stream.
+ * The {@code CheckedInputStream} class is used to maintain a checksum at the
+ * same time as the data, on which the checksum is computed, is read from a
+ * stream. The purpose of this checksum is to establish data integrity,
+ * comparing the computed checksum against a published checksum value.
*/
public class CheckedInputStream extends java.io.FilterInputStream {
private final Checksum check;
/**
- * Constructs a new CheckedInputStream on InputStream is. The Checksum will
- * be calculated using the algorithm implemented by csum.
+ * Constructs a new {@code CheckedInputStream} on {@code InputStream}
+ * {@code is}. The checksum will be calculated using the algorithm
+ * implemented by {@code csum}.
*
* @param is
- * InputStream to calculate checksum from
+ * the input stream to calculate checksum from.
* @param csum
- * Type of Checksum to calculate
+ * an entity implementing the checksum algorithm.
*/
public CheckedInputStream(InputStream is, Checksum csum) {
super(is);
@@ -43,10 +46,13 @@
}
/**
- * Reads a byte of data from the underlying stream and recomputes the
- * Checksum with the byte data.
+ * Reads one byte of data from the underlying input stream and updates the
+ * checksum with the byte data.
*
- * @return -1 if end of stream, a single byte value otherwise
+ * @return {@code -1} at the end of the stream, a single byte value
+ * otherwise.
+ * @throws IOException
+ * if an {@code IOException} occurs.
*/
@Override
public int read() throws IOException {
@@ -58,10 +64,21 @@
}
/**
- * Reads up to nbytes of data from the underlying stream, storing it in buf,
- * starting at offset off. The Checksum is updated with the bytes read.
+ * Reads up to n bytes of data from the underlying input stream, storing it
+ * into {@code buf}, starting at offset {@code off}. The checksum is
+ * updated with the bytes read.
*
- * @return Number of bytes read, -1 if end of stream
+ * @param buf
+ * the byte array in which to store the bytes read.
+ * @param off
+ * the initial position in {@code buf} to store the bytes read
+ * from this stream.
+ * @param nbytes
+ * the maximum number of bytes to store in {@code buf}.
+ * @return the number of bytes actually read or {@code -1} if arrived at the
+ * end of the filtered stream while reading the data.
+ * @throws IOException
+ * if this stream is closed or some I/O error occurs.
*/
@Override
public int read(byte[] buf, int off, int nbytes) throws IOException {
@@ -73,21 +90,23 @@
}
/**
- * Returns the Checksum calculated on the stream thus far.
+ * Returns the checksum calculated on the stream read so far.
*
- * @return A java.util.zip.Checksum
+ * @return the updated checksum.
*/
public Checksum getChecksum() {
return check;
}
/**
- * Skip upto nbytes of data on the underlying stream. Any skipped bytes are
- * added to the running Checksum value.
+ * Skip up to n bytes of data on the underlying input stream. Any skipped
+ * bytes are added to the running checksum value.
*
* @param nbytes
- * long Number of bytes to skip
- * @return Number of bytes skipped
+ * the number of bytes to skip.
+ * @throws IOException
+ * if this stream is closed or another I/O error occurs.
+ * @return the number of bytes skipped.
*/
@Override
public long skip(long nbytes) throws IOException {
Modified: harmony/enhanced/classlib/trunk/modules/archive/src/main/java/java/util/zip/CheckedOutputStream.java
URL: http://svn.apache.org/viewvc/harmony/enhanced/classlib/trunk/modules/archive/src/main/java/java/util/zip/CheckedOutputStream.java?rev=768128&r1=768127&r2=768128&view=diff
==============================================================================
--- harmony/enhanced/classlib/trunk/modules/archive/src/main/java/java/util/zip/CheckedOutputStream.java (original)
+++ harmony/enhanced/classlib/trunk/modules/archive/src/main/java/java/util/zip/CheckedOutputStream.java Fri Apr 24 02:23:48 2009
@@ -21,21 +21,24 @@
import java.io.OutputStream;
/**
- * The CheckedOutputStream class is used to maintain a running Checksum of all
- * data written to a stream.
+ * The {@code CheckedOutputStream} class is used to maintain a running checksum
+ * of all data written to a stream. The purpose of this checksum is to establish
+ * data integrity, by publishing the checksum to other parties wanting to read
+ * the non corrupted data.
*/
public class CheckedOutputStream extends java.io.FilterOutputStream {
private final Checksum check;
/**
- * Constructs a new CheckedOutputStream on OutputStream os. The Checksum
- * will be calculated using the algorithm implemented by csum.
+ * Constructs a new {@code CheckedOutputStream} on {@code OutputStream}
+ * {@code os}. The checksum is calculated using the algorithm implemented
+ * by {@code csum}.
*
* @param os
- * OutputStream to calculate checksum from
+ * the output stream to calculate checksum for.
* @param cs
- * Type of Checksum to calculate
+ * an entity implementing the checksum algorithm.
*/
public CheckedOutputStream(OutputStream os, Checksum cs) {
super(os);
@@ -43,23 +46,22 @@
}
/**
- * Returns the Checksum calculated on the stream thus far.
+ * Returns the checksum calculated on the stream read so far.
*
- * @return A java.util.zip.Checksum
+ * @return the updated checksum.
*/
public Checksum getChecksum() {
return check;
}
/**
- * Writes byte value val to the underlying stream. The Checksum is updated
- * with val.
+ * Writes the specified byte to the underlying stream. The checksum is
+ * updated with {@code val}.
*
* @param val
- * Value of the byte to write out
- *
+ * the data value to written to the output stream.
* @throws IOException
- * if an IO error has occured
+ * if an IO error has occurred.
*/
@Override
public void write(int val) throws IOException {
@@ -68,18 +70,18 @@
}
/**
- * Writes nbytes of data from buf starting at offset off to the underlying
- * stream. The Checksum is updated with the bytes written.
+ * Writes n bytes of data from {@code buf} starting at offset {@code off} to
+ * the underlying stream. The checksum is updated with the bytes written.
*
* @param buf
- * data to write out
+ * data written to the output stream.
* @param off
- * the start offset of the data
+ * the offset to start reading the data from {@code buf} written
+ * to the output stream.
* @param nbytes
- * number of bytes to write out
- *
+ * number of bytes to write to the output stream.
* @throws IOException
- * if an IO error has occured
+ * if an IO error has occurred.
*/
@Override
public void write(byte[] buf, int off, int nbytes) throws IOException {
Modified: harmony/enhanced/classlib/trunk/modules/archive/src/main/java/java/util/zip/Checksum.java
URL: http://svn.apache.org/viewvc/harmony/enhanced/classlib/trunk/modules/archive/src/main/java/java/util/zip/Checksum.java?rev=768128&r1=768127&r2=768128&view=diff
==============================================================================
--- harmony/enhanced/classlib/trunk/modules/archive/src/main/java/java/util/zip/Checksum.java (original)
+++ harmony/enhanced/classlib/trunk/modules/archive/src/main/java/java/util/zip/Checksum.java Fri Apr 24 02:23:48 2009
@@ -18,39 +18,41 @@
package java.util.zip;
/**
- * Interface to types that can compute a checksum value of given data.
+ * Holds information about a checksum which was computed with the methods
+ * implementing a checksum algorithm.
*/
public interface Checksum {
/**
- * Answers the computed checksum value so far.
+ * Returns the current calculated checksum value.
*
- * @return the checksum value
+ * @return the checksum.
*/
public long getValue();
/**
- * Reinitialize the checksum computation to its starting value.
+ * Resets the checksum value applied before beginning calculations on a new
+ * stream of data.
*/
public void reset();
/**
- * Update the checksum value based on the given byte array
- *
+ * Updates the checksum with the given bytes.
+ *
* @param buf
- * the data used to update the checksum
+ * the byte array from which to read the bytes.
* @param off
- * the starting point for data values
+ * the initial position in {@code buf} to read the bytes from.
* @param nbytes
- * the number of bytes to consider
+ * the number of bytes to read from {@code buf}.
*/
public void update(byte[] buf, int off, int nbytes);
/**
- * Update the checksum value based on the given data value.
+ * Updates the checksum value with the given byte.
*
* @param val
- * a single byte value
+ * the byte to update the checksum with.
*/
public void update(int val);
}
Modified: harmony/enhanced/classlib/trunk/modules/archive/src/main/java/java/util/zip/DataFormatException.java
URL: http://svn.apache.org/viewvc/harmony/enhanced/classlib/trunk/modules/archive/src/main/java/java/util/zip/DataFormatException.java?rev=768128&r1=768127&r2=768128&view=diff
==============================================================================
--- harmony/enhanced/classlib/trunk/modules/archive/src/main/java/java/util/zip/DataFormatException.java (original)
+++ harmony/enhanced/classlib/trunk/modules/archive/src/main/java/java/util/zip/DataFormatException.java Fri Apr 24 02:23:48 2009
@@ -18,27 +18,26 @@
package java.util.zip;
/**
- * DataFormatException is used to indicate an error in the format of a
- * particular data stream.
+ * {@code DataFormatException} is used to indicate an error in the format of a
+ * particular data stream which is to be uncompressed.
*/
public class DataFormatException extends Exception {
private static final long serialVersionUID = 2219632870893641452L;
/**
- * Constructs a new instance of this class with its walkback filled in.
- *
+ * Constructs a new {@code DataFormatException} instance.
*/
public DataFormatException() {
super();
}
/**
- * Constructs a new instance of this class with its walkback and message
- * filled in.
- *
+ * Constructs a new {@code DataFormatException} instance with the specified
+ * message.
+ *
* @param detailMessage
- * String The detail message for the exception.
+ * the detail message for the exception.
*/
public DataFormatException(String detailMessage) {
super(detailMessage);