harmony-commits mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From qi...@apache.org
Subject svn commit: r768698 [3/18] - in /harmony/enhanced/classlib/branches/java6: ./ modules/annotation/src/main/java/java/lang/annotation/ modules/archive/src/main/java/java/util/jar/ modules/archive/src/main/java/java/util/zip/ modules/auth/src/main/java/co...
Date Sun, 26 Apr 2009 12:30:06 GMT
Modified: harmony/enhanced/classlib/branches/java6/modules/archive/src/main/java/java/util/zip/ZipEntry.java
URL: http://svn.apache.org/viewvc/harmony/enhanced/classlib/branches/java6/modules/archive/src/main/java/java/util/zip/ZipEntry.java?rev=768698&r1=768697&r2=768698&view=diff
==============================================================================
--- harmony/enhanced/classlib/branches/java6/modules/archive/src/main/java/java/util/zip/ZipEntry.java (original)
+++ harmony/enhanced/classlib/branches/java6/modules/archive/src/main/java/java/util/zip/ZipEntry.java Sun Apr 26 12:30:01 2009
@@ -22,10 +22,15 @@
 import java.util.GregorianCalendar;
 
 /**
- * ZipEntry represents an entry in a zip file.
+ * An instance of {@code ZipEntry} represents an entry within a <i>ZIP-archive</i>.
+ * An entry has attributes such as name (= path) or the size of its data. While
+ * an entry identifies data stored in an archive, it does not hold the data
+ * itself. For example when reading a <i>ZIP-file</i> you will first retrieve
+ * all its entries in a collection and then read the data for a specific entry
+ * through an input stream.
  * 
  * @see ZipFile
- * @see ZipInputStream
+ * @see ZipOutputStream
  */
 public class ZipEntry implements ZipConstants, Cloneable {
     String name, comment;
@@ -37,20 +42,22 @@
     byte[] extra;
 
     /**
-     * Zip entry state: Deflated
+     * Zip entry state: Deflated.
      */
     public static final int DEFLATED = 8;
 
     /**
-     * Zip entry state: Stored
+     * Zip entry state: Stored.
      */
     public static final int STORED = 0;
 
     /**
-     * Constructs a new ZipEntry with the specified name.
+     * Constructs a new {@code ZipEntry} with the specified name.
      * 
      * @param name
-     *            the name of the zip entry
+     *            the name of the ZIP entry.
+     * @throws IllegalArgumentException
+     *             if the name length is outside the range (> 0xFFFF).
      */
     public ZipEntry(String name) {
         if (name == null) {
@@ -63,76 +70,79 @@
     }
 
     /**
-     * Gets the comment for this ZipEntry.
+     * Gets the comment for this {@code ZipEntry}.
      * 
-     * @return the comment for this ZipEntry, or null if there is no comment
+     * @return the comment for this {@code ZipEntry}, or {@code null} if there
+     *         is no comment. If we're reading an archive with
+     *         {@code ZipInputStream} the comment is not available.
      */
     public String getComment() {
         return comment;
     }
 
     /**
-     * Gets the compressed size of this ZipEntry.
+     * Gets the compressed size of this {@code ZipEntry}.
      * 
      * @return the compressed size, or -1 if the compressed size has not been
-     *         set
+     *         set.
      */
     public long getCompressedSize() {
         return compressedSize;
     }
 
     /**
-     * Gets the crc for this ZipEntry.
+     * Gets the checksum for this {@code ZipEntry}.
      * 
-     * @return the crc, or -1 if the crc has not been set
+     * @return the checksum, or -1 if the checksum has not been set.
      */
     public long getCrc() {
         return crc;
     }
 
     /**
-     * Gets the extra information for this ZipEntry.
+     * Gets the extra information for this {@code ZipEntry}.
      * 
-     * @return a byte array containing the extra information, or null if there
-     *         is none
+     * @return a byte array containing the extra information, or {@code null} if
+     *         there is none.
      */
     public byte[] getExtra() {
         return extra;
     }
 
     /**
-     * Gets the compression method for this ZipEntry.
+     * Gets the compression method for this {@code ZipEntry}.
      * 
-     * @return the compression method, either DEFLATED, STORED or -1 if the
-     *         compression method has not been set
+     * @return the compression method, either {@code DEFLATED}, {@code STORED}
+     *         or -1 if the compression method has not been set.
      */
     public int getMethod() {
         return compressionMethod;
     }
 
     /**
-     * Gets the name of this ZipEntry.
+     * Gets the name of this {@code ZipEntry}.
      * 
-     * @return the entry name
+     * @return the entry name.
      */
     public String getName() {
         return name;
     }
 
     /**
-     * Gets the uncompressed size of this ZipEntry.
+     * Gets the uncompressed size of this {@code ZipEntry}.
      * 
-     * @return the uncompressed size, or -1 if the size has not been set
+     * @return the uncompressed size, or {@code -1} if the size has not been
+     *         set.
      */
     public long getSize() {
         return size;
     }
 
     /**
-     * Gets the last modification time of this ZipEntry.
+     * Gets the last modification time of this {@code ZipEntry}.
      * 
      * @return the last modification time as the number of milliseconds since
-     *         Jan. 1, 1970
+     *         Jan. 1, 1970.
      */
     public long getTime() {
         if (time != -1) {
@@ -147,20 +157,20 @@
     }
 
     /**
-     * Answers if this ZipEntry is a directory.
+     * Determine whether or not this {@code ZipEntry} is a directory.
      * 
-     * @return <code>true</code> when this ZipEntry is a directory,
-     *         <code>false<code> otherwise
+     * @return {@code true} when this {@code ZipEntry} is a directory, {@code
+     *         false} otherwise.
      */
     public boolean isDirectory() {
         return name.charAt(name.length() - 1) == '/';
     }
 
     /**
-     * Sets the comment for this ZipEntry.
+     * Sets the comment for this {@code ZipEntry}.
      * 
      * @param string
-     *            the comment
+     *            the comment for this entry.
      */
     public void setComment(String string) {
         if (string == null || string.length() <= 0xFFFF) {
@@ -171,23 +181,22 @@
     }
 
     /**
-     * Sets the compressed size for this ZipEntry.
+     * Sets the compressed size for this {@code ZipEntry}.
      * 
      * @param value
-     *            the compressed size
+     *            the compressed size (in bytes).
      */
     public void setCompressedSize(long value) {
         compressedSize = value;
     }
 
     /**
-     * Sets the crc for this ZipEntry.
+     * Sets the checksum for this {@code ZipEntry}.
      * 
      * @param value
-     *            the crc
-     * 
+     *            the checksum for this entry.
      * @throws IllegalArgumentException
-     *             if value is < 0 or > 0xFFFFFFFFL
+     *             if {@code value} is < 0 or > 0xFFFFFFFFL.
      */
     public void setCrc(long value) {
         if (value >= 0 && value <= 0xFFFFFFFFL) {
@@ -198,13 +207,12 @@
     }
 
     /**
-     * Sets the extra information for this ZipEntry.
+     * Sets the extra information for this {@code ZipEntry}.
      * 
      * @param data
-     *            a byte array containing the extra information
-     * 
+     *            a byte array containing the extra information.
      * @throws IllegalArgumentException
-     *             when the length of data is > 0xFFFF bytes
+     *             when the length of data is greater than 0xFFFF bytes.
      */
     public void setExtra(byte[] data) {
         if (data == null || data.length <= 0xFFFF) {
@@ -215,13 +223,13 @@
     }
 
     /**
-     * Sets the compression method for this ZipEntry.
+     * Sets the compression method for this {@code ZipEntry}.
      * 
      * @param value
-     *            the compression method, either DEFLATED or STORED
-     * 
+     *            the compression method, either {@code DEFLATED} or {@code
+     *            STORED}.
      * @throws IllegalArgumentException
-     *             when value is not DEFLATED or STORED
+     *             when value is not {@code DEFLATED} or {@code STORED}.
      */
     public void setMethod(int value) {
         if (value != STORED && value != DEFLATED) {
@@ -231,13 +239,12 @@
     }
 
     /**
-     * Sets the uncompressed size of this ZipEntry.
+     * Sets the uncompressed size of this {@code ZipEntry}.
      * 
      * @param value
-     *            the uncompressed size
-     * 
+     *            the uncompressed size for this entry.
      * @throws IllegalArgumentException
-     *             if value is < 0 or > 0xFFFFFFFFL
+     *             if {@code value} < 0 or {@code value} > 0xFFFFFFFFL.
      */
     public void setSize(long value) {
         if (value >= 0 && value <= 0xFFFFFFFFL) {
@@ -248,11 +255,11 @@
     }
 
     /**
-     * Sets the last modification time of this ZipEntry.
+     * Sets the modification time of this {@code ZipEntry}.
      * 
      * @param value
-     *            the last modification time as the number of milliseconds since
-     *            Jan. 1, 1970
+     *            the modification time as the number of milliseconds since Jan.
+     *            1, 1970.
      */
     public void setTime(long value) {
         GregorianCalendar cal = new GregorianCalendar();
@@ -272,9 +279,9 @@
     }
 
     /**
-     * Answers the string representation of this ZipEntry.
+     * Returns the string representation of this {@code ZipEntry}.
      * 
-     * @return the string representation of this ZipEntry
+     * @return the string representation of this {@code ZipEntry}.
      */
     @Override
     public String toString() {
@@ -297,10 +304,11 @@
     }
 
     /**
-     * Constructs a new ZipEntry using the values obtained from ze.
+     * Constructs a new {@code ZipEntry} using the values obtained from {@code
+     * ze}.
      * 
      * @param ze
-     *            ZipEntry from which to obtain values.
+     *            the {@code ZipEntry} from which to obtain values.
      */
     public ZipEntry(ZipEntry ze) {
         name = ze.name;
@@ -316,9 +324,9 @@
     }
 
     /**
-     * Returns a shallow copy of this entry
+     * Returns a shallow copy of this entry.
      * 
-     * @return a copy of this entry
+     * @return a copy of this entry.
      */
     @Override
     public Object clone() {
@@ -326,9 +334,9 @@
     }
 
     /**
-     * Returns the hashCode for this ZipEntry.
+     * Returns the hash code for this {@code ZipEntry}.
      * 
-     * @return the hashCode of the entry
+     * @return the hash code of the entry.
      */
     @Override
     public int hashCode() {

Modified: harmony/enhanced/classlib/branches/java6/modules/archive/src/main/java/java/util/zip/ZipException.java
URL: http://svn.apache.org/viewvc/harmony/enhanced/classlib/branches/java6/modules/archive/src/main/java/java/util/zip/ZipException.java?rev=768698&r1=768697&r2=768698&view=diff
==============================================================================
--- harmony/enhanced/classlib/branches/java6/modules/archive/src/main/java/java/util/zip/ZipException.java (original)
+++ harmony/enhanced/classlib/branches/java6/modules/archive/src/main/java/java/util/zip/ZipException.java Sun Apr 26 12:30:01 2009
@@ -20,8 +20,8 @@
 import java.io.IOException;
 
 /**
- * This runtime exception is thrown by ZipFile and ZipInputStream when the file
- * or stream is not a valid zip file.
+ * This runtime exception is thrown by {@code ZipFile} and {@code
+ * ZipInputStream} when the file or stream is not a valid ZIP file.
  * 
  * @see ZipFile
  * @see ZipInputStream
@@ -31,18 +31,18 @@
     private static final long serialVersionUID = 8000196834066748623L;
 
     /**
-     * Constructs a new instance of this class with its walkback filled in.
+     * Constructs a new {@code ZipException} instance.
      */
     public ZipException() {
         super();
     }
 
     /**
-     * Constructs a new instance of this class with its walkback and message
-     * filled in.
-     * 
+     * Constructs a new {@code ZipException} instance with the specified
+     * message.
+     *
      * @param detailMessage
-     *            String The detail message for the exception.
+     *            the detail message for the exception.
      */
     public ZipException(String detailMessage) {
         super(detailMessage);

Modified: harmony/enhanced/classlib/branches/java6/modules/archive/src/main/java/java/util/zip/ZipFile.java
URL: http://svn.apache.org/viewvc/harmony/enhanced/classlib/branches/java6/modules/archive/src/main/java/java/util/zip/ZipFile.java?rev=768698&r1=768697&r2=768698&view=diff
==============================================================================
--- harmony/enhanced/classlib/branches/java6/modules/archive/src/main/java/java/util/zip/ZipFile.java (original)
+++ harmony/enhanced/classlib/branches/java6/modules/archive/src/main/java/java/util/zip/ZipFile.java Sun Apr 26 12:30:01 2009
@@ -30,10 +30,18 @@
 import org.apache.harmony.luni.util.Util;
 
 /**
- * ZipFile is used to read zip entries and their associated data from zip files.
+ * This class provides random read access to a <i>ZIP-archive</i> file.
+ * <p>
+ * While {@code ZipInputStream} provides stream based read access to a
+ * <i>ZIP-archive</i>, this class implements more efficient (file based) access
+ * and makes use of the <i>central directory</i> within a <i>ZIP-archive</i>.
+ * <p>
+ * Use {@code ZipOutputStream} if you want to create an archive.
+ * <p>
+ * A temporary ZIP file can be marked for automatic deletion upon closing it.
  * 
- * @see ZipInputStream
  * @see ZipEntry
+ * @see ZipOutputStream
  */
 public class ZipFile implements ZipConstants {
 
@@ -49,37 +57,41 @@
         ntvinit();
     }
 
-    /** Open ZIP file for read. */
+    /**
+     * Open zip file for read.
+     */
     public static final int OPEN_READ = 1;
 
-    /** Delete ZIP file when closed. */
+    /**
+     * Delete zip file when closed.
+     */
     public static final int OPEN_DELETE = 4;
 
     /**
-     * Constructs a new ZipFile opened on the specified File.
+     * Constructs a new {@code ZipFile} with the specified file.
      * 
      * @param file
-     *            the File
+     *            the file to read from.
      * @throws ZipException
-     *             if a ZIP format exception occurs reading the file
+     *             if a ZIP error occurs.
      * @throws IOException
-     *             if an IO exception occurs reading the file
+     *             if an {@code IOException} occurs.
      */
     public ZipFile(File file) throws ZipException, IOException {
         this(file.getPath());
     }
 
     /**
-     * Constructs a new ZipFile opened on the specified file using the specified
-     * mode.
+     * Opens a file as <i>ZIP-archive</i>. "mode" must be {@code OPEN_READ} or
+     * {@code OPEN_DELETE} . The latter sets the "delete on exit" flag through a
+     * file.
      * 
      * @param file
-     *            the file
+     *            the ZIP file to read.
      * @param mode
-     *            the mode to use, either <code>OPEN_READ</code> or
-     *            <code>OPEN_READ | OPEN_DELETE</code>
+     *            the mode of the file open operation.
      * @throws IOException
-     *             if an IO exception occurs reading the file
+     *             if an {@code IOException} occurs.
      */
     public ZipFile(File file, int mode) throws IOException {
         if (mode == OPEN_READ || mode == (OPEN_READ | OPEN_DELETE)) {
@@ -99,19 +111,19 @@
     }
 
     /**
-     * Constructs a new ZipFile opened on the specified file path name.
+     * Opens a ZIP archived file.
      * 
-     * @param filename
-     *            the file path name
+     * @param name
+     *            the name of the ZIP file.
      * @throws IOException
-     *             if an IO exception occured reading the file
+     *             if an IOException occurs.
      */
-    public ZipFile(String filename) throws IOException {
+    public ZipFile(String name) throws IOException {
         SecurityManager security = System.getSecurityManager();
         if (security != null) {
-            security.checkRead(filename);
+            security.checkRead(name);
         }
-        fileName = filename;
+        fileName = name;
         openZip();
     }
 
@@ -138,10 +150,10 @@
     }
 
     /**
-     * Closes this ZipFile.
+     * Closes this ZIP file.
      * 
      * @throws IOException
-     *             if an IO exception occured closing the file
+     *             if an IOException occurs.
      */
     public synchronized void close() throws IOException {
         if (descriptor != -1 && fileName != null) {
@@ -159,21 +171,22 @@
     }
 
     /**
-     * Answers all of the ZIP entries contained in this ZipFile.
+     * Returns an enumeration of the entries. The entries are listed in the
+     * order in which they appear in the ZIP archive.
      * 
-     * @return an Enumeration of the ZIP entries
+     * @return the enumeration of the entries.
      */
     public Enumeration<? extends ZipEntry> entries() {
         return new ZFEnum<ZipEntry>();
     }
 
     /**
-     * Gets the zip entry with the specified name from this ZipFile.
+     * Gets the ZIP entry with the specified name from this {@code ZipFile}.
      * 
      * @param entryName
-     *            the name of the entry in the zip file
-     * @return a ZipEntry or null if the entry name does not exist in the zip
-     *         file
+     *            the name of the entry in the ZIP file.
+     * @return a {@code ZipEntry} or {@code null} if the entry name does not
+     *         exist in the ZIP file.
      */
     public ZipEntry getEntry(String entryName) {
         if (entryName != null) {
@@ -184,13 +197,13 @@
     }
 
     /**
-     * Answers an input stream on the data of the specified ZipEntry.
+     * Returns an input stream on the data of the specified {@code ZipEntry}.
      * 
      * @param entry
-     *            the ZipEntry
-     * @return an input stream on the ZipEntry data
+     *            the ZipEntry.
+     * @return an input stream of the data contained in the {@code ZipEntry}.
      * @throws IOException
-     *             if an IO exception occurs reading the data
+     *             if an {@code IOException} occurs.
      */
     public InputStream getInputStream(ZipEntry entry) throws IOException {
         if (descriptor == -1) {
@@ -208,9 +221,9 @@
     }
 
     /**
-     * Gets the file name of this ZipFile.
+     * Gets the file name of this {@code ZipFile}.
      * 
-     * @return the file name of this ZipFile
+     * @return the file name of this {@code ZipFile}.
      */
     public String getName() {
         return fileName;
@@ -226,9 +239,9 @@
             throws ZipException;
 
     /**
-     * Returns the number of ZipEntries in this ZipFile.
+     * Returns the number of {@code ZipEntries} in this {@code ZipFile}.
      * 
-     * @return Number of entries in this file
+     * @return the number of entries in this file.
      */
     public int size() {
         if (size != -1) {

Modified: harmony/enhanced/classlib/branches/java6/modules/archive/src/main/java/java/util/zip/ZipInputStream.java
URL: http://svn.apache.org/viewvc/harmony/enhanced/classlib/branches/java6/modules/archive/src/main/java/java/util/zip/ZipInputStream.java?rev=768698&r1=768697&r2=768698&view=diff
==============================================================================
--- harmony/enhanced/classlib/branches/java6/modules/archive/src/main/java/java/util/zip/ZipInputStream.java (original)
+++ harmony/enhanced/classlib/branches/java6/modules/archive/src/main/java/java/util/zip/ZipInputStream.java Sun Apr 26 12:30:01 2009
@@ -28,8 +28,19 @@
 import org.apache.harmony.luni.util.Util;
 
 /**
- * ZipInputStream is an input stream for reading zip files.
- * 
+ * This class provides an implementation of {@code FilterInputStream} that
+ * uncompresses data from a <i>ZIP-archive</i> input stream.
+ * <p>
+ * A <i>ZIP-archive</i> is a collection of compressed (or uncompressed) files -
+ * the so called ZIP entries. Therefore when reading from a {@code
+ * ZipInputStream} first the entry's attributes will be retrieved with {@code
+ * getNextEntry} before its data is read.
+ * <p>
+ * While {@code InflaterInputStream} can read a compressed <i>ZIP-archive</i>
+ * entry, this extension can read uncompressed entries as well.
+ * <p>
+ * Use {@code ZipFile} if you can access the archive as a file directly.
+ *
  * @see ZipEntry
  * @see ZipFile
  */
@@ -63,10 +74,10 @@
     private char[] charBuf = new char[256];
 
     /**
-     * Constructs a new ZipInputStream on the specified input stream.
+     * Constructs a new {@code ZipInputStream} from the specified input stream.
      * 
      * @param stream
-     *            the input stream
+     *            the input stream to representing a ZIP archive.
      */
     public ZipInputStream(InputStream stream) {
         super(new PushbackInputStream(stream, BUF_SIZE), new Inflater(true));
@@ -76,7 +87,10 @@
     }
 
     /**
-     * Closes this ZipInputStream.
+     * Closes this {@code ZipInputStream}.
+     *
+     * @throws IOException
+     *             if an {@code IOException} occurs.
      */
     @Override
     public void close() throws IOException {
@@ -88,10 +102,10 @@
     }
 
     /**
-     * Closes the current zip entry and positions to read the next entry.
+     * Closes the current ZIP entry and positions to read the next entry.
      * 
      * @throws IOException
-     *             if an IO exception occurs closing the entry
+     *             if an {@code IOException} occurs.
      */
     public void closeEntry() throws IOException {
         if (zipClosed) {
@@ -145,11 +159,13 @@
     }
 
     /**
-     * Reads the next zip entry from this ZipInputStream.
+     * Reads the next entry from this {@code ZipInputStream}.
      * 
-     * @return the next entry
+     * @return the next {@code ZipEntry} contained in the input stream.
      * @throws IOException
-     *             if an IO exception occurs reading the next entry
+     *             if the stream is not positioned at the beginning of an entry
+     *             or if an other {@code IOException} occurs.
+     * @see ZipEntry
      */
     public ZipEntry getNextEntry() throws IOException {
         if (currentEntry != null) {
@@ -308,11 +324,13 @@
     }
 
     /**
-     * Skips up to the specified number of bytes in the current zip entry.
+     * Skips up to the specified number of bytes in the current ZIP entry.
      * 
      * @param value
-     *            the number of bytes to skip
-     * @return the number of bytes skipped
+     *            the number of bytes to skip.
+     * @return the number of bytes skipped.
+     * @throws IOException
+     *             if an {@code IOException} occurs.
      */
     @Override
     public long skip(long value) throws IOException {
@@ -333,9 +351,11 @@
     }
 
     /**
-     * Answers 1 if the EOF has been reached, otherwise returns 0.
+     * Returns 0 if the {@code EOF} has been reached, otherwise returns 1.
      * 
-     * @return 0 after EOF of current entry, 1 otherwise
+     * @return 0 after {@code EOF} of current entry, 1 otherwise.
+     * @throws IOException
+     *             if an IOException occurs.
      */
     @Override
     public int available() throws IOException {
@@ -357,6 +377,13 @@
         return 1;
     }
 
+    /**
+     * creates a {@link ZipEntry } with the given name.
+     *
+     * @param name
+     *            the name of the entry.
+     * @return the created {@code ZipEntry}.
+     */
     protected ZipEntry createZipEntry(String name) {
         return new ZipEntry(name);
     }

Modified: harmony/enhanced/classlib/branches/java6/modules/archive/src/main/java/java/util/zip/ZipOutputStream.java
URL: http://svn.apache.org/viewvc/harmony/enhanced/classlib/branches/java6/modules/archive/src/main/java/java/util/zip/ZipOutputStream.java?rev=768698&r1=768697&r2=768698&view=diff
==============================================================================
--- harmony/enhanced/classlib/branches/java6/modules/archive/src/main/java/java/util/zip/ZipOutputStream.java (original)
+++ harmony/enhanced/classlib/branches/java6/modules/archive/src/main/java/java/util/zip/ZipOutputStream.java Sun Apr 26 12:30:01 2009
@@ -25,19 +25,33 @@
 import org.apache.harmony.archive.internal.nls.Messages;
 
 /**
- * ZipOutputStream is used to write ZipEntries to the underlying stream. Output
- * from ZipOutputStream conforms to the ZipFile file format.
- * 
- * @see ZipInputStream
+ * This class provides an implementation of {@code FilterOutputStream} that
+ * compresses data entries into a <i>ZIP-archive</i> output stream.
+ * <p>
+ * {@code ZipOutputStream} is used to write {@code ZipEntries} to the underlying
+ * stream. Output from {@code ZipOutputStream} conforms to the {@code ZipFile}
+ * file format.
+ * <p>
+ * While {@code DeflaterOutputStream} can write a compressed <i>ZIP-archive</i>
+ * entry, this extension can write uncompressed entries as well. In this case
+ * special rules apply, for this purpose refer to the <a
+ * href="http://www.pkware.com/documents/casestudies/APPNOTE.TXT">file format
+ * specification</a>.
+ *
  * @see ZipEntry
+ * @see ZipFile
  */
 public class ZipOutputStream extends DeflaterOutputStream implements
         ZipConstants {
 
-    /** Method for compressed entries */
+    /**
+     * Indicates deflated entries.
+     */
     public static final int DEFLATED = 8;
 
-    /** Method for uncompressed entries */
+    /**
+     * Indicates uncompressed entries.
+     */
     public static final int STORED = 0;
 
     static final int ZIPDataDescriptorFlag = 8;
@@ -63,21 +77,22 @@
     private byte[] nameBytes;
 
     /**
-     * Constructs a new ZipOutputStream on p1
+     * Constructs a new {@code ZipOutputStream} with the specified output
+     * stream.
      * 
      * @param p1
-     *            OutputStream The InputStream to output to
+     *            the {@code OutputStream} to write the data to.
      */
     public ZipOutputStream(OutputStream p1) {
         super(p1, new Deflater(Deflater.DEFAULT_COMPRESSION, true));
     }
 
     /**
-     * Closes the current ZipEntry if any. Closes the underlying output stream.
-     * If the stream is already closed this method does nothing.
+     * Closes the current {@code ZipEntry}, if any, and the underlying output
+     * stream. If the stream is already closed this method does nothing.
      * 
-     * @exception IOException
-     *                If an error occurs closing the stream
+     * @throws IOException
+     *             If an error occurs closing the stream.
      */
     @Override
     public void close() throws IOException {
@@ -89,11 +104,11 @@
     }
 
     /**
-     * Closes the current ZipEntry. Any entry terminal data is written to the
-     * underlying stream.
+     * Closes the current {@code ZipEntry}. Any entry terminal data is written
+     * to the underlying stream.
      * 
-     * @exception IOException
-     *                If an error occurs closing the entry
+     * @throws IOException
+     *             If an error occurs closing the entry.
      */
     public void closeEntry() throws IOException {
         if (cDir == null) {
@@ -175,10 +190,10 @@
 
     /**
      * Indicates that all entries have been written to the stream. Any terminal
-     * ZipFile information is written to the underlying stream.
+     * information is written to the underlying stream.
      * 
-     * @exception IOException
-     *                If an error occurs while finishing
+     * @throws IOException
+     *             if an error occurs while terminating the stream.
      */
     @Override
     public void finish() throws IOException {
@@ -216,15 +231,15 @@
     }
 
     /**
-     * Writes entry information for ze to the underlying stream. Data associated
-     * with the entry can then be written using write(). After data is written
-     * closeEntry() must be called to complete the storing of ze on the
-     * underlying stream.
+     * Writes entry information to the underlying stream. Data associated with
+     * the entry can then be written using {@code write()}. After data is
+     * written {@code closeEntry()} must be called to complete the writing of
+     * the entry to the underlying stream.
      * 
      * @param ze
-     *            ZipEntry to store
-     * @exception IOException
-     *                If an error occurs storing the entry
+     *            the {@code ZipEntry} to store.
+     * @throws IOException
+     *             If an error occurs storing the entry.
      * @see #write
      */
     public void putNextEntry(ZipEntry ze) throws java.io.IOException {
@@ -307,10 +322,10 @@
     }
 
     /**
-     * Sets the ZipFile comment associated with the file being written.
+     * Sets the {@code ZipFile} comment associated with the file being written.
      * 
      * @param comment
-     *            the file comment
+     *            the comment associated with the file.
      */
     public void setComment(String comment) {
         if (comment.length() > 0xFFFF) {
@@ -321,10 +336,12 @@
 
     /**
      * Sets the compression level to be used for writing entry data. This level
-     * may be set on a per entry basis.
+     * may be set on a per entry basis. The level must have a value between -1
+     * and 8 according to the {@code Deflater} compression level bounds.
      * 
      * @param level
-     *            the compression level, must have a value between 0 and 10.
+     *            the compression level (ranging from -1 to 8).
+     * @see Deflater
      */
     public void setLevel(int level) {
         if (level < Deflater.DEFAULT_COMPRESSION
@@ -336,10 +353,11 @@
 
     /**
      * Sets the compression method to be used when compressing entry data.
-     * method must be one of STORED or DEFLATED.
+     * method must be one of {@code STORED} (for no compression) or {@code
+     * DEFLATED}.
      * 
      * @param method
-     *            Compression method to use
+     *            the compression method to use.
      */
     public void setMethod(int method) {
         if (method != STORED && method != DEFLATED) {

Modified: harmony/enhanced/classlib/branches/java6/modules/auth/src/main/java/common/javax/security/auth/AuthPermission.java
URL: http://svn.apache.org/viewvc/harmony/enhanced/classlib/branches/java6/modules/auth/src/main/java/common/javax/security/auth/AuthPermission.java?rev=768698&r1=768697&r2=768698&view=diff
==============================================================================
--- harmony/enhanced/classlib/branches/java6/modules/auth/src/main/java/common/javax/security/auth/AuthPermission.java (original)
+++ harmony/enhanced/classlib/branches/java6/modules/auth/src/main/java/common/javax/security/auth/AuthPermission.java Sun Apr 26 12:30:01 2009
@@ -21,6 +21,37 @@
 
 import org.apache.harmony.auth.internal.nls.Messages;
 
+/**
+ * Governs the use of methods in this package and also its subpackages. A
+ * <i>target name</i> of the permission specifies which methods are allowed
+ * without specifying the concrete action lists. Possible target names and
+ * associated authentication permissions are:
+ *
+ * <pre>
+ *    doAs                      invoke Subject.doAs methods.
+ *    doAsPrivileged            invoke the Subject.doAsPrivileged methods.
+ *    getSubject                invoke Subject.getSubject().
+ *    getSubjectFromDomainCombiner    invoke SubjectDomainCombiner.getSubject().
+ *    setReadOnly               invoke Subject.setReadonly().
+ *    modifyPrincipals          modify the set of principals
+ *                              associated with a Subject.
+ *    modifyPublicCredentials   modify the set of public credentials
+ *                              associated with a Subject.
+ *    modifyPrivateCredentials  modify the set of private credentials
+ *                              associated with a Subject.
+ *    refreshCredential         invoke the refresh method on a credential of a
+ *                              refreshable credential class.
+ *    destroyCredential         invoke the destroy method on a credential of a
+ *                              destroyable credential class.
+ *    createLoginContext.<i>name</i>   instantiate a LoginContext with the
+ *                              specified name. The wildcard name ('*')
+ *                              allows to a LoginContext of any name.
+ *    getLoginConfiguration     invoke the getConfiguration method of
+ *                              javax.security.auth.login.Configuration.
+ *    refreshLoginConfiguration Invoke the refresh method of
+ *                              javax.security.auth.login.Configuration.
+ * </pre>
+ */
 public final class AuthPermission extends BasicPermission {
 
     private static final long serialVersionUID = 5806031445061587174L;
@@ -42,10 +73,24 @@
         return name;
     }
 
+    /**
+     * Creates an authentication permission with the specified target name.
+     *
+     * @param name
+     *            the target name of this authentication permission.
+     */
     public AuthPermission(String name) {
         super(init(name));
     }
 
+    /**
+     * Creates an authentication permission with the specified target name.
+     *
+     * @param name
+     *            the target name of this authentication permission.
+     * @param actions
+     *            this parameter is ignored and should be {@code null}.
+     */
     public AuthPermission(String name, String actions) {
         super(init(name), actions);
     }

Modified: harmony/enhanced/classlib/branches/java6/modules/auth/src/main/java/common/javax/security/auth/DestroyFailedException.java
URL: http://svn.apache.org/viewvc/harmony/enhanced/classlib/branches/java6/modules/auth/src/main/java/common/javax/security/auth/DestroyFailedException.java?rev=768698&r1=768697&r2=768698&view=diff
==============================================================================
--- harmony/enhanced/classlib/branches/java6/modules/auth/src/main/java/common/javax/security/auth/DestroyFailedException.java (original)
+++ harmony/enhanced/classlib/branches/java6/modules/auth/src/main/java/common/javax/security/auth/DestroyFailedException.java Sun Apr 26 12:30:01 2009
@@ -17,14 +17,26 @@
 
 package javax.security.auth;
 
+/**
+ * Signals that the {@link Destroyable#destroy()} method failed.
+ */
 public class DestroyFailedException extends Exception {
 
     private static final long serialVersionUID = -7790152857282749162L;
 
+    /**
+     * Creates an exception of type {@code DestroyFailedException}.
+     */
     public DestroyFailedException() {
         super();
     }
 
+    /**
+     * Creates an exception of type {@code DestroyFailedException}.
+     *
+     * @param message
+     *            A detail message that describes the reason for this exception.
+     */
     public DestroyFailedException(String message) {
         super(message);
     }

Modified: harmony/enhanced/classlib/branches/java6/modules/auth/src/main/java/common/javax/security/auth/Destroyable.java
URL: http://svn.apache.org/viewvc/harmony/enhanced/classlib/branches/java6/modules/auth/src/main/java/common/javax/security/auth/Destroyable.java?rev=768698&r1=768697&r2=768698&view=diff
==============================================================================
--- harmony/enhanced/classlib/branches/java6/modules/auth/src/main/java/common/javax/security/auth/Destroyable.java (original)
+++ harmony/enhanced/classlib/branches/java6/modules/auth/src/main/java/common/javax/security/auth/Destroyable.java Sun Apr 26 12:30:01 2009
@@ -17,10 +17,27 @@
 
 package javax.security.auth;
 
+/**
+ * Allows for special treatment of sensitive information, when it comes to
+ * destroying or clearing of the data.
+ */
 public interface Destroyable {
 
+    /**
+     * Erases the sensitive information. Once an object is destroyed any calls
+     * to its methods will throw an {@code IllegalStateException}. If it does
+     * not succeed a DestroyFailedException is thrown.
+     *
+     * @throws DestroyFailedException
+     *             if the information cannot be erased.
+     */
     void destroy() throws DestroyFailedException;
 
+    /**
+     * Returns {@code true} once an object has been safely destroyed.
+     *
+     * @return whether the object has been safely destroyed.
+     */
     boolean isDestroyed();
 
 }

Modified: harmony/enhanced/classlib/branches/java6/modules/auth/src/main/java/common/javax/security/auth/PrivateCredentialPermission.java
URL: http://svn.apache.org/viewvc/harmony/enhanced/classlib/branches/java6/modules/auth/src/main/java/common/javax/security/auth/PrivateCredentialPermission.java?rev=768698&r1=768697&r2=768698&view=diff
==============================================================================
--- harmony/enhanced/classlib/branches/java6/modules/auth/src/main/java/common/javax/security/auth/PrivateCredentialPermission.java (original)
+++ harmony/enhanced/classlib/branches/java6/modules/auth/src/main/java/common/javax/security/auth/PrivateCredentialPermission.java Sun Apr 26 12:30:01 2009
@@ -27,6 +27,28 @@
 
 import org.apache.harmony.auth.internal.nls.Messages;
 
+/**
+ * Protects private credential objects belonging to a {@code Subject}. It has
+ * only one action which is "read". The target name of this permission has a
+ * special syntax:
+ *
+ * <pre>
+ * targetName = CredentialClass {PrincipalClass &quot;PrincipalName&quot;}*
+ * </pre>
+ *
+ * First it states a credential class and is followed then by a list of one or
+ * more principals identifying the subject.
+ * <p>
+ * The principals on their part are specified as the name of the {@code
+ * Principal} class followed by the principal name in quotes. For example, the
+ * following file may define permission to read the private credentials of a
+ * principal named "Bob": "com.sun.PrivateCredential com.sun.Principal \"Bob\""
+ * <p>
+ * The syntax also allows the use of the wildcard "*" in place of {@code
+ * CredentialClass} or {@code PrincipalClass} and/or {@code PrincipalName}.
+ *
+ * @see Principal
+ */
 public final class PrivateCredentialPermission extends Permission {
 
     private static final long serialVersionUID = 5284372143517237068L;
@@ -42,6 +64,16 @@
     // owners set
     private transient CredOwner[] set;
     
+    /**
+     * Creates a new permission for private credentials specified by the target
+     * name {@code name} and an {@code action}. The action is always
+     * {@code "read"}.
+     *
+     * @param name
+     *            the target name of the permission.
+     * @param action
+     *            the action {@code "read"}.
+     */
     public PrivateCredentialPermission(String name, String action) {
         super(name);
         if (READ.equalsIgnoreCase(action)) {
@@ -52,11 +84,13 @@
     }
 
     /**
-     * Creates a <code>PrivateCredentialPermission</code> from the Credential Class 
-     * and Set of Principals
+     * Creates a {@code PrivateCredentialPermission} from the {@code Credential}
+     * class and set of principals.
      * 
-     * @param credentialClass - credential class name
-     * @param principals - principal set
+     * @param credentialClass
+     *            the credential class name.
+     * @param principals
+     *            the set of principals.
      */
     PrivateCredentialPermission(String credentialClass, Set<Principal> principals) {
         super(credentialClass);
@@ -156,6 +190,22 @@
         initTargetName(getName());
     }
 
+    /**
+     * Returns the principal's classes and names associated with this {@code
+     * PrivateCredentialPermission} as a two dimensional array. The first
+     * dimension of the array corresponds to the number of principals. The
+     * second dimension defines either the name of the {@code PrincipalClass}
+     * [x][0] or the value of {@code PrincipalName} [x][1].
+     * <p>
+     * This corresponds to the the target name's syntax:
+     *
+     * <pre>
+     * targetName = CredentialClass {PrincipalClass &quot;PrincipalName&quot;}*
+     * </pre>
+     *
+     * @return the principal classes and names associated with this {@code
+     *         PrivateCredentialPermission}.
+     */
     public String[][] getPrincipals() {
 
         String[][] s = new String[offset][2];
@@ -172,6 +222,11 @@
         return READ;
     }
 
+    /**
+     * Returns the class name of the credential associated with this permission.
+     *
+     * @return the class name of the credential associated with this permission.
+     */
     public String getCredentialClass() {
         return credentialClass;
     }

Modified: harmony/enhanced/classlib/branches/java6/modules/auth/src/main/java/common/javax/security/auth/Subject.java
URL: http://svn.apache.org/viewvc/harmony/enhanced/classlib/branches/java6/modules/auth/src/main/java/common/javax/security/auth/Subject.java?rev=768698&r1=768697&r2=768698&view=diff
==============================================================================
--- harmony/enhanced/classlib/branches/java6/modules/auth/src/main/java/common/javax/security/auth/Subject.java (original)
+++ harmony/enhanced/classlib/branches/java6/modules/auth/src/main/java/common/javax/security/auth/Subject.java Sun Apr 26 12:30:01 2009
@@ -38,6 +38,20 @@
 
 import org.apache.harmony.auth.internal.nls.Messages;
 
+/**
+ * The central class of the {@code javax.security.auth} package representing an
+ * authenticated user or entity (both referred to as "subject"). IT defines also
+ * the static methods that allow code to be run, and do modifications according
+ * to the subject's permissions.
+ * <p>
+ * A subject has the following features:
+ * <ul>
+ * <li>A set of {@code Principal} objects specifying the identities bound to a
+ * {@code Subject} that distinguish it.</li>
+ * <li>Credentials (public and private) such as certificates, keys, or
+ * authentication proofs such as tickets</li>
+ * </ul>
+ */
 public final class Subject implements Serializable {
 
     private static final long serialVersionUID = -8308522755600156056L;
@@ -72,6 +86,10 @@
     // set of public credentials
     private transient SecureSet<Object> publicCredentials;
     
+    /**
+     * The default constructor initializing the sets of public and private
+     * credentials and principals with the empty set.
+     */
     public Subject() {
         super();
         principals = new SecureSet<Principal>(_PRINCIPALS);
@@ -81,6 +99,23 @@
         readOnly = false;
     }
 
+    /**
+     * The constructor for the subject, setting its public and private
+     * credentials and principals according to the arguments.
+     *
+     * @param readOnly
+     *            {@code true} if this {@code Subject} is read-only, thus
+     *            preventing any modifications to be done.
+     * @param subjPrincipals
+     *            the set of Principals that are attributed to this {@code
+     *            Subject}.
+     * @param pubCredentials
+     *            the set of public credentials that distinguish this {@code
+     *            Subject}.
+     * @param privCredentials
+     *            the set of private credentials that distinguish this {@code
+     *            Subject}.
+     */
     public Subject(boolean readOnly, Set<? extends Principal> subjPrincipals,
             Set<?> pubCredentials, Set<?> privCredentials) {
 
@@ -95,6 +130,16 @@
         this.readOnly = readOnly;
     }
 
+    /**
+     * Runs the code defined by {@code action} using the permissions granted to
+     * the {@code Subject} itself and to the code as well.
+     *
+     * @param subject
+     *            the distinguished {@code Subject}.
+     * @param action
+     *            the code to be run.
+     * @return the {@code Object} returned when running the {@code action}.
+     */
     @SuppressWarnings("unchecked")
     public static Object doAs(Subject subject, PrivilegedAction action) {
 
@@ -103,6 +148,21 @@
         return doAs_PrivilegedAction(subject, action, AccessController.getContext());
     }
 
+    /**
+     * Run the code defined by {@code action} using the permissions granted to
+     * the {@code Subject} and to the code itself, additionally providing a more
+     * specific context.
+     *
+     * @param subject
+     *            the distinguished {@code Subject}.
+     * @param action
+     *            the code to be run.
+     * @param context
+     *            the specific context in which the {@code action} is invoked.
+     *            if {@code null} a new {@link AccessControlContext} is
+     *            instantiated.
+     * @return the {@code Object} returned when running the {@code action}.
+     */
     @SuppressWarnings("unchecked")
     public static Object doAsPrivileged(Subject subject, PrivilegedAction action,
             AccessControlContext context) {
@@ -144,6 +204,18 @@
         return AccessController.doPrivileged(action, newContext);
     }
 
+    /**
+     * Runs the code defined by {@code action} using the permissions granted to
+     * the subject and to the code itself.
+     *
+     * @param subject
+     *            the distinguished {@code Subject}.
+     * @param action
+     *            the code to be run.
+     * @return the {@code Object} returned when running the {@code action}.
+     * @throws PrivilegedActionException
+     *             if running the {@code action} throws an exception.
+     */
     @SuppressWarnings("unchecked")
     public static Object doAs(Subject subject, PrivilegedExceptionAction action)
             throws PrivilegedActionException {
@@ -153,6 +225,23 @@
         return doAs_PrivilegedExceptionAction(subject, action, AccessController.getContext());
     }
 
+    /**
+     * Runs the code defined by {@code action} using the permissions granted to
+     * the subject and to the code itself, additionally providing a more
+     * specific context.
+     *
+     * @param subject
+     *            the distinguished {@code Subject}.
+     * @param action
+     *            the code to be run.
+     * @param context
+     *            the specific context in which the {@code action} is invoked.
+     *            if {@code null} a new {@link AccessControlContext} is
+     *            instantiated.
+     * @return the {@code Object} returned when running the {@code action}.
+     * @throws PrivilegedActionException
+     *             if running the {@code action} throws an exception.
+     */
     @SuppressWarnings("unchecked")
     public static Object doAsPrivileged(Subject subject,
             PrivilegedExceptionAction action, AccessControlContext context)
@@ -195,6 +284,17 @@
         return AccessController.doPrivileged(action, newContext);
     }
 
+    /**
+     * Checks two Subjects for equality. More specifically if the principals,
+     * public and private credentials are equal, equality for two {@code
+     * Subjects} is implied.
+     *
+     * @param obj
+     *            the {@code Object} checked for equality with this {@code
+     *            Subject}.
+     * @return {@code true} if the specified {@code Subject} is equal to this
+     *         one.
+     */
     @Override
     public boolean equals(Object obj) {
 
@@ -216,46 +316,117 @@
         return false;
     }
 
+    /**
+     * Returns this {@code Subject}'s {@link Principal}.
+     *
+     * @return this {@code Subject}'s {@link Principal}.
+     */
     public Set<Principal> getPrincipals() {
         return principals;
     }
 
+
+    /**
+     * Returns this {@code Subject}'s {@link Principal} which is a subclass of
+     * the {@code Class} provided.
+     *
+     * @param c
+     *            the {@code Class} as a criteria which the {@code Principal}
+     *            returned must satisfy.
+     * @return this {@code Subject}'s {@link Principal}. Modifications to the
+     *         returned set of {@code Principal}s do not affect this {@code
+     *         Subject}'s set.
+     */
     public <T extends Principal> Set<T> getPrincipals(Class<T> c) {
         return ((SecureSet<Principal>) principals).get(c);
     }
 
+    /**
+     * Returns the private credentials associated with this {@code Subject}.
+     *
+     * @return the private credentials associated with this {@code Subject}.
+     */
     public Set<Object> getPrivateCredentials() {
         return privateCredentials;
     }
 
+    /**
+     * Returns this {@code Subject}'s private credentials which are a subclass
+     * of the {@code Class} provided.
+     *
+     * @param c
+     *            the {@code Class} as a criteria which the private credentials
+     *            returned must satisfy.
+     * @return this {@code Subject}'s private credentials. Modifications to the
+     *         returned set of credentials do not affect this {@code Subject}'s
+     *         credentials.
+     */
     public <T> Set<T> getPrivateCredentials(Class<T> c) {
         return privateCredentials.get(c);
     }
 
+    /**
+     * Returns the public credentials associated with this {@code Subject}.
+     *
+     * @return the public credentials associated with this {@code Subject}.
+     */
     public Set<Object> getPublicCredentials() {
         return publicCredentials;
     }
 
+
+    /**
+     * Returns this {@code Subject}'s public credentials which are a subclass of
+     * the {@code Class} provided.
+     *
+     * @param c
+     *            the {@code Class} as a criteria which the public credentials
+     *            returned must satisfy.
+     * @return this {@code Subject}'s public credentials. Modifications to the
+     *         returned set of credentials do not affect this {@code Subject}'s
+     *         credentials.
+     */
     public <T> Set<T> getPublicCredentials(Class<T> c) {
         return publicCredentials.get(c);
     }
 
+    /**
+     * Returns a hash code of this {@code Subject}.
+     *
+     * @return a hash code of this {@code Subject}.
+     */
     @Override
     public int hashCode() {
         return principals.hashCode() + privateCredentials.hashCode()
                 + publicCredentials.hashCode();
     }
 
+    /**
+     * Prevents from modifications being done to the credentials and {@link
+     * Principal} sets. After setting it to read-only this {@code Subject} can
+     * not be made writable again. The destroy method on the credentials still
+     * works though.
+     */
     public void setReadOnly() {
         checkPermission(_READ_ONLY);
 
         readOnly = true;
     }
 
+    /**
+     * Returns whether this {@code Subject} is read-only or not.
+     *
+     * @return whether this {@code Subject} is read-only or not.
+     */
     public boolean isReadOnly() {
         return readOnly;
     }
 
+    /**
+     * Returns a {@code String} representation of this {@code Subject}.
+     *
+     * @return a {@code String} representation of this {@code Subject}.
+     */
     @Override
     public String toString() {
 
@@ -303,6 +474,16 @@
         out.defaultWriteObject();
     }
 
+    /**
+     * Returns the {@code Subject} that was last associated with the {@code
+     * context} provided as argument.
+     *
+     * @param context
+     *            the {@code context} that was associated with the
+     *            {@code Subject}.
+     * @return the {@code Subject} that was last associated with the {@code
+     *         context} provided as argument.
+     */
     public static Subject getSubject(final AccessControlContext context) {
         checkPermission(_SUBJECT);
         if (context == null) {

Modified: harmony/enhanced/classlib/branches/java6/modules/auth/src/main/java/common/javax/security/auth/SubjectDomainCombiner.java
URL: http://svn.apache.org/viewvc/harmony/enhanced/classlib/branches/java6/modules/auth/src/main/java/common/javax/security/auth/SubjectDomainCombiner.java?rev=768698&r1=768697&r2=768698&view=diff
==============================================================================
--- harmony/enhanced/classlib/branches/java6/modules/auth/src/main/java/common/javax/security/auth/SubjectDomainCombiner.java (original)
+++ harmony/enhanced/classlib/branches/java6/modules/auth/src/main/java/common/javax/security/auth/SubjectDomainCombiner.java Sun Apr 26 12:30:01 2009
@@ -22,6 +22,10 @@
 import java.security.ProtectionDomain;
 import java.util.Set;
 
+/**
+ * Merges permissions based on code source and code signers with permissions
+ * granted to the specified {@link Subject}.
+ */
 public class SubjectDomainCombiner implements DomainCombiner {
 
     // subject to be associated
@@ -31,6 +35,12 @@
     private static final AuthPermission _GET = new AuthPermission(
             "getSubjectFromDomainCombiner"); //$NON-NLS-1$
 
+    /**
+     * Creates a domain combiner for the entity provided in {@code subject}.
+     *
+     * @param subject
+     *            the entity to which this domain combiner is associated.
+     */
     public SubjectDomainCombiner(Subject subject) {
         super();
         if (subject == null) {
@@ -39,6 +49,11 @@
         this.subject = subject;
     }
 
+    /**
+     * Returns the entity to which this domain combiner is associated.
+     *
+     * @return the entity to which this domain combiner is associated.
+     */
     public Subject getSubject() {
         SecurityManager sm = System.getSecurityManager();
         if (sm != null) {
@@ -48,6 +63,22 @@
         return subject;
     }
 
+    /**
+     * Merges the {@code ProtectionDomain} with the {@code Principal}s
+     * associated with the subject of this {@code SubjectDomainCombiner}.
+     *
+     * @param currentDomains
+     *            the {@code ProtectionDomain}s associated with the context of
+     *            the current thread. The domains must be sorted according to
+     *            the execution order, the most recent residing at the
+     *            beginning.
+     * @param assignedDomains
+     *            the {@code ProtectionDomain}s from the parent thread based on
+     *            code source and signers.
+     * @return a single {@code ProtectionDomain} array computed from the two
+     *         provided arrays, or {@code null}.
+     * @see ProtectionDomain
+     */
     public ProtectionDomain[] combine(ProtectionDomain[] currentDomains,
             ProtectionDomain[] assignedDomains) {
         // get array length for combining protection domains

Modified: harmony/enhanced/classlib/branches/java6/modules/auth/src/main/java/common/javax/security/auth/callback/Callback.java
URL: http://svn.apache.org/viewvc/harmony/enhanced/classlib/branches/java6/modules/auth/src/main/java/common/javax/security/auth/callback/Callback.java?rev=768698&r1=768697&r2=768698&view=diff
==============================================================================
--- harmony/enhanced/classlib/branches/java6/modules/auth/src/main/java/common/javax/security/auth/callback/Callback.java (original)
+++ harmony/enhanced/classlib/branches/java6/modules/auth/src/main/java/common/javax/security/auth/callback/Callback.java Sun Apr 26 12:30:01 2009
@@ -17,5 +17,9 @@
 
 package javax.security.auth.callback;
 
+/**
+ * Defines an empty base interface for all {@code Callback}s used during
+ * authentication.
+ */
 public interface Callback {
 }
\ No newline at end of file

Modified: harmony/enhanced/classlib/branches/java6/modules/auth/src/main/java/common/javax/security/auth/callback/CallbackHandler.java
URL: http://svn.apache.org/viewvc/harmony/enhanced/classlib/branches/java6/modules/auth/src/main/java/common/javax/security/auth/callback/CallbackHandler.java?rev=768698&r1=768697&r2=768698&view=diff
==============================================================================
--- harmony/enhanced/classlib/branches/java6/modules/auth/src/main/java/common/javax/security/auth/callback/CallbackHandler.java (original)
+++ harmony/enhanced/classlib/branches/java6/modules/auth/src/main/java/common/javax/security/auth/callback/CallbackHandler.java Sun Apr 26 12:30:01 2009
@@ -17,8 +17,38 @@
 
 package javax.security.auth.callback;
 
+import java.io.IOException;
+
+/**
+ * Needs to be implemented by classes that want to handle authentication
+ * {@link Callback}s. A single method {@link #handle(Callback[])} must be
+ * provided that checks the type of the incoming {@code Callback}s and reacts
+ * accordingly. {@code CallbackHandler}s can be installed per application. It is
+ * also possible to configure a system-default {@code CallbackHandler} by
+ * setting the {@code auth.login.defaultCallbackHandler} property in the
+ * standard {@code security.properties} file.
+ */
 public interface CallbackHandler {
 
-    void handle(Callback[] callbacks) throws java.io.IOException, UnsupportedCallbackException;
+    /**
+     * Handles the actual {@link Callback}. A {@code CallbackHandler} needs to
+     * implement this method. In the method, it is free to select which {@code
+     * Callback}s it actually wants to handle and in which way. For example, a
+     * console-based {@code CallbackHandler} might choose to sequentially ask
+     * the user for login and password, if it implements these {@code Callback}
+     * s, whereas a GUI-based one might open a single dialog window for both
+     * values. If a {@code CallbackHandler} is not able to handle a specific
+     * {@code Callback}, it needs to throw an
+     * {@link UnsupportedCallbackException}.
+     *
+     * @param callbacks
+     *            the array of {@code Callback}s that need handling
+     * @throws IOException
+     *             if an I/O related error occurs
+     * @throws UnsupportedCallbackException
+     *             if the {@code CallbackHandler} is not able to handle a
+     *             specific {@code Callback}
+     */
+    void handle(Callback[] callbacks) throws IOException, UnsupportedCallbackException;
 
 }

Modified: harmony/enhanced/classlib/branches/java6/modules/auth/src/main/java/common/javax/security/auth/callback/PasswordCallback.java
URL: http://svn.apache.org/viewvc/harmony/enhanced/classlib/branches/java6/modules/auth/src/main/java/common/javax/security/auth/callback/PasswordCallback.java?rev=768698&r1=768697&r2=768698&view=diff
==============================================================================
--- harmony/enhanced/classlib/branches/java6/modules/auth/src/main/java/common/javax/security/auth/callback/PasswordCallback.java (original)
+++ harmony/enhanced/classlib/branches/java6/modules/auth/src/main/java/common/javax/security/auth/callback/PasswordCallback.java Sun Apr 26 12:30:01 2009
@@ -22,6 +22,10 @@
 
 import org.apache.harmony.auth.internal.nls.Messages;
 
+/**
+ * Is used in conjunction with a {@link CallbackHandler} to retrieve a password
+ * when needed.
+ */
 public class PasswordCallback implements Callback, Serializable {
 
     private static final long serialVersionUID = 2267422647454909926L;
@@ -39,20 +43,49 @@
         this.prompt = prompt;
     }
 
+    /**
+     * Creates a new {@code PasswordCallback} instance.
+     *
+     * @param prompt
+     *            the message that should be displayed to the user
+     * @param echoOn
+     *            determines whether the user input should be echoed
+     */
     public PasswordCallback(String prompt, boolean echoOn) {
         super();
         setPrompt(prompt);
         this.echoOn = echoOn;
     }
 
+    /**
+     * Returns the prompt that was specified when creating this {@code
+     * PasswordCallback}
+     *
+     * @return the prompt
+     */
     public String getPrompt() {
         return prompt;
     }
 
+    /**
+     * Queries whether this {@code PasswordCallback} expects user input to be
+     * echoed, which is specified during the creation of the object.
+     *
+     * @return {@code true} if (and only if) user input should be echoed
+     */
     public boolean isEchoOn() {
         return echoOn;
     }
 
+    /**
+     * Sets the password. The {@link CallbackHandler} that performs the actual
+     * provisioning or input of the password needs to call this method to hand
+     * back the password to the security service that requested it.
+     *
+     * @param password
+     *            the password. A copy of this is stored, so subsequent changes
+     *            to the input array do not affect the {@code PasswordCallback}.
+     */
     public void setPassword(char[] password) {
         if (password == null) {
             this.inputPassword = password;
@@ -62,6 +95,15 @@
         }
     }
 
+    /**
+     * Returns the password. The security service that needs the password
+     * usually calls this method once the {@link CallbackHandler} has finished
+     * its work.
+     *
+     * @return the password. A copy of the internal password is created and
+     *         returned, so subsequent changes to the internal password do not
+     *         affect the result.
+     */
     public char[] getPassword() {
         if (inputPassword != null) {
             char[] tmp = new char[inputPassword.length];
@@ -71,6 +113,9 @@
         return null;
     }
 
+    /**
+     * Clears the password stored in this {@code PasswordCallback}.
+     */
     public void clearPassword() {
         if (inputPassword != null) {
             Arrays.fill(inputPassword, '\u0000');

Modified: harmony/enhanced/classlib/branches/java6/modules/auth/src/main/java/common/javax/security/auth/callback/UnsupportedCallbackException.java
URL: http://svn.apache.org/viewvc/harmony/enhanced/classlib/branches/java6/modules/auth/src/main/java/common/javax/security/auth/callback/UnsupportedCallbackException.java?rev=768698&r1=768697&r2=768698&view=diff
==============================================================================
--- harmony/enhanced/classlib/branches/java6/modules/auth/src/main/java/common/javax/security/auth/callback/UnsupportedCallbackException.java (original)
+++ harmony/enhanced/classlib/branches/java6/modules/auth/src/main/java/common/javax/security/auth/callback/UnsupportedCallbackException.java Sun Apr 26 12:30:01 2009
@@ -17,22 +17,47 @@
 
 package javax.security.auth.callback;
 
+/**
+ * Thrown when a {@link CallbackHandler} does not support a particular {@link
+ * Callback}.
+ */
 public class UnsupportedCallbackException extends Exception {
 
     private static final long serialVersionUID = -6873556327655666839L;
 
     private Callback callback;
 
+    /**
+     * Creates a new exception instance and initializes it with just the
+     * unsupported {@code Callback}, but no error message.
+     *
+     * @param callback
+     *            the {@code Callback}
+     */
     public UnsupportedCallbackException(Callback callback) {
         super();
         this.callback = callback;
     }
 
+    /**
+     * Creates a new exception instance and initializes it with both the
+     * unsupported {@code Callback} and an error message.
+     *
+     * @param callback
+     *            the {@code Callback}
+     * @param message
+     *            the error message
+     */
     public UnsupportedCallbackException(Callback callback, String message) {
         super(message);
         this.callback = callback;
     }
 
+    /**
+     * Returns the unsupported {@code Callback} that triggered this exception.
+     *
+     * @return the {@code Callback}
+     */
     public Callback getCallback() {
         return callback;
     }

Modified: harmony/enhanced/classlib/branches/java6/modules/auth/src/main/java/common/javax/security/auth/login/LoginException.java
URL: http://svn.apache.org/viewvc/harmony/enhanced/classlib/branches/java6/modules/auth/src/main/java/common/javax/security/auth/login/LoginException.java?rev=768698&r1=768697&r2=768698&view=diff
==============================================================================
--- harmony/enhanced/classlib/branches/java6/modules/auth/src/main/java/common/javax/security/auth/login/LoginException.java (original)
+++ harmony/enhanced/classlib/branches/java6/modules/auth/src/main/java/common/javax/security/auth/login/LoginException.java Sun Apr 26 12:30:01 2009
@@ -19,14 +19,25 @@
 
 import java.security.GeneralSecurityException;
 
+/**
+ * Base class for exceptions that are thrown when a login error occurs.
+ */
 public class LoginException extends GeneralSecurityException {
 
     private static final long serialVersionUID = -4679091624035232488L;
 
+    /**
+     * Creates a new exception instance and initializes it with default values.
+     */
     public LoginException() {
         super();
     }
 
+    /**
+     * Creates a new exception instance and initializes it with a given message.
+     *
+     * @param message the error message
+     */
     public LoginException(String message) {
         super(message);
     }

Modified: harmony/enhanced/classlib/branches/java6/modules/auth/src/main/java/common/javax/security/auth/x500/X500Principal.java
URL: http://svn.apache.org/viewvc/harmony/enhanced/classlib/branches/java6/modules/auth/src/main/java/common/javax/security/auth/x500/X500Principal.java?rev=768698&r1=768697&r2=768698&view=diff
==============================================================================
--- harmony/enhanced/classlib/branches/java6/modules/auth/src/main/java/common/javax/security/auth/x500/X500Principal.java (original)
+++ harmony/enhanced/classlib/branches/java6/modules/auth/src/main/java/common/javax/security/auth/x500/X500Principal.java Sun Apr 26 12:30:01 2009
@@ -28,19 +28,49 @@
 import org.apache.harmony.auth.internal.nls.Messages;
 import org.apache.harmony.security.x501.Name;
 
+/**
+ * Represents an X.500 principal, which holds the distinguished name of some
+ * network entity. An example of a distinguished name is {@code "O=SomeOrg,
+ * OU=SomeOrgUnit, C=US"}. The class can be instantiated from a byte representation
+ * of an object identifier (OID), an ASN.1 DER-encoded version, or a simple
+ * string holding the distinguished name. The representations must follow either
+ * RFC 2253, RFC 1779, or RFC2459.
+ */
 public final class X500Principal implements Serializable, Principal {
 
     private static final long serialVersionUID = -500463348111345721L;
 
+    /**
+     * Defines a constant for the canonical string format of distinguished
+     * names.
+     */
     public static final String CANONICAL = "CANONICAL"; //$NON-NLS-1$
 
+    /**
+     * Defines a constant for the RFC 1779 string format of distinguished
+     * names.
+     */
     public static final String RFC1779 = "RFC1779"; //$NON-NLS-1$
 
+    /**
+     * Defines a constant for the RFC 2253 string format of distinguished
+     * names.
+     */
     public static final String RFC2253 = "RFC2253"; //$NON-NLS-1$
 
     //Distinguished Name
     private transient Name dn;
 
+    /**
+     * Creates a new X500Principal from a given ASN.1 DER encoding of a
+     * distinguished name.
+     *
+     * @param name
+     *            the ASN.1 DER-encoded distinguished name
+     *
+     * @throws IllegalArgumentException
+     *             if the ASN.1 DER-encoded distinguished name is incorrect
+     */
     public X500Principal(byte[] name) {
         super();
         if (name == null) {
@@ -57,6 +87,17 @@
         }
     }
 
+    /**
+     * Creates a new X500Principal from a given ASN.1 DER encoding of a
+     * distinguished name.
+     *
+     * @param in
+     *            an {@code InputStream} holding the ASN.1 DER-encoded
+     *            distinguished name
+     *
+     * @throws IllegalArgumentException
+     *             if the ASN.1 DER-encoded distinguished name is incorrect
+     */
     public X500Principal(InputStream in) {
         super();
         if (in == null) {
@@ -73,6 +114,17 @@
         }
     }
 
+    /**
+     * Creates a new X500Principal from a string representation of a
+     * distinguished name.
+     *
+     * @param name
+     *            the string representation of the distinguished name
+     *
+     * @throws IllegalArgumentException
+     *             if the string representation of the distinguished name is
+     *             incorrect
+     */
     public X500Principal(String name) {
         super();
         if (name == null) {
@@ -116,6 +168,12 @@
         return dn.getName(CANONICAL).equals(principal.dn.getName(CANONICAL));
     }
 
+    /**
+     * Returns an ASN.1 DER-encoded representation of the distinguished name
+     * contained in this X.500 principal.
+     *
+     * @return the ASN.1 DER-encoded representation
+     */
     public byte[] getEncoded() {
         byte[] src = dn.getEncoded();
         byte[] dst = new byte[src.length];
@@ -123,10 +181,35 @@
         return dst;
     }
 
+    /**
+     * Returns a human-readable string representation of the distinguished name
+     * contained in this X.500 principal.
+     *
+     * @return the string representation
+     */
     public String getName() {
         return dn.getName(RFC2253);
     }
 
+    /**
+     * Returns a string representation of the distinguished name contained in
+     * this X.500 principal. The format of the representation can be chosen.
+     * Valid arguments are {@link #RFC1779}, {@link #RFC2253}, and
+     * {@link #CANONICAL}. The representations are specified in RFC 1779 and RFC
+     * 2253, respectively. The canonical form is based on RFC 2253, but adds
+     * some canonicalizing operations like removing leading and trailing
+     * whitespace, lower-casing the whole name, and bringing it into a
+     * normalized Unicode representation.
+     *
+     * @param format
+     *            the name of the format to use for the representation
+     *
+     * @return the string representation
+     *
+     * @throws IllegalArgumentException
+     *             if the {@code format} argument is not one of the three
+     *             mentioned above
+     */
     public String getName(String format) {
         return dn.getName(format);
     }

Modified: harmony/enhanced/classlib/branches/java6/modules/beans/src/main/java/java/beans/Statement.java
URL: http://svn.apache.org/viewvc/harmony/enhanced/classlib/branches/java6/modules/beans/src/main/java/java/beans/Statement.java?rev=768698&r1=768697&r2=768698&view=diff
==============================================================================
--- harmony/enhanced/classlib/branches/java6/modules/beans/src/main/java/java/beans/Statement.java (original)
+++ harmony/enhanced/classlib/branches/java6/modules/beans/src/main/java/java/beans/Statement.java Sun Apr 26 12:30:01 2009
@@ -215,7 +215,9 @@
 					result = action.run();
 				}
             } else {
-                Method method = findMethod(theTarget.getClass(), theMethodName, theArguments, false);
+                Method method = findMethod(theTarget.getClass(), theMethodName,
+                        theArguments, false);
+                method.setAccessible(true);
                 result = method.invoke(theTarget, theArguments);
             }
         } catch (InvocationTargetException ite) {

Modified: harmony/enhanced/classlib/branches/java6/modules/beans/src/main/java/java/beans/XMLEncoder.java
URL: http://svn.apache.org/viewvc/harmony/enhanced/classlib/branches/java6/modules/beans/src/main/java/java/beans/XMLEncoder.java?rev=768698&r1=768697&r2=768698&view=diff
==============================================================================
--- harmony/enhanced/classlib/branches/java6/modules/beans/src/main/java/java/beans/XMLEncoder.java (original)
+++ harmony/enhanced/classlib/branches/java6/modules/beans/src/main/java/java/beans/XMLEncoder.java Sun Apr 26 12:30:01 2009
@@ -838,7 +838,7 @@
                 break;
             }
             
-            if (obj != null && value.equals(obj)) {
+            if (obj != null && obj.equals(value)) {
                 n++;
 
                 if (n >= DEADLOCK_THRESHOLD) {

Modified: harmony/enhanced/classlib/branches/java6/modules/beans/src/test/java/org/apache/harmony/beans/tests/java/beans/StatementTest.java
URL: http://svn.apache.org/viewvc/harmony/enhanced/classlib/branches/java6/modules/beans/src/test/java/org/apache/harmony/beans/tests/java/beans/StatementTest.java?rev=768698&r1=768697&r2=768698&view=diff
==============================================================================
--- harmony/enhanced/classlib/branches/java6/modules/beans/src/test/java/org/apache/harmony/beans/tests/java/beans/StatementTest.java (original)
+++ harmony/enhanced/classlib/branches/java6/modules/beans/src/test/java/org/apache/harmony/beans/tests/java/beans/StatementTest.java Sun Apr 26 12:30:01 2009
@@ -20,6 +20,7 @@
 import java.beans.DefaultPersistenceDelegate;
 import java.beans.Statement;
 import java.util.Arrays;
+import java.util.TreeMap;
 import java.util.Vector;
 
 import junit.framework.Test;
@@ -1018,6 +1019,33 @@
                 TInspectorCluster.OFFSPRING_OBJECT_LIST);
     }
 
+    public void test_Statement_Execute() throws Exception {
+        MockTreeMapInnerClass innerTreeMap = new MockTreeMapInnerClass();
+        Statement statement = new Statement(innerTreeMap, "get",
+                new Object[] { "key" });
+        statement.execute();
+        assertEquals("value", innerTreeMap.getReturnValue());
+        innerTreeMap.reset();
+    }
+
+    class MockTreeMapInnerClass extends TreeMap {
+
+        private Object returnValue = null;
+
+        public Object getReturnValue() {
+            return returnValue;
+        }
+
+        public void reset() {
+            returnValue = null;
+        }
+
+        @Override
+        public Object get(Object key) {
+            return returnValue = "value";
+        }
+    }
+
     /*
      * Super class of MockObject.
      */

Modified: harmony/enhanced/classlib/branches/java6/modules/beans/src/test/java/org/apache/harmony/beans/tests/java/beans/XMLEncoderTest.java
URL: http://svn.apache.org/viewvc/harmony/enhanced/classlib/branches/java6/modules/beans/src/test/java/org/apache/harmony/beans/tests/java/beans/XMLEncoderTest.java?rev=768698&r1=768697&r2=768698&view=diff
==============================================================================
--- harmony/enhanced/classlib/branches/java6/modules/beans/src/test/java/org/apache/harmony/beans/tests/java/beans/XMLEncoderTest.java (original)
+++ harmony/enhanced/classlib/branches/java6/modules/beans/src/test/java/org/apache/harmony/beans/tests/java/beans/XMLEncoderTest.java Sun Apr 26 12:30:01 2009
@@ -32,6 +32,8 @@
 import java.io.InputStreamReader;
 import java.io.PrintWriter;
 import java.io.StringReader;
+import java.util.Map;
+import java.util.TreeMap;
 
 import junit.framework.TestCase;
 
@@ -44,6 +46,7 @@
 import org.apache.harmony.beans.tests.support.mock.MockBean4Owner_Target;
 import org.apache.harmony.beans.tests.support.mock.MockBean4StaticField;
 import org.apache.harmony.beans.tests.support.mock.MockBean4StaticField_PD;
+import org.apache.harmony.beans.tests.support.mock.MockTreeMapClass;
 import org.xml.sax.InputSource;
 import org.xml.sax.XMLReader;
 import org.xml.sax.helpers.XMLReaderFactory;
@@ -300,6 +303,18 @@
 
     }
 
+    public void testWriteObject_MockTreeMap() throws Exception {
+        Map<String, TreeMap<String, String>> innerTreeMap = new MockTreeMapClass();
+        TreeMap resultTreeMap = innerTreeMap.get("outKey");
+        resultTreeMap.put("innerKey", "innerValue");
+
+        ByteArrayOutputStream baos = new ByteArrayOutputStream();
+        XMLEncoder xmlEncoder = new XMLEncoder(baos);
+
+        assertCodedXML(innerTreeMap, "/xml/MockTreeMap.xml", baos, xmlEncoder);
+        assertEquals(1, innerTreeMap.size());
+    }
+
     public void testClose() {
         ByteArrayOutputStream out = new ByteArrayOutputStream() {
             boolean closeCalled = false;

Propchange: harmony/enhanced/classlib/branches/java6/modules/concurrent/src/main/java/java/util/concurrent/atomic/
------------------------------------------------------------------------------
--- svn:mergeinfo (original)
+++ svn:mergeinfo Sun Apr 26 12:30:01 2009
@@ -0,0 +1 @@
+/harmony/enhanced/classlib/trunk/modules/concurrent/src/main/java/java/util/concurrent/atomic:765923-768151

Propchange: harmony/enhanced/classlib/branches/java6/modules/concurrent/src/main/java/java/util/concurrent/locks/
------------------------------------------------------------------------------
--- svn:mergeinfo (original)
+++ svn:mergeinfo Sun Apr 26 12:30:01 2009
@@ -0,0 +1 @@
+/harmony/enhanced/classlib/trunk/modules/concurrent/src/main/java/java/util/concurrent/locks:765923-768151

Modified: harmony/enhanced/classlib/branches/java6/modules/crypto/src/main/java/javax/crypto/BadPaddingException.java
URL: http://svn.apache.org/viewvc/harmony/enhanced/classlib/branches/java6/modules/crypto/src/main/java/javax/crypto/BadPaddingException.java?rev=768698&r1=768697&r2=768698&view=diff
==============================================================================
--- harmony/enhanced/classlib/branches/java6/modules/crypto/src/main/java/javax/crypto/BadPaddingException.java (original)
+++ harmony/enhanced/classlib/branches/java6/modules/crypto/src/main/java/javax/crypto/BadPaddingException.java Sun Apr 26 12:30:01 2009
@@ -25,8 +25,8 @@
 import java.security.GeneralSecurityException;
 
 /**
- * @com.intel.drl.spec_ref
- * 
+ * The exception that is thrown when a padding mechanism is expected for the
+ * input data, but the input data does not have the proper padding bytes.
  */
 public class BadPaddingException extends GeneralSecurityException {
 
@@ -36,16 +36,17 @@
     private static final long serialVersionUID = -5315033893984728443L;
 
     /**
-     * @com.intel.drl.spec_ref
+     * Creates a new instance of {@code BadPaddingException} with a message.
      * 
+     * @param msg
+     *            the message
      */
     public BadPaddingException(String msg) {
         super(msg);
     }
 
     /**
-     * @com.intel.drl.spec_ref
-     * 
+     * Creates a new instance of {@code BadPaddingException} with no message.
      */
     public BadPaddingException() {
     }



Mime
View raw message