You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@harmony.apache.org by qi...@apache.org on 2009/04/26 14:30:06 UTC
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...
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 "PrincipalName"}*
+ * </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 "PrincipalName"}*
+ * </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() {
}