--- a/jdk/src/share/classes/java/io/ByteArrayInputStream.java Tue Oct 22 19:37:11 2013 -0400
+++ b/jdk/src/share/classes/java/io/ByteArrayInputStream.java Tue Oct 22 19:43:42 2013 -0400
@@ -275,7 +275,6 @@
* Closing a <tt>ByteArrayInputStream</tt> has no effect. The methods in
* this class can be called after the stream has been closed without
* generating an <tt>IOException</tt>.
- * <p>
*/
public void close() throws IOException {
}
--- a/jdk/src/share/classes/java/io/ByteArrayOutputStream.java Tue Oct 22 19:37:11 2013 -0400
+++ b/jdk/src/share/classes/java/io/ByteArrayOutputStream.java Tue Oct 22 19:43:42 2013 -0400
@@ -263,8 +263,6 @@
* Closing a <tt>ByteArrayOutputStream</tt> has no effect. The methods in
* this class can be called after the stream has been closed without
* generating an <tt>IOException</tt>.
- * <p>
- *
*/
public void close() throws IOException {
}
--- a/jdk/src/share/classes/java/io/DataInput.java Tue Oct 22 19:37:11 2013 -0400
+++ b/jdk/src/share/classes/java/io/DataInput.java Tue Oct 22 19:43:42 2013 -0400
@@ -155,7 +155,7 @@
* to the length of {@code b}.
* <p>
* This method blocks until one of the
- * following conditions occurs:<p>
+ * following conditions occurs:
* <ul>
* <li>{@code b.length}
* bytes of input data are available, in which
@@ -197,7 +197,7 @@
* <p>
* This method
* blocks until one of the following conditions
- * occurs:<p>
+ * occurs:
* <ul>
* <li>{@code len} bytes
* of input data are available, in which case
@@ -316,8 +316,8 @@
* be the second byte. The value
* returned
* is:
- * <p><pre><code>(short)((a << 8) | (b & 0xff))
- * </code></pre>
+ * <pre>{@code (short)((a << 8) | (b & 0xff))
+ * }</pre>
* This method
* is suitable for reading the bytes written
* by the {@code writeShort} method of
@@ -337,8 +337,8 @@
* be the first byte read and
* {@code b}
* be the second byte. The value returned is:
- * <p><pre><code>(((a & 0xff) << 8) | (b & 0xff))
- * </code></pre>
+ * <pre>{@code (((a & 0xff) << 8) | (b & 0xff))
+ * }</pre>
* This method is suitable for reading the bytes
* written by the {@code writeShort} method
* of interface {@code DataOutput} if
@@ -359,8 +359,8 @@
* be the first byte read and {@code b}
* be the second byte. The value
* returned is:
- * <p><pre><code>(char)((a << 8) | (b & 0xff))
- * </code></pre>
+ * <pre>{@code (char)((a << 8) | (b & 0xff))
+ * }</pre>
* This method
* is suitable for reading bytes written by
* the {@code writeChar} method of interface
@@ -377,10 +377,10 @@
* Reads four input bytes and returns an
* {@code int} value. Let {@code a-d}
* be the first through fourth bytes read. The value returned is:
- * <p><pre><code>
- * (((a & 0xff) << 24) | ((b & 0xff) << 16) |
- *  ((c & 0xff) << 8) | (d & 0xff))
- * </code></pre>
+ * <pre>{@code
+ * (((a & 0xff) << 24) | ((b & 0xff) << 16) |
+ * ((c & 0xff) << 8) | (d & 0xff))
+ * }</pre>
* This method is suitable
* for reading bytes written by the {@code writeInt}
* method of interface {@code DataOutput}.
@@ -397,16 +397,16 @@
* a {@code long} value. Let {@code a-h}
* be the first through eighth bytes read.
* The value returned is:
- * <p><pre><code>
- * (((long)(a & 0xff) << 56) |
- * ((long)(b & 0xff) << 48) |
- * ((long)(c & 0xff) << 40) |
- * ((long)(d & 0xff) << 32) |
- * ((long)(e & 0xff) << 24) |
- * ((long)(f & 0xff) << 16) |
- * ((long)(g & 0xff) << 8) |
- * ((long)(h & 0xff)))
- * </code></pre>
+ * <pre>{@code
+ * (((long)(a & 0xff) << 56) |
+ * ((long)(b & 0xff) << 48) |
+ * ((long)(c & 0xff) << 40) |
+ * ((long)(d & 0xff) << 32) |
+ * ((long)(e & 0xff) << 24) |
+ * ((long)(f & 0xff) << 16) |
+ * ((long)(g & 0xff) << 8) |
+ * ((long)(h & 0xff)))
+ * }</pre>
* <p>
* This method is suitable
* for reading bytes written by the {@code writeLong}
@@ -540,9 +540,9 @@
* not match the bit pattern {@code 10xxxxxx},
* then a {@code UTFDataFormatException}
* is thrown. Otherwise, the group is converted
- * to the character:<p>
- * <pre><code>(char)(((a& 0x1F) << 6) | (b & 0x3F))
- * </code></pre>
+ * to the character:
+ * <pre>{@code (char)(((a & 0x1F) << 6) | (b & 0x3F))
+ * }</pre>
* If the first byte of a group
* matches the bit pattern {@code 1110xxxx},
* then the group consists of that byte {@code a}
@@ -554,10 +554,10 @@
* does not match the bit pattern {@code 10xxxxxx},
* then a {@code UTFDataFormatException}
* is thrown. Otherwise, the group is converted
- * to the character:<p>
- * <pre><code>
- * (char)(((a & 0x0F) << 12) | ((b & 0x3F) << 6) | (c & 0x3F))
- * </code></pre>
+ * to the character:
+ * <pre>{@code
+ * (char)(((a & 0x0F) << 12) | ((b & 0x3F) << 6) | (c & 0x3F))
+ * }</pre>
* If the first byte of a group matches the
* pattern {@code 1111xxxx} or the pattern
* {@code 10xxxxxx}, then a {@code UTFDataFormatException}
--- a/jdk/src/share/classes/java/io/DataOutput.java Tue Oct 22 19:37:11 2013 -0400
+++ b/jdk/src/share/classes/java/io/DataOutput.java Tue Oct 22 19:43:42 2013 -0400
@@ -134,11 +134,11 @@
* Writes two bytes to the output
* stream to represent the value of the argument.
* The byte values to be written, in the order
- * shown, are: <p>
- * <pre><code>
- * (byte)(0xff & (v >> 8))
- * (byte)(0xff & v)
- * </code> </pre> <p>
+ * shown, are:
+ * <pre>{@code
+ * (byte)(0xff & (v >> 8))
+ * (byte)(0xff & v)
+ * }</pre> <p>
* The bytes written by this method may be
* read by the <code>readShort</code> method
* of interface <code>DataInput</code> , which
@@ -156,10 +156,10 @@
* output stream.
* The byte values to be written, in the order
* shown, are:
- * <p><pre><code>
- * (byte)(0xff & (v >> 8))
- * (byte)(0xff & v)
- * </code></pre><p>
+ * <pre>{@code
+ * (byte)(0xff & (v >> 8))
+ * (byte)(0xff & v)
+ * }</pre><p>
* The bytes written by this method may be
* read by the <code>readChar</code> method
* of interface <code>DataInput</code> , which
@@ -176,12 +176,12 @@
* comprised of four bytes, to the output stream.
* The byte values to be written, in the order
* shown, are:
- * <p><pre><code>
- * (byte)(0xff & (v >> 24))
- * (byte)(0xff & (v >> 16))
- * (byte)(0xff & (v >>    8))
- * (byte)(0xff & v)
- * </code></pre><p>
+ * <pre>{@code
+ * (byte)(0xff & (v >> 24))
+ * (byte)(0xff & (v >> 16))
+ * (byte)(0xff & (v >> 8))
+ * (byte)(0xff & v)
+ * }</pre><p>
* The bytes written by this method may be read
* by the <code>readInt</code> method of interface
* <code>DataInput</code> , which will then
@@ -197,16 +197,16 @@
* comprised of eight bytes, to the output stream.
* The byte values to be written, in the order
* shown, are:
- * <p><pre><code>
- * (byte)(0xff & (v >> 56))
- * (byte)(0xff & (v >> 48))
- * (byte)(0xff & (v >> 40))
- * (byte)(0xff & (v >> 32))
- * (byte)(0xff & (v >> 24))
- * (byte)(0xff & (v >> 16))
- * (byte)(0xff & (v >> 8))
- * (byte)(0xff & v)
- * </code></pre><p>
+ * <pre>{@code
+ * (byte)(0xff & (v >> 56))
+ * (byte)(0xff & (v >> 48))
+ * (byte)(0xff & (v >> 40))
+ * (byte)(0xff & (v >> 32))
+ * (byte)(0xff & (v >> 24))
+ * (byte)(0xff & (v >> 16))
+ * (byte)(0xff & (v >> 8))
+ * (byte)(0xff & v)
+ * }</pre><p>
* The bytes written by this method may be
* read by the <code>readLong</code> method
* of interface <code>DataInput</code> , which
@@ -314,24 +314,24 @@
* If a character <code>c</code>
* is in the range <code>\u0001</code> through
* <code>\u007f</code>, it is represented
- * by one byte:<p>
+ * by one byte:
* <pre>(byte)c </pre> <p>
* If a character <code>c</code> is <code>\u0000</code>
* or is in the range <code>\u0080</code>
* through <code>\u07ff</code>, then it is
* represented by two bytes, to be written
- * in the order shown:<p> <pre><code>
- * (byte)(0xc0 | (0x1f & (c >> 6)))
- * (byte)(0x80 | (0x3f & c))
- * </code></pre> <p> If a character
+ * in the order shown: <pre>{@code
+ * (byte)(0xc0 | (0x1f & (c >> 6)))
+ * (byte)(0x80 | (0x3f & c))
+ * }</pre> <p> If a character
* <code>c</code> is in the range <code>\u0800</code>
* through <code>uffff</code>, then it is
* represented by three bytes, to be written
- * in the order shown:<p> <pre><code>
- * (byte)(0xe0 | (0x0f & (c >> 12)))
- * (byte)(0x80 | (0x3f & (c >> 6)))
- * (byte)(0x80 | (0x3f & c))
- * </code></pre> <p> First,
+ * in the order shown: <pre>{@code
+ * (byte)(0xe0 | (0x0f & (c >> 12)))
+ * (byte)(0x80 | (0x3f & (c >> 6)))
+ * (byte)(0x80 | (0x3f & c))
+ * }</pre> <p> First,
* the total number of bytes needed to represent
* all the characters of <code>s</code> is
* calculated. If this number is larger than
--- a/jdk/src/share/classes/java/io/FilePermission.java Tue Oct 22 19:37:11 2013 -0400
+++ b/jdk/src/share/classes/java/io/FilePermission.java Tue Oct 22 19:43:42 2013 -0400
@@ -55,7 +55,7 @@
* a list of one or more comma-separated keywords. The possible keywords are
* "read", "write", "execute", "delete", and "readlink". Their meaning is
* defined as follows:
- * <P>
+ *
* <DL>
* <DT> read <DD> read permission
* <DT> write <DD> write permission
@@ -297,11 +297,11 @@
/**
* Checks if this FilePermission object "implies" the specified permission.
* <P>
- * More specifically, this method returns true if:<p>
+ * More specifically, this method returns true if:
* <ul>
- * <li> <i>p</i> is an instanceof FilePermission,<p>
+ * <li> <i>p</i> is an instanceof FilePermission,
* <li> <i>p</i>'s actions are a proper subset of this
- * object's actions, and <p>
+ * object's actions, and
* <li> <i>p</i>'s pathname is implied by this object's
* pathname. For example, "/tmp/*" implies "/tmp/foo", since
* "/tmp/*" encompasses all files in the "/tmp" directory,
--- a/jdk/src/share/classes/java/io/InputStream.java Tue Oct 22 19:37:11 2013 -0400
+++ b/jdk/src/share/classes/java/io/InputStream.java Tue Oct 22 19:43:42 2013 -0400
@@ -306,8 +306,7 @@
*
* <p> The general contract of <code>reset</code> is:
*
- * <p><ul>
- *
+ * <ul>
* <li> If the method <code>markSupported</code> returns
* <code>true</code>, then:
*
--- a/jdk/src/share/classes/java/io/ObjectInputStream.java Tue Oct 22 19:37:11 2013 -0400
+++ b/jdk/src/share/classes/java/io/ObjectInputStream.java Tue Oct 22 19:43:42 2013 -0400
@@ -109,7 +109,7 @@
*
* <p>Serializable classes that require special handling during the
* serialization and deserialization process should implement the following
- * methods:<p>
+ * methods:
*
* <pre>
* private void writeObject(java.io.ObjectOutputStream stream)
--- a/jdk/src/share/classes/java/io/PipedInputStream.java Tue Oct 22 19:37:11 2013 -0400
+++ b/jdk/src/share/classes/java/io/PipedInputStream.java Tue Oct 22 19:43:42 2013 -0400
@@ -172,15 +172,14 @@
* unconnected piped output stream and <code>snk</code>
* is an unconnected piped input stream, they
* may be connected by either the call:
- * <p>
+ *
* <pre><code>snk.connect(src)</code> </pre>
* <p>
* or the call:
- * <p>
+ *
* <pre><code>src.connect(snk)</code> </pre>
* <p>
- * The two
- * calls have the same effect.
+ * The two calls have the same effect.
*
* @param src The piped output stream to connect to.
* @exception IOException if an I/O error occurs.
--- a/jdk/src/share/classes/java/io/PipedReader.java Tue Oct 22 19:37:11 2013 -0400
+++ b/jdk/src/share/classes/java/io/PipedReader.java Tue Oct 22 19:43:42 2013 -0400
@@ -145,15 +145,14 @@
* unconnected piped writer and <code>snk</code>
* is an unconnected piped reader, they
* may be connected by either the call:
- * <p>
+ *
* <pre><code>snk.connect(src)</code> </pre>
* <p>
* or the call:
- * <p>
+ *
* <pre><code>src.connect(snk)</code> </pre>
* <p>
- * The two
- * calls have the same effect.
+ * The two calls have the same effect.
*
* @param src The piped writer to connect to.
* @exception IOException if an I/O error occurs.
--- a/jdk/src/share/classes/java/io/RandomAccessFile.java Tue Oct 22 19:37:11 2013 -0400
+++ b/jdk/src/share/classes/java/io/RandomAccessFile.java Tue Oct 22 19:43:42 2013 -0400
@@ -784,7 +784,7 @@
* </pre></blockquote>
* <p>
* then the result is equal to:
- * <p><blockquote><pre>
+ * <blockquote><pre>
* ((long)b1 << 56) + ((long)b2 << 48)
* + ((long)b3 << 40) + ((long)b4 << 32)
* + ((long)b5 << 24) + ((long)b6 << 16)
--- a/jdk/src/share/classes/java/io/Serializable.java Tue Oct 22 19:37:11 2013 -0400
+++ b/jdk/src/share/classes/java/io/Serializable.java Tue Oct 22 19:43:42 2013 -0400
@@ -55,7 +55,7 @@
*
* Classes that require special handling during the serialization and
* deserialization process must implement special methods with these exact
- * signatures: <p>
+ * signatures:
*
* <PRE>
* private void writeObject(java.io.ObjectOutputStream out)
@@ -101,7 +101,7 @@
*
* <p>Serializable classes that need to designate an alternative object to be
* used when writing an object to the stream should implement this
- * special method with the exact signature: <p>
+ * special method with the exact signature:
*
* <PRE>
* ANY-ACCESS-MODIFIER Object writeReplace() throws ObjectStreamException;
@@ -115,7 +115,7 @@
*
* Classes that need to designate a replacement when an instance of it
* is read from the stream should implement this special method with the
- * exact signature.<p>
+ * exact signature.
*
* <PRE>
* ANY-ACCESS-MODIFIER Object readResolve() throws ObjectStreamException;
@@ -133,7 +133,7 @@
* deserialization will result in an {@link InvalidClassException}. A
* serializable class can declare its own serialVersionUID explicitly by
* declaring a field named <code>"serialVersionUID"</code> that must be static,
- * final, and of type <code>long</code>:<p>
+ * final, and of type <code>long</code>:
*
* <PRE>
* ANY-ACCESS-MODIFIER static final long serialVersionUID = 42L;
--- a/jdk/src/share/classes/java/io/SerializablePermission.java Tue Oct 22 19:37:11 2013 -0400
+++ b/jdk/src/share/classes/java/io/SerializablePermission.java Tue Oct 22 19:43:42 2013 -0400
@@ -43,7 +43,6 @@
* The following table lists all the possible SerializablePermission target names,
* and for each provides a description of what the permission allows
* and a discussion of the risks of granting code the permission.
- * <P>
*
* <table border=1 cellpadding=5 summary="Permission target name, what the permission allows, and associated risks">
* <tr>
--- a/jdk/src/share/classes/java/lang/AbstractStringBuilder.java Tue Oct 22 19:37:11 2013 -0400
+++ b/jdk/src/share/classes/java/lang/AbstractStringBuilder.java Tue Oct 22 19:43:42 2013 -0400
@@ -330,9 +330,9 @@
* characters to be copied is {@code srcEnd-srcBegin}. The
* characters are copied into the subarray of {@code dst} starting
* at index {@code dstBegin} and ending at index:
- * <p><blockquote><pre>
+ * <pre>{@code
* dstbegin + (srcEnd-srcBegin) - 1
- * </pre></blockquote>
+ * }</pre>
*
* @param srcBegin start copying at this offset.
* @param srcEnd stop copying at this offset.
@@ -859,16 +859,16 @@
*
* <p> An invocation of this method of the form
*
- * <blockquote><pre>
- * sb.subSequence(begin, end)</pre></blockquote>
+ * <pre>{@code
+ * sb.subSequence(begin, end)}</pre>
*
* behaves in exactly the same way as the invocation
*
- * <blockquote><pre>
- * sb.substring(begin, end)</pre></blockquote>
+ * <pre>{@code
+ * sb.substring(begin, end)}</pre>
*
* This method is provided so that this class can
- * implement the {@link CharSequence} interface. </p>
+ * implement the {@link CharSequence} interface.
*
* @param start the start index, inclusive.
* @param end the end index, exclusive.
@@ -1287,9 +1287,9 @@
* Returns the index within this string of the first occurrence of the
* specified substring. The integer returned is the smallest value
* <i>k</i> such that:
- * <blockquote><pre>
+ * <pre>{@code
* this.toString().startsWith(str, <i>k</i>)
- * </pre></blockquote>
+ * }</pre>
* is {@code true}.
*
* @param str any string.
@@ -1306,10 +1306,10 @@
* Returns the index within this string of the first occurrence of the
* specified substring, starting at the specified index. The integer
* returned is the smallest value {@code k} for which:
- * <blockquote><pre>
+ * <pre>{@code
* k >= Math.min(fromIndex, this.length()) &&
* this.toString().startsWith(str, k)
- * </pre></blockquote>
+ * }</pre>
* If no such value of <i>k</i> exists, then -1 is returned.
*
* @param str the substring for which to search.
@@ -1326,9 +1326,9 @@
* of the specified substring. The rightmost empty string "" is
* considered to occur at the index value {@code this.length()}.
* The returned index is the largest value <i>k</i> such that
- * <blockquote><pre>
+ * <pre>{@code
* this.toString().startsWith(str, k)
- * </pre></blockquote>
+ * }</pre>
* is true.
*
* @param str the substring to search for.
@@ -1345,10 +1345,10 @@
* Returns the index within this string of the last occurrence of the
* specified substring. The integer returned is the largest value <i>k</i>
* such that:
- * <blockquote><pre>
+ * <pre>{@code
* k <= Math.min(fromIndex, this.length()) &&
* this.toString().startsWith(str, k)
- * </pre></blockquote>
+ * }</pre>
* If no such value of <i>k</i> exists, then -1 is returned.
*
* @param str the substring to search for.
--- a/jdk/src/share/classes/java/lang/ArrayStoreException.java Tue Oct 22 19:37:11 2013 -0400
+++ b/jdk/src/share/classes/java/lang/ArrayStoreException.java Tue Oct 22 19:43:42 2013 -0400
@@ -29,7 +29,7 @@
* Thrown to indicate that an attempt has been made to store the
* wrong type of object into an array of objects. For example, the
* following code generates an <code>ArrayStoreException</code>:
- * <p><blockquote><pre>
+ * <blockquote><pre>
* Object x[] = new String[3];
* x[0] = new Integer(0);
* </pre></blockquote>
--- a/jdk/src/share/classes/java/lang/Byte.java Tue Oct 22 19:37:11 2013 -0400
+++ b/jdk/src/share/classes/java/lang/Byte.java Tue Oct 22 19:43:42 2013 -0400
@@ -244,7 +244,7 @@
* <dd><i>Sign<sub>opt</sub></i> {@code 0X} <i>HexDigits</i>
* <dd><i>Sign<sub>opt</sub></i> {@code #} <i>HexDigits</i>
* <dd><i>Sign<sub>opt</sub></i> {@code 0} <i>OctalDigits</i>
- * <p>
+ *
* <dt><i>Sign:</i>
* <dd>{@code -}
* <dd>{@code +}
--- a/jdk/src/share/classes/java/lang/Character.java Tue Oct 22 19:37:11 2013 -0400
+++ b/jdk/src/share/classes/java/lang/Character.java Tue Oct 22 19:43:42 2013 -0400
@@ -5394,7 +5394,7 @@
* Other_Lowercase as defined by the Unicode Standard.
* <p>
* The following are examples of lowercase characters:
- * <p><blockquote><pre>
+ * <blockquote><pre>
* a b c d e f g h i j k l m n o p q r s t u v w x y z
* '\u00DF' '\u00E0' '\u00E1' '\u00E2' '\u00E3' '\u00E4' '\u00E5' '\u00E6'
* '\u00E7' '\u00E8' '\u00E9' '\u00EA' '\u00EB' '\u00EC' '\u00ED' '\u00EE'
@@ -5430,7 +5430,7 @@
* Other_Lowercase as defined by the Unicode Standard.
* <p>
* The following are examples of lowercase characters:
- * <p><blockquote><pre>
+ * <blockquote><pre>
* a b c d e f g h i j k l m n o p q r s t u v w x y z
* '\u00DF' '\u00E0' '\u00E1' '\u00E2' '\u00E3' '\u00E4' '\u00E5' '\u00E6'
* '\u00E7' '\u00E8' '\u00E9' '\u00EA' '\u00EB' '\u00EC' '\u00ED' '\u00EE'
@@ -5461,14 +5461,14 @@
* or it has contributory property Other_Uppercase as defined by the Unicode Standard.
* <p>
* The following are examples of uppercase characters:
- * <p><blockquote><pre>
+ * <blockquote><pre>
* A B C D E F G H I J K L M N O P Q R S T U V W X Y Z
* '\u00C0' '\u00C1' '\u00C2' '\u00C3' '\u00C4' '\u00C5' '\u00C6' '\u00C7'
* '\u00C8' '\u00C9' '\u00CA' '\u00CB' '\u00CC' '\u00CD' '\u00CE' '\u00CF'
* '\u00D0' '\u00D1' '\u00D2' '\u00D3' '\u00D4' '\u00D5' '\u00D6' '\u00D8'
* '\u00D9' '\u00DA' '\u00DB' '\u00DC' '\u00DD' '\u00DE'
* </pre></blockquote>
- * <p> Many other Unicode characters are uppercase too.<p>
+ * <p> Many other Unicode characters are uppercase too.
*
* <p><b>Note:</b> This method cannot handle <a
* href="#supplementary"> supplementary characters</a>. To support
@@ -5496,7 +5496,7 @@
* or it has contributory property Other_Uppercase as defined by the Unicode Standard.
* <p>
* The following are examples of uppercase characters:
- * <p><blockquote><pre>
+ * <blockquote><pre>
* A B C D E F G H I J K L M N O P Q R S T U V W X Y Z
* '\u00C0' '\u00C1' '\u00C2' '\u00C3' '\u00C4' '\u00C5' '\u00C6' '\u00C7'
* '\u00C8' '\u00C9' '\u00CA' '\u00CB' '\u00CC' '\u00CD' '\u00CE' '\u00CF'
@@ -5540,7 +5540,7 @@
* <li>{@code LATIN CAPITAL LETTER N WITH SMALL LETTER J}
* <li>{@code LATIN CAPITAL LETTER D WITH SMALL LETTER Z}
* </ul>
- * <p> Many other Unicode characters are titlecase too.<p>
+ * <p> Many other Unicode characters are titlecase too.
*
* <p><b>Note:</b> This method cannot handle <a
* href="#supplementary"> supplementary characters</a>. To support
--- a/jdk/src/share/classes/java/lang/Class.java Tue Oct 22 19:37:11 2013 -0400
+++ b/jdk/src/share/classes/java/lang/Class.java Tue Oct 22 19:43:42 2013 -0400
@@ -91,7 +91,7 @@
* <p> The following example uses a {@code Class} object to print the
* class name of an object:
*
- * <p> <blockquote><pre>
+ * <blockquote><pre>
* void printClassName(Object obj) {
* System.out.println("The class of " + obj +
* " is " + obj.getClass().getName());
@@ -103,7 +103,7 @@
* <cite>The Java™ Language Specification</cite>.
* For example:
*
- * <p> <blockquote>
+ * <blockquote>
* {@code System.out.println("The name of class Foo is: "+Foo.class.getName());}
* </blockquote>
*
--- a/jdk/src/share/classes/java/lang/ClassCastException.java Tue Oct 22 19:37:11 2013 -0400
+++ b/jdk/src/share/classes/java/lang/ClassCastException.java Tue Oct 22 19:43:42 2013 -0400
@@ -29,7 +29,7 @@
* Thrown to indicate that the code has attempted to cast an object
* to a subclass of which it is not an instance. For example, the
* following code generates a <code>ClassCastException</code>:
- * <p><blockquote><pre>
+ * <blockquote><pre>
* Object x = new Integer(0);
* System.out.println((String)x);
* </pre></blockquote>
--- a/jdk/src/share/classes/java/lang/Double.java Tue Oct 22 19:37:11 2013 -0400
+++ b/jdk/src/share/classes/java/lang/Double.java Tue Oct 22 19:43:42 2013 -0400
@@ -361,15 +361,11 @@
* <dd><i>SignedInteger</i>
* </dl>
*
- * <p>
- *
* <dl>
* <dt><i>HexFloatingPointLiteral</i>:
* <dd> <i>HexSignificand BinaryExponent FloatTypeSuffix<sub>opt</sub></i>
* </dl>
*
- * <p>
- *
* <dl>
* <dt><i>HexSignificand:</i>
* <dd><i>HexNumeral</i>
@@ -380,15 +376,11 @@
* </i>{@code .} <i>HexDigits</i>
* </dl>
*
- * <p>
- *
* <dl>
* <dt><i>BinaryExponent:</i>
* <dd><i>BinaryExponentIndicator SignedInteger</i>
* </dl>
*
- * <p>
- *
* <dl>
* <dt><i>BinaryExponentIndicator:</i>
* <dd>{@code p}
--- a/jdk/src/share/classes/java/lang/Float.java Tue Oct 22 19:37:11 2013 -0400
+++ b/jdk/src/share/classes/java/lang/Float.java Tue Oct 22 19:43:42 2013 -0400
@@ -321,15 +321,11 @@
* <dd><i>SignedInteger</i>
* </dl>
*
- * <p>
- *
* <dl>
* <dt><i>HexFloatingPointLiteral</i>:
* <dd> <i>HexSignificand BinaryExponent FloatTypeSuffix<sub>opt</sub></i>
* </dl>
*
- * <p>
- *
* <dl>
* <dt><i>HexSignificand:</i>
* <dd><i>HexNumeral</i>
@@ -340,15 +336,11 @@
* </i>{@code .} <i>HexDigits</i>
* </dl>
*
- * <p>
- *
* <dl>
* <dt><i>BinaryExponent:</i>
* <dd><i>BinaryExponentIndicator SignedInteger</i>
* </dl>
*
- * <p>
- *
* <dl>
* <dt><i>BinaryExponentIndicator:</i>
* <dd>{@code p}
--- a/jdk/src/share/classes/java/lang/Integer.java Tue Oct 22 19:37:11 2013 -0400
+++ b/jdk/src/share/classes/java/lang/Integer.java Tue Oct 22 19:43:42 2013 -0400
@@ -1123,7 +1123,7 @@
* <dd><i>Sign<sub>opt</sub></i> {@code 0X} <i>HexDigits</i>
* <dd><i>Sign<sub>opt</sub></i> {@code #} <i>HexDigits</i>
* <dd><i>Sign<sub>opt</sub></i> {@code 0} <i>OctalDigits</i>
- * <p>
+ *
* <dt><i>Sign:</i>
* <dd>{@code -}
* <dd>{@code +}
--- a/jdk/src/share/classes/java/lang/Iterable.java Tue Oct 22 19:37:11 2013 -0400
+++ b/jdk/src/share/classes/java/lang/Iterable.java Tue Oct 22 19:43:42 2013 -0400
@@ -51,10 +51,12 @@
Iterator<T> iterator();
/**
- * Performs the given action on the contents of the {@code Iterable}, in the
- * order elements occur when iterating, until all elements have been
- * processed or the action throws an exception. Errors or runtime
- * exceptions thrown by the action are relayed to the caller.
+ * Performs the given action for each element of the {@code Iterable}
+ * until all elements have been processed or the action throws an
+ * exception. Unless otherwise specified by the implementing class,
+ * actions are performed in the order of iteration (if an iteration order
+ * is specified). Exceptions thrown by the action are relayed to the
+ * caller.
*
* @implSpec
* <p>The default implementation behaves as if:
@@ -99,4 +101,3 @@
return Spliterators.spliteratorUnknownSize(iterator(), 0);
}
}
-
--- a/jdk/src/share/classes/java/lang/Long.java Tue Oct 22 19:37:11 2013 -0400
+++ b/jdk/src/share/classes/java/lang/Long.java Tue Oct 22 19:43:42 2013 -0400
@@ -853,7 +853,7 @@
* <dd><i>Sign<sub>opt</sub></i> {@code 0X} <i>HexDigits</i>
* <dd><i>Sign<sub>opt</sub></i> {@code #} <i>HexDigits</i>
* <dd><i>Sign<sub>opt</sub></i> {@code 0} <i>OctalDigits</i>
- * <p>
+ *
* <dt><i>Sign:</i>
* <dd>{@code -}
* <dd>{@code +}
--- a/jdk/src/share/classes/java/lang/RuntimePermission.java Tue Oct 22 19:37:11 2013 -0400
+++ b/jdk/src/share/classes/java/lang/RuntimePermission.java Tue Oct 22 19:43:42 2013 -0400
@@ -47,7 +47,6 @@
* The following table lists all the possible RuntimePermission target names,
* and for each provides a description of what the permission allows
* and a discussion of the risks of granting code the permission.
- * <P>
*
* <table border=1 cellpadding=5 summary="permission target name,
* what the target allows,and associated risks">
--- a/jdk/src/share/classes/java/lang/Short.java Tue Oct 22 19:37:11 2013 -0400
+++ b/jdk/src/share/classes/java/lang/Short.java Tue Oct 22 19:43:42 2013 -0400
@@ -249,7 +249,7 @@
* <dd><i>Sign<sub>opt</sub></i> {@code 0X} <i>HexDigits</i>
* <dd><i>Sign<sub>opt</sub></i> {@code #} <i>HexDigits</i>
* <dd><i>Sign<sub>opt</sub></i> {@code 0} <i>OctalDigits</i>
- * <p>
+ *
* <dt><i>Sign:</i>
* <dd>{@code -}
* <dd>{@code +}
--- a/jdk/src/share/classes/java/lang/String.java Tue Oct 22 19:37:11 2013 -0400
+++ b/jdk/src/share/classes/java/lang/String.java Tue Oct 22 19:43:42 2013 -0400
@@ -47,16 +47,16 @@
* Strings are constant; their values cannot be changed after they
* are created. String buffers support mutable strings.
* Because String objects are immutable they can be shared. For example:
- * <p><blockquote><pre>
+ * <blockquote><pre>
* String str = "abc";
* </pre></blockquote><p>
* is equivalent to:
- * <p><blockquote><pre>
+ * <blockquote><pre>
* char data[] = {'a', 'b', 'c'};
* String str = new String(data);
* </pre></blockquote><p>
* Here are some more examples of how strings can be used:
- * <p><blockquote><pre>
+ * <blockquote><pre>
* System.out.println("abc");
* String cde = "cde";
* System.out.println("abc" + cde);
@@ -786,7 +786,7 @@
* {@code srcEnd-srcBegin}). The characters are copied into the
* subarray of {@code dst} starting at index {@code dstBegin}
* and ending at index:
- * <p><blockquote><pre>
+ * <blockquote><pre>
* dstbegin + (srcEnd-srcBegin) - 1
* </pre></blockquote>
*
@@ -2662,7 +2662,7 @@
* {@code String} may be a different length than the original {@code String}.
* <p>
* Examples of locale-sensitive and 1:M case mappings are in the following table.
- * <p>
+ *
* <table border="1" summary="Examples of locale-sensitive and 1:M case mappings. Shows Language code of locale, lower case, upper case, and description.">
* <tr>
* <th>Language Code of Locale</th>
--- a/jdk/src/share/classes/java/lang/Thread.java Tue Oct 22 19:37:11 2013 -0400
+++ b/jdk/src/share/classes/java/lang/Thread.java Tue Oct 22 19:43:42 2013 -0400
@@ -76,7 +76,7 @@
* <code>Thread</code>. An instance of the subclass can then be
* allocated and started. For example, a thread that computes primes
* larger than a stated value could be written as follows:
- * <p><hr><blockquote><pre>
+ * <hr><blockquote><pre>
* class PrimeThread extends Thread {
* long minPrime;
* PrimeThread(long minPrime) {
@@ -91,7 +91,7 @@
* </pre></blockquote><hr>
* <p>
* The following code would then create a thread and start it running:
- * <p><blockquote><pre>
+ * <blockquote><pre>
* PrimeThread p = new PrimeThread(143);
* p.start();
* </pre></blockquote>
@@ -102,7 +102,7 @@
* then be allocated, passed as an argument when creating
* <code>Thread</code>, and started. The same example in this other
* style looks like the following:
- * <p><hr><blockquote><pre>
+ * <hr><blockquote><pre>
* class PrimeRun implements Runnable {
* long minPrime;
* PrimeRun(long minPrime) {
@@ -117,7 +117,7 @@
* </pre></blockquote><hr>
* <p>
* The following code would then create a thread and start it running:
- * <p><blockquote><pre>
+ * <blockquote><pre>
* PrimeRun p = new PrimeRun(143);
* new Thread(p).start();
* </pre></blockquote>
--- a/jdk/src/share/classes/java/lang/invoke/LambdaMetafactory.java Tue Oct 22 19:37:11 2013 -0400
+++ b/jdk/src/share/classes/java/lang/invoke/LambdaMetafactory.java Tue Oct 22 19:43:42 2013 -0400
@@ -183,15 +183,15 @@
* @param samMethodType MethodType of the method in the functional interface
* to which the lambda or method reference is being
* converted, represented as a MethodType.
- * @param implMethod The implementation method which should be called
- * (with suitable adaptation of argument types, return
- * types, and adjustment for captured arguments) when
- * methods of the resulting functional interface instance
- * are invoked.
+ * @param implMethod A direct method handle describing the implementation
+ * method which should be called (with suitable adaptation
+ * of argument types, return types, and adjustment for
+ * captured arguments) when methods of the resulting
+ * functional interface instance are invoked.
* @param instantiatedMethodType The signature of the primary functional
* interface method after type variables
* are substituted with their instantiation
- * from the capture site
+ * from the capture site.
* @return a CallSite, which, when invoked, will return an instance of the
* functional interface
* @throws ReflectiveOperationException if the caller is not able to
@@ -220,15 +220,21 @@
* references to functional interfaces, which supports serialization and
* other uncommon options.
*
- * The declared argument list for this method is:
+ * <p>The declared argument list for this method is:
*
+ * <pre>{@code
* CallSite altMetafactory(MethodHandles.Lookup caller,
* String invokedName,
* MethodType invokedType,
* Object... args)
+ * }</pre>
*
- * but it behaves as if the argument list is:
+ * <p>but it behaves as if the argument list is as follows, where names that
+ * appear in the argument list for
+ * {@link #metafactory(MethodHandles.Lookup, String, MethodType, MethodType, MethodHandle, MethodType)}
+ * have the same specification as in that method:
*
+ * <pre>{@code
* CallSite altMetafactory(MethodHandles.Lookup caller,
* String invokedName,
* MethodType invokedType,
@@ -241,7 +247,15 @@
* int bridgeCount, // IF flags has BRIDGES set
* MethodType... bridges // IF flags has BRIDGES set
* )
+ * }</pre>
*
+ * <p>If the flags contains {@code FLAG_SERIALIZABLE}, or one of the marker
+ * interfaces extends {@link Serializable}, the metafactory will link the
+ * call site to one that produces a serializable lambda. In addition to
+ * the lambda instance implementing {@code Serializable}, it will have a
+ * {@code writeReplace} method that returns an appropriate {@link
+ * SerializedLambda}, and an appropriate {@code $deserializeLambda$}
+ * method.
*
* @param caller Stacked automatically by VM; represents a lookup context
* with the accessibility privileges of the caller.
@@ -257,7 +271,7 @@
* In the event that the implementation method is an
* instance method, the first argument in the invocation
* signature will correspond to the receiver.
- * @param args flags and optional arguments, as described above
+ * @param args flags and optional arguments, as described above.
* @return a CallSite, which, when invoked, will return an instance of the
* functional interface
* @throws ReflectiveOperationException if the caller is not able to
--- a/jdk/src/share/classes/java/lang/invoke/SerializedLambda.java Tue Oct 22 19:37:11 2013 -0400
+++ b/jdk/src/share/classes/java/lang/invoke/SerializedLambda.java Tue Oct 22 19:43:42 2013 -0400
@@ -32,9 +32,26 @@
import java.util.Objects;
/**
- * Serialized form of a lambda expression. The properties of this class represent the information that is present
- * at the lambda factory site, including the identity of the primary functional interface method, the identity of the
- * implementation method, and any variables captured from the local environment at the time of lambda capture.
+ * Serialized form of a lambda expression. The properties of this class
+ * represent the information that is present at the lambda factory site, including
+ * static metafactory arguments such as the identity of the primary functional
+ * interface method and the identity of the implementation method, as well as
+ * dynamic metafactory arguments such as values captured from the lexical scope
+ * at the time of lambda capture.
+ *
+ * <p>Implementors of serializable lambdas, such as compilers or language
+ * runtime libraries, are expected to ensure that instances deserialize properly.
+ * One means to do so is to ensure that the {@code writeReplace} method returns
+ * an instance of {@code SerializedLambda}, rather than allowing default
+ * serialization to proceed.
+ *
+ * <p>{@code SerializedLambda} has a {@code readResolve} method that looks for
+ * a (possibly private) static method called
+ * {@code $deserializeLambda$(SerializedLambda)} in the capturing class, invokes
+ * that with itself as the first argument, and returns the result. Lambda classes
+ * implementing {@code $deserializeLambda$} are responsible for validating
+ * that the properties of the {@code SerializedLambda} are consistent with a
+ * lambda actually captured by that class.
*
* @see LambdaMetafactory
*/
--- a/jdk/src/share/classes/java/lang/management/ManagementFactory.java Tue Oct 22 19:37:11 2013 -0400
+++ b/jdk/src/share/classes/java/lang/management/ManagementFactory.java Tue Oct 22 19:43:42 2013 -0400
@@ -60,7 +60,7 @@
* one or more <i>platform MXBeans</i> representing
* the management interface of a component of the Java virtual
* machine.
- * <p>
+ *
* <h3><a name="MXBean">Platform MXBeans</a></h3>
* <p>
* A platform MXBean is a <i>managed bean</i> that
--- a/jdk/src/share/classes/java/lang/management/ManagementPermission.java Tue Oct 22 19:37:11 2013 -0400
+++ b/jdk/src/share/classes/java/lang/management/ManagementPermission.java Tue Oct 22 19:43:42 2013 -0400
@@ -33,10 +33,8 @@
* The following table
* provides a summary description of what the permission allows,
* and discusses the risks of granting code the permission.
- * <P>
*
- * <table border=1 cellpadding=5 summary="Table shows permission target name, wh
-at the permission allows, and associated risks">
+ * <table border=1 cellpadding=5 summary="Table shows permission target name, what the permission allows, and associated risks">
* <tr>
* <th>Permission Target Name</th>
* <th>What the Permission Allows</th>
--- a/jdk/src/share/classes/java/lang/management/MemoryUsage.java Tue Oct 22 19:37:11 2013 -0400
+++ b/jdk/src/share/classes/java/lang/management/MemoryUsage.java Tue Oct 22 19:43:42 2013 -0400
@@ -79,7 +79,7 @@
* </table>
*
* Below is a picture showing an example of a memory pool:
- * <p>
+ *
* <pre>
* +----------------------------------------------+
* +//////////////// | +
@@ -250,7 +250,7 @@
* Returns a <tt>MemoryUsage</tt> object represented by the
* given <tt>CompositeData</tt>. The given <tt>CompositeData</tt>
* must contain the following attributes:
- * <p>
+ *
* <blockquote>
* <table border summary="The attributes and the types the given CompositeData contains">
* <tr>
--- a/jdk/src/share/classes/java/lang/management/package.html Tue Oct 22 19:37:11 2013 -0400
+++ b/jdk/src/share/classes/java/lang/management/package.html Tue Oct 22 19:43:42 2013 -0400
@@ -82,7 +82,7 @@
<b>1. Direct access to an MXBean interface</b>
<p>
<ul>
-<li>Get an MXBean instance locally in the running Java virtual machine:<p>
+<li>Get an MXBean instance locally in the running Java virtual machine:
<pre>
RuntimeMXBean mxbean = ManagementFactory.getRuntimeMXBean();
@@ -103,7 +103,7 @@
<p>
</li>
<li>Construct an MXBean proxy instance that forwards the
- method calls to a given MBeanServer:<p>
+ method calls to a given MBeanServer:
<pre>
MBeanServerConnection mbs;
--- a/jdk/src/share/classes/java/lang/reflect/ReflectPermission.java Tue Oct 22 19:37:11 2013 -0400
+++ b/jdk/src/share/classes/java/lang/reflect/ReflectPermission.java Tue Oct 22 19:43:42 2013 -0400
@@ -31,7 +31,6 @@
* The following table
* provides a summary description of what the permission allows,
* and discusses the risks of granting code the permission.
- * <P>
*
* <table border=1 cellpadding=5 summary="Table shows permission target name, what the permission allows, and associated risks">
* <tr>
--- a/jdk/src/share/classes/java/net/DatagramSocket.java Tue Oct 22 19:37:11 2013 -0400
+++ b/jdk/src/share/classes/java/net/DatagramSocket.java Tue Oct 22 19:43:42 2013 -0400
@@ -196,7 +196,7 @@
* socket address.
* <p>
* If, if the address is {@code null}, creates an unbound socket.
- * <p>
+ *
* <p>If there is a security manager,
* its {@code checkListen} method is first called
* with the port from the socket address
@@ -1109,7 +1109,7 @@
* represent the value of the TOS octet in IP packets sent by
* the socket.
* RFC 1349 defines the TOS values as follows:
- * <p>
+ *
* <UL>
* <LI><CODE>IPTOS_LOWCOST (0x02)</CODE></LI>
* <LI><CODE>IPTOS_RELIABILITY (0x04)</CODE></LI>
--- a/jdk/src/share/classes/java/net/Inet6Address.java Tue Oct 22 19:37:11 2013 -0400
+++ b/jdk/src/share/classes/java/net/Inet6Address.java Tue Oct 22 19:43:42 2013 -0400
@@ -133,7 +133,7 @@
* representation. However, it will be converted into an IPv4
* address.</td></tr>
* </table></blockquote>
- * <p>
+ *
* <h4><A NAME="scoped">Textual representation of IPv6 scoped addresses</a></h4>
*
* <p> The textual representation of IPv6 addresses as described above can be
@@ -150,11 +150,11 @@
*
* <p> The general format for specifying the <i>scope_id</i> is the following:
*
- * <p><blockquote><i>IPv6-address</i>%<i>scope_id</i></blockquote>
+ * <blockquote><i>IPv6-address</i>%<i>scope_id</i></blockquote>
* <p> The IPv6-address is a literal IPv6 address as described above.
* The <i>scope_id</i> refers to an interface on the local system, and it can be
* specified in two ways.
- * <p><ol><li><i>As a numeric identifier.</i> This must be a positive integer
+ * <ol><li><i>As a numeric identifier.</i> This must be a positive integer
* that identifies the particular interface and scope as understood by the
* system. Usually, the numeric values can be determined through administration
* tools on the system. Each interface may have multiple values, one for each
--- a/jdk/src/share/classes/java/net/MulticastSocket.java Tue Oct 22 19:37:11 2013 -0400
+++ b/jdk/src/share/classes/java/net/MulticastSocket.java Tue Oct 22 19:43:42 2013 -0400
@@ -140,7 +140,7 @@
* Create a MulticastSocket bound to the specified socket address.
* <p>
* Or, if the address is {@code null}, create an unbound socket.
- * <p>
+ *
* <p>If there is a security manager,
* its {@code checkListen} method is first called
* with the SocketAddress port as its argument to ensure the operation is allowed.
--- a/jdk/src/share/classes/java/net/NetPermission.java Tue Oct 22 19:37:11 2013 -0400
+++ b/jdk/src/share/classes/java/net/NetPermission.java Tue Oct 22 19:43:42 2013 -0400
@@ -46,7 +46,6 @@
* The following table lists all the possible NetPermission target names,
* and for each provides a description of what the permission allows
* and a discussion of the risks of granting code the permission.
- * <P>
*
* <table border=1 cellpadding=5 summary="Permission target name, what the permission allows, and associated risks">
* <tr>
--- a/jdk/src/share/classes/java/net/Proxy.java Tue Oct 22 19:37:11 2013 -0400
+++ b/jdk/src/share/classes/java/net/Proxy.java Tue Oct 22 19:43:42 2013 -0400
@@ -66,8 +66,8 @@
* Used, for instance, to create sockets bypassing any other global
* proxy settings (like SOCKS):
* <P>
- * {@code Socket s = new Socket(Proxy.NO_PROXY);}<br>
- * <P>
+ * {@code Socket s = new Socket(Proxy.NO_PROXY);}
+ *
*/
public final static Proxy NO_PROXY = new Proxy();
--- a/jdk/src/share/classes/java/net/Socket.java Tue Oct 22 19:37:11 2013 -0400
+++ b/jdk/src/share/classes/java/net/Socket.java Tue Oct 22 19:43:42 2013 -0400
@@ -1230,13 +1230,13 @@
* Generally, the window size can be modified at any time when a socket is
* connected. However, if a receive window larger than 64K is required then
* this must be requested <B>before</B> the socket is connected to the
- * remote peer. There are two cases to be aware of:<p>
+ * remote peer. There are two cases to be aware of:
* <ol>
* <li>For sockets accepted from a ServerSocket, this must be done by calling
* {@link ServerSocket#setReceiveBufferSize(int)} before the ServerSocket
* is bound to a local address.<p></li>
* <li>For client sockets, setReceiveBufferSize() must be called before
- * connecting the socket to its remote peer.<p></li></ol>
+ * connecting the socket to its remote peer.</li></ol>
* @param size the size to which to set the receive buffer
* size. This value must be greater than 0.
*
@@ -1329,7 +1329,7 @@
* represent the value of the TOS octet in IP packets sent by
* the socket.
* RFC 1349 defines the TOS values as follows:
- * <p>
+ *
* <UL>
* <LI><CODE>IPTOS_LOWCOST (0x02)</CODE></LI>
* <LI><CODE>IPTOS_RELIABILITY (0x04)</CODE></LI>
--- a/jdk/src/share/classes/java/net/SocketOptions.java Tue Oct 22 19:37:11 2013 -0400
+++ b/jdk/src/share/classes/java/net/SocketOptions.java Tue Oct 22 19:43:42 2013 -0400
@@ -134,7 +134,7 @@
* previously written data.
*<P>
* Valid for TCP only: SocketImpl.
- * <P>
+ *
* @see Socket#setTcpNoDelay
* @see Socket#getTcpNoDelay
*/
@@ -155,7 +155,7 @@
* This option <B>must</B> be specified in the constructor.
* <P>
* Valid for: SocketImpl, DatagramSocketImpl
- * <P>
+ *
* @see Socket#getLocalAddress
* @see DatagramSocket#getLocalAddress
*/
@@ -186,7 +186,7 @@
* want to use other than the system default. Takes/returns an InetAddress.
* <P>
* Valid for Multicast: DatagramSocketImpl
- * <P>
+ *
* @see MulticastSocket#setInterface(InetAddress)
* @see MulticastSocket#getInterface()
*/
--- a/jdk/src/share/classes/java/net/SocketPermission.java Tue Oct 22 19:37:11 2013 -0400
+++ b/jdk/src/share/classes/java/net/SocketPermission.java Tue Oct 22 19:43:42 2013 -0400
@@ -779,27 +779,27 @@
* specified permission.
* <P>
* More specifically, this method first ensures that all of the following
- * are true (and returns false if any of them are not):<p>
+ * are true (and returns false if any of them are not):
* <ul>
- * <li> <i>p</i> is an instanceof SocketPermission,<p>
+ * <li> <i>p</i> is an instanceof SocketPermission,
* <li> <i>p</i>'s actions are a proper subset of this
- * object's actions, and<p>
+ * object's actions, and
* <li> <i>p</i>'s port range is included in this port range. Note:
- * port range is ignored when p only contains the action, 'resolve'.<p>
+ * port range is ignored when p only contains the action, 'resolve'.
* </ul>
*
* Then {@code implies} checks each of the following, in order,
- * and for each returns true if the stated condition is true:<p>
+ * and for each returns true if the stated condition is true:
* <ul>
* <li> If this object was initialized with a single IP address and one of <i>p</i>'s
- * IP addresses is equal to this object's IP address.<p>
+ * IP addresses is equal to this object's IP address.
* <li>If this object is a wildcard domain (such as *.sun.com), and
* <i>p</i>'s canonical name (the name without any preceding *)
* ends with this object's canonical host name. For example, *.sun.com
- * implies *.eng.sun.com..<p>
+ * implies *.eng.sun.com.
* <li>If this object was not initialized with a single IP address, and one of this
- * object's IP addresses equals one of <i>p</i>'s IP addresses.<p>
- * <li>If this canonical name equals <i>p</i>'s canonical name.<p>
+ * object's IP addresses equals one of <i>p</i>'s IP addresses.
+ * <li>If this canonical name equals <i>p</i>'s canonical name.
* </ul>
*
* If none of the above are true, {@code implies} returns false.
--- a/jdk/src/share/classes/java/net/URI.java Tue Oct 22 19:37:11 2013 -0400
+++ b/jdk/src/share/classes/java/net/URI.java Tue Oct 22 19:43:42 2013 -0400
@@ -389,20 +389,20 @@
* colon following a host name but no port (as in
* {@code http://java.sun.com:} ), and that does not encode characters
* except those that must be quoted, the following identities also hold:
- * <p><pre>
+ * <pre>
* new URI(<i>u</i>.getScheme(),
* <i>u</i>.getSchemeSpecificPart(),
* <i>u</i>.getFragment())
* .equals(<i>u</i>)</pre>
* in all cases,
- * <p><pre>
+ * <pre>
* new URI(<i>u</i>.getScheme(),
* <i>u</i>.getUserInfo(), <i>u</i>.getAuthority(),
* <i>u</i>.getPath(), <i>u</i>.getQuery(),
* <i>u</i>.getFragment())
* .equals(<i>u</i>)</pre>
* if <i>u</i> is hierarchical, and
- * <p><pre>
+ * <pre>
* new URI(<i>u</i>.getScheme(),
* <i>u</i>.getUserInfo(), <i>u</i>.getHost(), <i>u</i>.getPort(),
* <i>u</i>.getPath(), <i>u</i>.getQuery(),
--- a/jdk/src/share/classes/java/net/URLConnection.java Tue Oct 22 19:37:11 2013 -0400
+++ b/jdk/src/share/classes/java/net/URLConnection.java Tue Oct 22 19:43:42 2013 -0400
@@ -45,7 +45,7 @@
* application and a URL. Instances of this class can be used both to
* read from and to write to the resource referenced by the URL. In
* general, creating a connection to a URL is a multistep process:
- * <p>
+ *
* <center><table border=2 summary="Describes the process of creating a connection to a URL: openConnection() and connect() over time.">
* <tr><th>{@code openConnection()}</th>
* <th>{@code connect()}</th></tr>
--- a/jdk/src/share/classes/java/net/URLDecoder.java Tue Oct 22 19:37:11 2013 -0400
+++ b/jdk/src/share/classes/java/net/URLDecoder.java Tue Oct 22 19:43:42 2013 -0400
@@ -43,7 +43,7 @@
* as the start of a special escaped sequence.
* <p>
* The following rules are applied in the conversion:
- * <p>
+ *
* <ul>
* <li>The alphanumeric characters "{@code a}" through
* "{@code z}", "{@code A}" through
--- a/jdk/src/share/classes/java/net/URLEncoder.java Tue Oct 22 19:37:11 2013 -0400
+++ b/jdk/src/share/classes/java/net/URLEncoder.java Tue Oct 22 19:43:42 2013 -0400
@@ -49,7 +49,6 @@
* <p>
* When encoding a String, the following rules apply:
*
- * <p>
* <ul>
* <li>The alphanumeric characters "{@code a}" through
* "{@code z}", "{@code A}" through
--- a/jdk/src/share/classes/java/net/URLPermission.java Tue Oct 22 19:37:11 2013 -0400
+++ b/jdk/src/share/classes/java/net/URLPermission.java Tue Oct 22 19:43:42 2013 -0400
@@ -45,7 +45,7 @@
* </pre>
* <i>scheme</i> will typically be http or https, but is not restricted by this
* class.
- * <i>authority</i> is specified as:<p>
+ * <i>authority</i> is specified as:
* <pre>
* authority = hostrange [ : portrange ]
* portrange = portnumber | -portnumber | portnumber-[portnumber] | *
@@ -223,7 +223,7 @@
* Checks if this URLPermission implies the given permission.
* Specifically, the following checks are done as if in the
* following sequence:
- * <p><ul>
+ * <ul>
* <li>if 'p' is not an instance of URLPermission return false</li>
* <li>if any of p's methods are not in this's method list, and if
* this's method list is not equal to "*", then return false.</li>
@@ -242,7 +242,7 @@
* <li>otherwise, return false</li>
* </ul>
* <p>Some examples of how paths are matched are shown below:
- * <p><table border>
+ * <table border>
* <caption>Examples of Path Matching</caption>
* <tr><th>this's path</th><th>p's path</th><th>match</th></tr>
* <tr><td>/a/b</td><td>/a/b</td><td>yes</td></tr>
--- a/jdk/src/share/classes/java/net/package-info.java Tue Oct 22 19:37:11 2013 -0400
+++ b/jdk/src/share/classes/java/net/package-info.java Tue Oct 22 19:43:42 2013 -0400
@@ -127,9 +127,9 @@
* resources, then convert it into a {@link java.net.URL} when it is time to
* access the resource. From that URL, you can either get the
* {@link java.net.URLConnection} for fine control, or get directly the
- * InputStream.<p>
+ * InputStream.
* <p>Here is an example:</p>
- * <p><pre>
+ * <pre>
* URI uri = new URI("http://java.sun.com/");
* URL url = uri.toURL();
* InputStream in = url.openStream();
@@ -147,7 +147,7 @@
* the {@code java.protocol.handler.pkgs} system property. For instance if
* it is set to {@code myapp.protocols}, then the URL code will try, in the
* case of http, first to load {@code myapp.protocols.http.Handler}, then,
- * if this fails, {@code http.Handler} from the default location.<p>
+ * if this fails, {@code http.Handler} from the default location.
* <p>Note that the Handler class <b>has to</b> be a subclass of the abstract
* class {@link java.net.URLStreamHandler}.</p>
* <h2>Additional Specification</h2>
--- a/jdk/src/share/classes/java/nio/X-Buffer.java.template Tue Oct 22 19:37:11 2013 -0400
+++ b/jdk/src/share/classes/java/nio/X-Buffer.java.template Tue Oct 22 19:43:42 2013 -0400
@@ -1129,7 +1129,7 @@
*
* <p> Two $type$ buffers are equal if, and only if,
*
- * <p><ol>
+ * <ol>
*
* <li><p> They have the same element type, </p></li>
*
--- a/jdk/src/share/classes/java/nio/file/FileSystem.java Tue Oct 22 19:37:11 2013 -0400
+++ b/jdk/src/share/classes/java/nio/file/FileSystem.java Tue Oct 22 19:43:42 2013 -0400
@@ -355,7 +355,7 @@
*
* <p> The following rules are used to interpret glob patterns:
*
- * <p> <ul>
+ * <ul>
* <li><p> The {@code *} character matches zero or more {@link Character
* characters} of a {@link Path#getName(int) name} component without
* crossing directory boundaries. </p></li>
--- a/jdk/src/share/classes/java/rmi/RMISecurityManager.java Tue Oct 22 19:37:11 2013 -0400
+++ b/jdk/src/share/classes/java/rmi/RMISecurityManager.java Tue Oct 22 19:43:42 2013 -0400
@@ -1,5 +1,5 @@
/*
- * Copyright (c) 1996, 2003, Oracle and/or its affiliates. All rights reserved.
+ * Copyright (c) 1996, 2013, Oracle and/or its affiliates. All rights reserved.
* DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
*
* This code is free software; you can redistribute it and/or modify it
@@ -28,35 +28,38 @@
import java.security.*;
/**
- * A subclass of {@link SecurityManager} used by RMI applications that use
- * downloaded code. RMI's class loader will not download any classes from
- * remote locations if no security manager has been set.
- * <code>RMISecurityManager</code> does not apply to applets, which run
- * under the protection of their browser's security manager.
+ * {@code RMISecurityManager} implements a policy identical to the policy
+ * implemented by {@link SecurityManager}. RMI applications
+ * should use the {@code SecurityManager} class or another appropriate
+ * {@code SecurityManager} implementation instead of this class. RMI's class
+ * loader will download classes from remote locations only if a security
+ * manager has been set.
*
- * <code>RMISecurityManager</code> implements a policy that
- * is no different than the policy implemented by {@link SecurityManager}.
- * Therefore an RMI application should use the <code>SecurityManager</code>
- * class or another application-specific <code>SecurityManager</code>
- * implementation instead of this class.
+ * @implNote
+ * <p>Applets typically run in a container that already has a security
+ * manager, so there is generally no need for applets to set a security
+ * manager. If you have a standalone application, you might need to set a
+ * {@code SecurityManager} in order to enable class downloading. This can be
+ * done by adding the following to your code. (It needs to be executed before
+ * RMI can download code from remote hosts, so it most likely needs to appear
+ * in the {@code main} method of your application.)
*
- * <p>To use a <code>SecurityManager</code> in your application, add
- * the following statement to your code (it needs to be executed before RMI
- * can download code from remote hosts, so it most likely needs to appear
- * in the <code>main</code> method of your application):
- *
- * <pre>
- * System.setSecurityManager(new SecurityManager());
- * </pre>
+ * <pre>{@code
+ * if (System.getSecurityManager() == null) {
+ * System.setSecurityManager(new SecurityManager());
+ * }
+ * }</pre>
*
* @author Roger Riggs
* @author Peter Jones
* @since JDK1.1
- **/
+ * @deprecated Use {@link SecurityManager} instead.
+ */
+@Deprecated
public class RMISecurityManager extends SecurityManager {
/**
- * Constructs a new <code>RMISecurityManager</code>.
+ * Constructs a new {@code RMISecurityManager}.
* @since JDK1.1
*/
public RMISecurityManager() {
--- a/jdk/src/share/classes/java/rmi/activation/ActivationGroup.java Tue Oct 22 19:37:11 2013 -0400
+++ b/jdk/src/share/classes/java/rmi/activation/ActivationGroup.java Tue Oct 22 19:43:42 2013 -0400
@@ -74,7 +74,7 @@
* <code>ActivationGroup</code> will override the system properties
* with the properties requested when its
* <code>ActivationGroupDesc</code> was created, and will set a
- * <code>java.rmi.RMISecurityManager</code> as the default system
+ * {@link SecurityManager} as the default system
* security manager. If your application requires specific properties
* to be set when objects are activated in the group, the application
* should create a special <code>Properties</code> object containing
@@ -84,7 +84,7 @@
* <code>ActivationDesc</code>s (before the default
* <code>ActivationGroupDesc</code> is created). If your application
* requires the use of a security manager other than
- * <code>java.rmi.RMISecurityManager</code>, in the
+ * {@link SecurityManager}, in the
* ActivativationGroupDescriptor properties list you can set
* <code>java.security.manager</code> property to the name of the security
* manager you would like to install.
@@ -154,21 +154,21 @@
* active). If the object does not call
* <code>Activatable.inactive</code> when it deactivates, the
* object will never be garbage collected since the group keeps
- * strong references to the objects it creates. <p>
+ * strong references to the objects it creates.
*
* <p>The group's <code>inactiveObject</code> method unexports the
* remote object from the RMI runtime so that the object can no
* longer receive incoming RMI calls. An object will only be unexported
* if the object has no pending or executing calls.
* The subclass of <code>ActivationGroup</code> must override this
- * method and unexport the object. <p>
+ * method and unexport the object.
*
* <p>After removing the object from the RMI runtime, the group
* must inform its <code>ActivationMonitor</code> (via the monitor's
* <code>inactiveObject</code> method) that the remote object is
* not currently active so that the remote object will be
* re-activated by the activator upon a subsequent activation
- * request.<p>
+ * request.
*
* <p>This method simply informs the group's monitor that the object
* is inactive. It is up to the concrete subclass of ActivationGroup
@@ -235,7 +235,7 @@
* <p>Note that if your application creates its own custom
* activation group, a security manager must be set for that
* group. Otherwise objects cannot be activated in the group.
- * <code>java.rmi.RMISecurityManager</code> is set by default.
+ * {@link SecurityManager} is set by default.
*
* <p>If a security manager is already set in the group VM, this
* method first calls the security manager's
--- a/jdk/src/share/classes/java/rmi/dgc/VMID.java Tue Oct 22 19:37:11 2013 -0400
+++ b/jdk/src/share/classes/java/rmi/dgc/VMID.java Tue Oct 22 19:43:42 2013 -0400
@@ -67,7 +67,7 @@
* conditions: a) the conditions for uniqueness for objects of
* the class <code>java.rmi.server.UID</code> are satisfied, and b) an
* address can be obtained for this host that is unique and constant
- * for the lifetime of this object. <p>
+ * for the lifetime of this object.
*/
public VMID() {
addr = randomBytes;
--- a/jdk/src/share/classes/java/rmi/server/ServerRef.java Tue Oct 22 19:37:11 2013 -0400
+++ b/jdk/src/share/classes/java/rmi/server/ServerRef.java Tue Oct 22 19:43:42 2013 -0400
@@ -1,5 +1,5 @@
/*
- * Copyright (c) 1996, 1999, Oracle and/or its affiliates. All rights reserved.
+ * Copyright (c) 1996, 2013, Oracle and/or its affiliates. All rights reserved.
* DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
*
* This code is free software; you can redistribute it and/or modify it
@@ -33,7 +33,9 @@
*
* @author Ann Wollrath
* @since JDK1.1
+ * @deprecated No replacement. This interface is unused and is obsolete.
*/
+@Deprecated
public interface ServerRef extends RemoteRef {
/** indicate compatibility with JDK 1.1.x version of class. */
--- a/jdk/src/share/classes/java/rmi/server/SocketSecurityException.java Tue Oct 22 19:37:11 2013 -0400
+++ b/jdk/src/share/classes/java/rmi/server/SocketSecurityException.java Tue Oct 22 19:43:42 2013 -0400
@@ -1,5 +1,5 @@
/*
- * Copyright (c) 1996, 2003, Oracle and/or its affiliates. All rights reserved.
+ * Copyright (c) 1996, 2013, Oracle and/or its affiliates. All rights reserved.
* DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
*
* This code is free software; you can redistribute it and/or modify it
@@ -30,7 +30,9 @@
*
* @author Ann Wollrath
* @since JDK1.1
- **/
+ * @deprecated This class is obsolete. Use {@link ExportException} instead.
+ */
+@Deprecated
public class SocketSecurityException extends ExportException {
/* indicate compatibility with JDK 1.1.x version of class */
--- a/jdk/src/share/classes/java/rmi/server/UnicastRemoteObject.java Tue Oct 22 19:37:11 2013 -0400
+++ b/jdk/src/share/classes/java/rmi/server/UnicastRemoteObject.java Tue Oct 22 19:43:42 2013 -0400
@@ -36,7 +36,7 @@
* below, the stub for a remote object being exported is obtained as
* follows:
*
- * <p><ul>
+ * <ul>
*
* <li>If the remote object is exported using the {@link
* #exportObject(Remote) UnicastRemoteObject.exportObject(Remote)} method,
@@ -66,9 +66,8 @@
* could not be loaded, or a problem occurs creating the stub instance, a
* {@link StubNotFoundException} is thrown.
*
- * <p>
* <li>For all other means of exporting:
- * <p><ul>
+ * <ul>
*
* <li>If the remote object's stub class (as defined above) could not be
* loaded or the system property
@@ -93,7 +92,6 @@
* will be thrown.
* </ul>
*
- * <p>
* <li>Otherwise, an instance of the remote object's stub class (as
* described above) is used as the stub.
*
--- a/jdk/src/share/classes/java/security/AccessController.java Tue Oct 22 19:37:11 2013 -0400
+++ b/jdk/src/share/classes/java/security/AccessController.java Tue Oct 22 19:43:42 2013 -0400
@@ -39,9 +39,9 @@
* <ul>
* <li> to decide whether an access to a critical system
* resource is to be allowed or denied, based on the security policy
- * currently in effect,<p>
+ * currently in effect,
* <li>to mark code as being "privileged", thus affecting subsequent
- * access determinations, and<p>
+ * access determinations, and
* <li>to obtain a "snapshot" of the current calling context so
* access-control decisions from a different context can be made with
* respect to the saved context. </ul>
--- a/jdk/src/share/classes/java/security/AlgorithmParameterGenerator.java Tue Oct 22 19:37:11 2013 -0400
+++ b/jdk/src/share/classes/java/security/AlgorithmParameterGenerator.java Tue Oct 22 19:43:42 2013 -0400
@@ -48,7 +48,7 @@
* of the prime modulus (in bits).
* When using this approach, algorithm-specific parameter generation
* values - if any - default to some standard values, unless they can be
- * derived from the specified size.<P>
+ * derived from the specified size.
*
* <li>The other approach initializes a parameter generator object
* using algorithm-specific semantics, which are represented by a set of
--- a/jdk/src/share/classes/java/security/BasicPermission.java Tue Oct 22 19:37:11 2013 -0400
+++ b/jdk/src/share/classes/java/security/BasicPermission.java Tue Oct 22 19:43:42 2013 -0400
@@ -57,7 +57,6 @@
* Subclasses may implement actions on top of BasicPermission,
* if desired.
* <p>
- * <P>
* @see java.security.Permission
* @see java.security.Permissions
* @see java.security.PermissionCollection
@@ -153,9 +152,9 @@
* Checks if the specified permission is "implied" by
* this object.
* <P>
- * More specifically, this method returns true if:<p>
+ * More specifically, this method returns true if:
* <ul>
- * <li> <i>p</i>'s class is the same as this object's class, and<p>
+ * <li> <i>p</i>'s class is the same as this object's class, and
* <li> <i>p</i>'s name equals or (in the case of wildcards)
* is implied by this object's
* name. For example, "a.b.*" implies "a.b.c".
--- a/jdk/src/share/classes/java/security/CodeSource.java Tue Oct 22 19:37:11 2013 -0400
+++ b/jdk/src/share/classes/java/security/CodeSource.java Tue Oct 22 19:43:42 2013 -0400
@@ -234,7 +234,7 @@
* Returns true if this CodeSource object "implies" the specified CodeSource.
* <p>
* More specifically, this method makes the following checks.
- * If any fail, it returns false. If they all succeed, it returns true.<p>
+ * If any fail, it returns false. If they all succeed, it returns true.
* <ul>
* <li> <i>codesource</i> must not be null.
* <li> If this object's certificates are not null, then all
@@ -242,7 +242,7 @@
* certificates.
* <li> If this object's location (getLocation()) is not null, then the
* following checks are made against this object's location and
- * <i>codesource</i>'s:<p>
+ * <i>codesource</i>'s:
* <ul>
* <li> <i>codesource</i>'s location must not be null.
*
--- a/jdk/src/share/classes/java/security/Key.java Tue Oct 22 19:37:11 2013 -0400
+++ b/jdk/src/share/classes/java/security/Key.java Tue Oct 22 19:43:42 2013 -0400
@@ -39,7 +39,7 @@
* RSA), which will work with those algorithms and with related
* algorithms (such as MD5 with RSA, SHA-1 with RSA, Raw DSA, etc.)
* The name of the algorithm of a key is obtained using the
- * {@link #getAlgorithm() getAlgorithm} method.<P>
+ * {@link #getAlgorithm() getAlgorithm} method.
*
* <LI>An Encoded Form
*
@@ -65,12 +65,11 @@
* For more information, see
* <a href="http://www.ietf.org/rfc/rfc3280.txt">RFC 3280:
* Internet X.509 Public Key Infrastructure Certificate and CRL Profile</a>.
- * <P>
*
* <LI>A Format
*
* <P>This is the name of the format of the encoded key. It is returned
- * by the {@link #getFormat() getFormat} method.<P>
+ * by the {@link #getFormat() getFormat} method.
*
* </UL>
*
--- a/jdk/src/share/classes/java/security/KeyPairGenerator.java Tue Oct 22 19:37:11 2013 -0400
+++ b/jdk/src/share/classes/java/security/KeyPairGenerator.java Tue Oct 22 19:43:42 2013 -0400
@@ -77,7 +77,6 @@
* providers might have precomputed parameter sets for more than just the
* three modulus sizes mentioned above. Still others might not have a list of
* precomputed parameters at all and instead always create new parameter sets.
- * <p>
*
* <li><b>Algorithm-Specific Initialization</b>
* <p>For situations where a set of algorithm-specific parameters already
--- a/jdk/src/share/classes/java/security/KeyStore.java Tue Oct 22 19:37:11 2013 -0400
+++ b/jdk/src/share/classes/java/security/KeyStore.java Tue Oct 22 19:43:42 2013 -0400
@@ -98,7 +98,6 @@
* KeyStore ks = KeyStore.getInstance(KeyStore.getDefaultType());
* </pre>
* The system will return a keystore implementation for the default type.
- * <p>
*
* <li>To provide a specific keystore type:
* <pre>
--- a/jdk/src/share/classes/java/security/MessageDigest.java Tue Oct 22 19:37:11 2013 -0400
+++ b/jdk/src/share/classes/java/security/MessageDigest.java Tue Oct 22 19:43:42 2013 -0400
@@ -54,21 +54,21 @@
*
* <p>Implementations are free to implement the Cloneable interface.
* Client applications can test cloneability by attempting cloning
- * and catching the CloneNotSupportedException: <p>
+ * and catching the CloneNotSupportedException:
+ *
+ * <pre>{@code
+ * MessageDigest md = MessageDigest.getInstance("SHA");
*
-* <pre>
-* MessageDigest md = MessageDigest.getInstance("SHA");
-*
-* try {
-* md.update(toChapter1);
-* MessageDigest tc1 = md.clone();
-* byte[] toChapter1Digest = tc1.digest();
-* md.update(toChapter2);
-* ...etc.
-* } catch (CloneNotSupportedException cnse) {
-* throw new DigestException("couldn't make digest of partial content");
-* }
-* </pre>
+ * try {
+ * md.update(toChapter1);
+ * MessageDigest tc1 = md.clone();
+ * byte[] toChapter1Digest = tc1.digest();
+ * md.update(toChapter2);
+ * ...etc.
+ * } catch (CloneNotSupportedException cnse) {
+ * throw new DigestException("couldn't make digest of partial content");
+ * }
+ * }</pre>
*
* <p>Note that if a given implementation is not cloneable, it is
* still possible to compute intermediate digests by instantiating
--- a/jdk/src/share/classes/java/security/Permission.java Tue Oct 22 19:37:11 2013 -0400
+++ b/jdk/src/share/classes/java/security/Permission.java Tue Oct 22 19:43:42 2013 -0400
@@ -138,14 +138,14 @@
* Returns the hash code value for this Permission object.
* <P>
* The required {@code hashCode} behavior for Permission Objects is
- * the following: <p>
+ * the following:
* <ul>
* <li>Whenever it is invoked on the same Permission object more than
* once during an execution of a Java application, the
* {@code hashCode} method
* must consistently return the same integer. This integer need not
* remain consistent from one execution of an application to another
- * execution of the same application. <p>
+ * execution of the same application.
* <li>If two Permission objects are equal according to the
* {@code equals}
* method, then calling the {@code hashCode} method on each of the
--- a/jdk/src/share/classes/java/security/PermissionCollection.java Tue Oct 22 19:37:11 2013 -0400
+++ b/jdk/src/share/classes/java/security/PermissionCollection.java Tue Oct 22 19:43:42 2013 -0400
@@ -37,7 +37,6 @@
* collection, using the {@code implies} method.
* <LI> enumerate all the permissions, using the {@code elements} method.
* </UL>
- * <P>
*
* <p>When it is desirable to group together a number of Permission objects
* of the same type, the {@code newPermissionCollection} method on that
--- a/jdk/src/share/classes/java/security/SecurityPermission.java Tue Oct 22 19:37:11 2013 -0400
+++ b/jdk/src/share/classes/java/security/SecurityPermission.java Tue Oct 22 19:43:42 2013 -0400
@@ -44,7 +44,6 @@
* The following table lists all the possible SecurityPermission target names,
* and for each provides a description of what the permission allows
* and a discussion of the risks of granting code the permission.
- * <P>
*
* <table border=1 cellpadding=5 summary="target name,what the permission allows, and associated risks">
* <tr>
@@ -193,7 +192,6 @@
* associated with classes that have been deprecated: {@link Identity},
* {@link IdentityScope}, {@link Signer}. Use of them is discouraged. See the
* applicable classes for more information.
- * <P>
*
* <table border=1 cellpadding=5 summary="target name,what the permission allows, and associated risks">
* <tr>
--- a/jdk/src/share/classes/java/security/Signature.java Tue Oct 22 19:37:11 2013 -0400
+++ b/jdk/src/share/classes/java/security/Signature.java Tue Oct 22 19:43:42 2013 -0400
@@ -77,13 +77,13 @@
* (see {@link #initSign(PrivateKey)}
* and {@link #initSign(PrivateKey, SecureRandom)}).
*
- * </ul><p>
+ * </ul>
*
- * <li>Updating<p>
+ * <li>Updating
*
* <p>Depending on the type of initialization, this will update the
* bytes to be signed or verified. See the
- * {@link #update(byte) update} methods.<p>
+ * {@link #update(byte) update} methods.
*
* <li>Signing or Verifying a signature on all updated bytes. See the
* {@link #sign() sign} methods and the {@link #verify(byte[]) verify}
--- a/jdk/src/share/classes/java/security/SignedObject.java Tue Oct 22 19:37:11 2013 -0400
+++ b/jdk/src/share/classes/java/security/SignedObject.java Tue Oct 22 19:43:42 2013 -0400
@@ -43,7 +43,7 @@
* object passed to the constructor and the {@code verify} method.
* A typical usage for signing is the following:
*
- * <p> <pre>{@code
+ * <pre>{@code
* Signature signingEngine = Signature.getInstance(algorithm,
* provider);
* SignedObject so = new SignedObject(myobject, signingKey,
@@ -53,7 +53,7 @@
* <p> A typical usage for verification is the following (having
* received SignedObject {@code so}):
*
- * <p> <pre>{@code
+ * <pre>{@code
* Signature verificationEngine =
* Signature.getInstance(algorithm, provider);
* if (so.verify(publickey, verificationEngine))
--- a/jdk/src/share/classes/java/security/acl/Acl.java Tue Oct 22 19:37:11 2013 -0400
+++ b/jdk/src/share/classes/java/security/acl/Acl.java Tue Oct 22 19:43:42 2013 -0400
@@ -42,27 +42,27 @@
* granted to the associated principal. If negative, the permissions
* are to be denied.<p>
*
- * The ACL Entries in each ACL observe the following rules:<p>
+ * The ACL Entries in each ACL observe the following rules:
*
* <ul> <li>Each principal can have at most one positive ACL entry and
* one negative entry; that is, multiple positive or negative ACL
* entries are not allowed for any principal. Each entry specifies
* the set of permissions that are to be granted (if positive) or
- * denied (if negative). <p>
+ * denied (if negative).
*
* <li>If there is no entry for a particular principal, then the
- * principal is considered to have a null (empty) permission set.<p>
+ * principal is considered to have a null (empty) permission set.
*
* <li>If there is a positive entry that grants a principal a
* particular permission, and a negative entry that denies the
* principal the same permission, the result is as though the
- * permission was never granted or denied. <p>
+ * permission was never granted or denied.
*
* <li>Individual permissions always override permissions of the
* group(s) to which the individual belongs. That is, individual
* negative permissions (specific denial of permissions) override the
* groups' positive permissions. And individual positive permissions
- * override the groups' negative permissions.<p>
+ * override the groups' negative permissions.
*
* </ul>
*
@@ -159,12 +159,12 @@
* Returns an enumeration for the set of allowed permissions for the
* specified principal (representing an entity such as an individual or
* a group). This set of allowed permissions is calculated as
- * follows:<p>
+ * follows:
*
* <ul>
*
* <li>If there is no entry in this Access Control List for the
- * specified principal, an empty permission set is returned.<p>
+ * specified principal, an empty permission set is returned.
*
* <li>Otherwise, the principal's group permission sets are determined.
* (A principal can belong to one or more groups, where a group is a
--- a/jdk/src/share/classes/java/security/cert/CertificateFactory.java Tue Oct 22 19:37:11 2013 -0400
+++ b/jdk/src/share/classes/java/security/cert/CertificateFactory.java Tue Oct 22 19:43:42 2013 -0400
@@ -63,7 +63,7 @@
* supports those methods), so that each call to
* {@code generateCertificate} consumes only one certificate, and the
* read position of the input stream is positioned to the next certificate in
- * the file:<p>
+ * the file:
*
* <pre>{@code
* FileInputStream fis = new FileInputStream(filename);
@@ -78,7 +78,7 @@
* }</pre>
*
* <p>The following example parses a PKCS#7-formatted certificate reply stored
- * in a file and extracts all the certificates from it:<p>
+ * in a file and extracts all the certificates from it:
*
* <pre>
* FileInputStream fis = new FileInputStream(filename);
--- a/jdk/src/share/classes/java/security/cert/PKIXRevocationChecker.java Tue Oct 22 19:37:11 2013 -0400
+++ b/jdk/src/share/classes/java/security/cert/PKIXRevocationChecker.java Tue Oct 22 19:43:42 2013 -0400
@@ -299,7 +299,7 @@
/**
* Allow revocation check to succeed if the revocation status cannot be
* determined for one of the following reasons:
- * <p><ul>
+ * <ul>
* <li>The CRL or OCSP response cannot be obtained because of a
* network error.
* <li>The OCSP responder returns one of the following errors
--- a/jdk/src/share/classes/java/security/cert/PolicyQualifierInfo.java Tue Oct 22 19:37:11 2013 -0400
+++ b/jdk/src/share/classes/java/security/cert/PolicyQualifierInfo.java Tue Oct 22 19:43:42 2013 -0400
@@ -35,7 +35,7 @@
* structure.
*
* <p>The ASN.1 definition is as follows:
- * <p><pre>
+ * <pre>
* PolicyQualifierInfo ::= SEQUENCE {
* policyQualifierId PolicyQualifierId,
* qualifier ANY DEFINED BY policyQualifierId }
--- a/jdk/src/share/classes/java/security/cert/TrustAnchor.java Tue Oct 22 19:37:11 2013 -0400
+++ b/jdk/src/share/classes/java/security/cert/TrustAnchor.java Tue Oct 22 19:43:42 2013 -0400
@@ -44,7 +44,6 @@
* individual parameters.
* <p>
* <b>Concurrent Access</b>
- * <p>
* <p>All {@code TrustAnchor} objects must be immutable and
* thread-safe. That is, multiple threads may concurrently invoke the
* methods defined in this class on a single {@code TrustAnchor}
--- a/jdk/src/share/classes/java/security/cert/X509CertSelector.java Tue Oct 22 19:37:11 2013 -0400
+++ b/jdk/src/share/classes/java/security/cert/X509CertSelector.java Tue Oct 22 19:43:42 2013 -0400
@@ -359,7 +359,7 @@
* criticality setting, and encapsulating OCTET STRING)
* for a SubjectKeyIdentifier extension.
* The ASN.1 notation for this structure follows.
- * <p>
+ *
* <pre>{@code
* SubjectKeyIdentifier ::= KeyIdentifier
*
@@ -399,7 +399,7 @@
* criticality setting, and encapsulating OCTET STRING)
* for an AuthorityKeyIdentifier extension.
* The ASN.1 notation for this structure follows.
- * <p>
+ *
* <pre>{@code
* AuthorityKeyIdentifier ::= SEQUENCE {
* keyIdentifier [0] KeyIdentifier OPTIONAL,
--- a/jdk/src/share/classes/java/security/interfaces/DSAKeyPairGenerator.java Tue Oct 22 19:37:11 2013 -0400
+++ b/jdk/src/share/classes/java/security/interfaces/DSAKeyPairGenerator.java Tue Oct 22 19:43:42 2013 -0400
@@ -43,11 +43,11 @@
*
* <li>Get a key pair generator for the DSA algorithm by calling the
* KeyPairGenerator {@code getInstance} method with "DSA"
- * as its argument.<p>
+ * as its argument.
*
* <li>Initialize the generator by casting the result to a DSAKeyPairGenerator
* and calling one of the
- * {@code initialize} methods from this DSAKeyPairGenerator interface.<p>
+ * {@code initialize} methods from this DSAKeyPairGenerator interface.
*
* <li>Generate a key pair by calling the {@code generateKeyPair}
* method from the KeyPairGenerator class.
--- a/jdk/src/share/classes/java/text/MessageFormat.java Tue Oct 22 19:37:11 2013 -0400
+++ b/jdk/src/share/classes/java/text/MessageFormat.java Tue Oct 22 19:43:42 2013 -0400
@@ -125,7 +125,6 @@
* valid patterns, but <code>"ab {0'}' de"</code>, <code>"ab } de"</code>
* and <code>"''{''"</code> are not.
*
- * <p>
* <dl><dt><b>Warning:</b><dd>The rules for using quotes within message
* format patterns unfortunately have shown to be somewhat confusing.
* In particular, it isn't always obvious to localizers whether single
@@ -146,7 +145,7 @@
* table shows how the values map to {@code Format} instances. Combinations not
* shown in the table are illegal. A <i>SubformatPattern</i> must
* be a valid pattern string for the {@code Format} subclass used.
- * <p>
+ *
* <table border=1 summary="Shows how FormatType and FormatStyle values map to Format instances">
* <tr>
* <th id="ft" class="TableHeadingColor">FormatType
@@ -215,7 +214,6 @@
* <td headers="fs"><i>SubformatPattern</i>
* <td headers="sc">{@code new} {@link ChoiceFormat#ChoiceFormat(String) ChoiceFormat}{@code (subformatPattern)}
* </table>
- * <p>
*
* <h4>Usage Information</h4>
*
@@ -761,7 +759,7 @@
* as indicated by the first matching line of the following table. An
* argument is <i>unavailable</i> if <code>arguments</code> is
* <code>null</code> or has fewer than argumentIndex+1 elements.
- * <p>
+ *
* <table border=1 summary="Examples of subformat,argument,and formatted text">
* <tr>
* <th>Subformat
--- a/jdk/src/share/classes/java/text/Normalizer.java Tue Oct 22 19:37:11 2013 -0400
+++ b/jdk/src/share/classes/java/text/Normalizer.java Tue Oct 22 19:43:42 2013 -0400
@@ -53,12 +53,12 @@
* several different ways in Unicode. For example, take the character A-acute.
* In Unicode, this can be encoded as a single character (the "composed" form):
*
- * <p><pre>
+ * <pre>
* U+00C1 LATIN CAPITAL LETTER A WITH ACUTE</pre>
*
* or as two separate characters (the "decomposed" form):
*
- * <p><pre>
+ * <pre>
* U+0041 LATIN CAPITAL LETTER A
* U+0301 COMBINING ACUTE ACCENT</pre>
*
@@ -72,14 +72,14 @@
* <p>
* Similarly, the string "ffi" can be encoded as three separate letters:
*
- * <p><pre>
+ * <pre>
* U+0066 LATIN SMALL LETTER F
* U+0066 LATIN SMALL LETTER F
* U+0069 LATIN SMALL LETTER I</pre>
*
* or as the single character
*
- * <p><pre>
+ * <pre>
* U+FB03 LATIN SMALL LIGATURE FFI</pre>
*
* The ffi ligature is not a distinct semantic character, and strictly speaking
--- a/jdk/src/share/classes/java/text/SimpleDateFormat.java Tue Oct 22 19:37:11 2013 -0400
+++ b/jdk/src/share/classes/java/text/SimpleDateFormat.java Tue Oct 22 19:43:42 2013 -0400
@@ -356,7 +356,6 @@
* may be replaced with other, locale dependent, pattern letters.
* <code>SimpleDateFormat</code> does not deal with the localization of text
* other than the pattern letters; that's up to the client of the class.
- * <p>
*
* <h4>Examples</h4>
*
--- a/jdk/src/share/classes/java/time/Duration.java Tue Oct 22 19:37:11 2013 -0400
+++ b/jdk/src/share/classes/java/time/Duration.java Tue Oct 22 19:43:42 2013 -0400
@@ -141,7 +141,7 @@
/**
* The pattern for parsing.
*/
- private final static Pattern PATTERN =
+ private static final Pattern PATTERN =
Pattern.compile("([-+]?)P(?:([-+]?[0-9]+)D)?" +
"(T(?:([-+]?[0-9]+)H)?(?:([-+]?[0-9]+)M)?(?:([-+]?[0-9]+)(?:[.,]([0-9]{0,9}))?S)?)?",
Pattern.CASE_INSENSITIVE);
@@ -554,7 +554,7 @@
* the simple initialization in Duration.
*/
private static class DurationUnits {
- final static List<TemporalUnit> UNITS =
+ static final List<TemporalUnit> UNITS =
Collections.unmodifiableList(Arrays.<TemporalUnit>asList(SECONDS, NANOS));
}
--- a/jdk/src/share/classes/java/time/OffsetDateTime.java Tue Oct 22 19:37:11 2013 -0400
+++ b/jdk/src/share/classes/java/time/OffsetDateTime.java Tue Oct 22 19:43:42 2013 -0400
@@ -1903,9 +1903,9 @@
* <a href="../../serialized-form.html#java.time.Ser">dedicated serialized form</a>.
* @serialData
* <pre>
- * out.writeByte(10); // identifies a OffsetDateTime
- * out.writeObject(dateTime);
- * out.writeObject(offset);
+ * out.writeByte(10); // identifies an OffsetDateTime
+ * // the <a href="../../serialized-form.html#java.time.LocalDateTime">datetime</a> excluding the one byte header
+ * // the <a href="../../serialized-form.html#java.time.ZoneOffset">offset</a> excluding the one byte header
* </pre>
*
* @return the instance of {@code Ser}, not null
@@ -1924,13 +1924,13 @@
}
void writeExternal(ObjectOutput out) throws IOException {
- out.writeObject(dateTime);
- out.writeObject(offset);
+ dateTime.writeExternal(out);
+ offset.writeExternal(out);
}
static OffsetDateTime readExternal(ObjectInput in) throws IOException, ClassNotFoundException {
- LocalDateTime dateTime = (LocalDateTime) in.readObject();
- ZoneOffset offset = (ZoneOffset) in.readObject();
+ LocalDateTime dateTime = LocalDateTime.readExternal(in);
+ ZoneOffset offset = ZoneOffset.readExternal(in);
return OffsetDateTime.of(dateTime, offset);
}
--- a/jdk/src/share/classes/java/time/OffsetTime.java Tue Oct 22 19:37:11 2013 -0400
+++ b/jdk/src/share/classes/java/time/OffsetTime.java Tue Oct 22 19:43:42 2013 -0400
@@ -1374,9 +1374,9 @@
* <a href="../../serialized-form.html#java.time.Ser">dedicated serialized form</a>.
* @serialData
* <pre>
- * out.writeByte(9); // identifies a OffsetTime
- * out.writeObject(time);
- * out.writeObject(offset);
+ * out.writeByte(9); // identifies an OffsetTime
+ * // the <a href="../../serialized-form.html#java.time.LocalTime">time</a> excluding the one byte header
+ * // the <a href="../../serialized-form.html#java.time.ZoneOffset">offset</a> excluding the one byte header
* </pre>
*
* @return the instance of {@code Ser}, not null
@@ -1395,13 +1395,13 @@
}
void writeExternal(ObjectOutput out) throws IOException {
- out.writeObject(time);
- out.writeObject(offset);
+ time.writeExternal(out);
+ offset.writeExternal(out);
}
static OffsetTime readExternal(ObjectInput in) throws IOException, ClassNotFoundException {
- LocalTime time = (LocalTime) in.readObject();
- ZoneOffset offset = (ZoneOffset) in.readObject();
+ LocalTime time = LocalTime.readExternal(in);
+ ZoneOffset offset = ZoneOffset.readExternal(in);
return OffsetTime.of(time, offset);
}
--- a/jdk/src/share/classes/java/time/Period.java Tue Oct 22 19:37:11 2013 -0400
+++ b/jdk/src/share/classes/java/time/Period.java Tue Oct 22 19:43:42 2013 -0400
@@ -138,13 +138,13 @@
/**
* The pattern for parsing.
*/
- private final static Pattern PATTERN =
+ private static final Pattern PATTERN =
Pattern.compile("([-+]?)P(?:([-+]?[0-9]+)Y)?(?:([-+]?[0-9]+)M)?(?:([-+]?[0-9]+)W)?(?:([-+]?[0-9]+)D)?", Pattern.CASE_INSENSITIVE);
/**
* The set of supported units.
*/
- private final static List<TemporalUnit> SUPPORTED_UNITS =
+ private static final List<TemporalUnit> SUPPORTED_UNITS =
Collections.unmodifiableList(Arrays.<TemporalUnit>asList(YEARS, MONTHS, DAYS));
/**
--- a/jdk/src/share/classes/java/time/chrono/ChronoPeriodImpl.java Tue Oct 22 19:37:11 2013 -0400
+++ b/jdk/src/share/classes/java/time/chrono/ChronoPeriodImpl.java Tue Oct 22 19:43:42 2013 -0400
@@ -104,7 +104,7 @@
/**
* The set of supported units.
*/
- private final static List<TemporalUnit> SUPPORTED_UNITS =
+ private static final List<TemporalUnit> SUPPORTED_UNITS =
Collections.unmodifiableList(Arrays.<TemporalUnit>asList(YEARS, MONTHS, DAYS));
/**
--- a/jdk/src/share/classes/java/time/chrono/JapaneseDate.java Tue Oct 22 19:37:11 2013 -0400
+++ b/jdk/src/share/classes/java/time/chrono/JapaneseDate.java Tue Oct 22 19:43:42 2013 -0400
@@ -140,7 +140,7 @@
/**
* The first day supported by the JapaneseChronology is Meiji 6, January 1st.
*/
- final static LocalDate MEIJI_6_ISODATE = LocalDate.of(1873, 1, 1);
+ static final LocalDate MEIJI_6_ISODATE = LocalDate.of(1873, 1, 1);
//-----------------------------------------------------------------------
/**
--- a/jdk/src/share/classes/java/time/temporal/WeekFields.java Tue Oct 22 19:37:11 2013 -0400
+++ b/jdk/src/share/classes/java/time/temporal/WeekFields.java Tue Oct 22 19:43:42 2013 -0400
@@ -245,15 +245,15 @@
/**
* The field used to access the computed DayOfWeek.
*/
- private transient final TemporalField dayOfWeek = ComputedDayOfField.ofDayOfWeekField(this);
+ private final transient TemporalField dayOfWeek = ComputedDayOfField.ofDayOfWeekField(this);
/**
* The field used to access the computed WeekOfMonth.
*/
- private transient final TemporalField weekOfMonth = ComputedDayOfField.ofWeekOfMonthField(this);
+ private final transient TemporalField weekOfMonth = ComputedDayOfField.ofWeekOfMonthField(this);
/**
* The field used to access the computed WeekOfYear.
*/
- private transient final TemporalField weekOfYear = ComputedDayOfField.ofWeekOfYearField(this);
+ private final transient TemporalField weekOfYear = ComputedDayOfField.ofWeekOfYearField(this);
/**
* The field that represents the week-of-week-based-year.
* <p>
@@ -261,7 +261,7 @@
* <p>
* This unit is an immutable and thread-safe singleton.
*/
- private transient final TemporalField weekOfWeekBasedYear = ComputedDayOfField.ofWeekOfWeekBasedYearField(this);
+ private final transient TemporalField weekOfWeekBasedYear = ComputedDayOfField.ofWeekOfWeekBasedYearField(this);
/**
* The field that represents the week-based-year.
* <p>
@@ -269,7 +269,7 @@
* <p>
* This unit is an immutable and thread-safe singleton.
*/
- private transient final TemporalField weekBasedYear = ComputedDayOfField.ofWeekBasedYearField(this);
+ private final transient TemporalField weekBasedYear = ComputedDayOfField.ofWeekBasedYearField(this);
//-----------------------------------------------------------------------
/**
--- a/jdk/src/share/classes/java/time/zone/Ser.java Tue Oct 22 19:37:11 2013 -0400
+++ b/jdk/src/share/classes/java/time/zone/Ser.java Tue Oct 22 19:43:42 2013 -0400
@@ -171,9 +171,9 @@
* <li><a href="../../../serialized-form.html#java.time.zone.ZoneRules">ZoneRules</a>
* - {@code ZoneRules.of(standardTransitions, standardOffsets, savingsInstantTransitions, wallOffsets, lastRules);}
* <li><a href="../../../serialized-form.html#java.time.zone.ZoneOffsetTransition">ZoneOffsetTransition</a>
- * - {@code ;}
+ * - {@code ZoneOffsetTransition of(LocalDateTime.ofEpochSecond(epochSecond), offsetBefore, offsetAfter);}
* <li><a href="../../../serialized-form.html#java.time.zone.ZoneOffsetTransitionRule">ZoneOffsetTransitionRule</a>
- * - {@code ;}
+ * - {@code ZoneOffsetTransitionRule.of(month, dom, dow, time, timeEndOfDay, timeDefinition, standardOffset, offsetBefore, offsetAfter);}
* </ul>
* @param in the data to read, not null
*/
--- a/jdk/src/share/classes/java/time/zone/ZoneOffsetTransition.java Tue Oct 22 19:37:11 2013 -0400
+++ b/jdk/src/share/classes/java/time/zone/ZoneOffsetTransition.java Tue Oct 22 19:43:42 2013 -0400
@@ -191,7 +191,7 @@
* out.writeByte(2); // identifies a ZoneOffsetTransition
* out.writeEpochSec(toEpochSecond);
* out.writeOffset(offsetBefore);
- * out.writeOfset(offsetAfter);
+ * out.writeOffset(offsetAfter);
* }
* </pre>
* @return the replacing object, not null
--- a/jdk/src/share/classes/java/util/Base64.java Tue Oct 22 19:37:11 2013 -0400
+++ b/jdk/src/share/classes/java/util/Base64.java Tue Oct 22 19:43:42 2013 -0400
@@ -40,7 +40,6 @@
* <a href="http://www.ietf.org/rfc/rfc4648.txt">RFC 4648</a> and
* <a href="http://www.ietf.org/rfc/rfc2045.txt">RFC 2045</a>.
*
- * <p>
* <ul>
* <li><a name="basic"><b>Basic</b></a>
* <p> Uses "The Base64 Alphabet" as specified in Table 1 of
--- a/jdk/src/share/classes/java/util/BitSet.java Tue Oct 22 19:37:11 2013 -0400
+++ b/jdk/src/share/classes/java/util/BitSet.java Tue Oct 22 19:43:42 2013 -0400
@@ -1164,10 +1164,10 @@
* <p>Example:
* <pre>
* BitSet drPepper = new BitSet();</pre>
- * Now {@code drPepper.toString()} returns "{@code {}}".<p>
+ * Now {@code drPepper.toString()} returns "{@code {}}".
* <pre>
* drPepper.set(2);</pre>
- * Now {@code drPepper.toString()} returns "{@code {2}}".<p>
+ * Now {@code drPepper.toString()} returns "{@code {2}}".
* <pre>
* drPepper.set(4);
* drPepper.set(10);</pre>
--- a/jdk/src/share/classes/java/util/Deque.java Tue Oct 22 19:37:11 2013 -0400
+++ b/jdk/src/share/classes/java/util/Deque.java Tue Oct 22 19:43:42 2013 -0400
@@ -56,7 +56,6 @@
* <p>The twelve methods described above are summarized in the
* following table:
*
- * <p>
* <table BORDER CELLPADDING=3 CELLSPACING=1>
* <caption>Summary of Deque methods</caption>
* <tr>
@@ -100,7 +99,6 @@
* inherited from the {@code Queue} interface are precisely equivalent to
* {@code Deque} methods as indicated in the following table:
*
- * <p>
* <table BORDER CELLPADDING=3 CELLSPACING=1>
* <caption>Comparison of Queue and Deque methods</caption>
* <tr>
@@ -139,7 +137,6 @@
* beginning of the deque. Stack methods are precisely equivalent to
* {@code Deque} methods as indicated in the table below:
*
- * <p>
* <table BORDER CELLPADDING=3 CELLSPACING=1>
* <caption>Comparison of Stack and Deque methods</caption>
* <tr>
--- a/jdk/src/share/classes/java/util/DoubleSummaryStatistics.java Tue Oct 22 19:37:11 2013 -0400
+++ b/jdk/src/share/classes/java/util/DoubleSummaryStatistics.java Tue Oct 22 19:43:42 2013 -0400
@@ -127,7 +127,7 @@
* numerical sum compared to a simple summation of {@code double}
* values.
*
- * @apiNote Sorting values by increasing absolute magnitude tends to yield
+ * @apiNote Values sorted by increasing absolute magnitude tend to yield
* more accurate results.
*
* @return the sum of values, or zero if none
--- a/jdk/src/share/classes/java/util/Iterator.java Tue Oct 22 19:37:11 2013 -0400
+++ b/jdk/src/share/classes/java/util/Iterator.java Tue Oct 22 19:43:42 2013 -0400
@@ -94,10 +94,10 @@
}
/**
- * Performs the given action for each remaining element, in the order
- * elements occur when iterating, until all elements have been processed or
- * the action throws an exception. Errors or runtime exceptions thrown by
- * the action are relayed to the caller.
+ * Performs the given action for each remaining element until all elements
+ * have been processed or the action throws an exception. Actions are
+ * performed in the order of iteration, if that order is specified.
+ * Exceptions thrown by the action are relayed to the caller.
*
* @implSpec
* <p>The default implementation behaves as if:
--- a/jdk/src/share/classes/java/util/List.java Tue Oct 22 19:37:11 2013 -0400
+++ b/jdk/src/share/classes/java/util/List.java Tue Oct 22 19:43:42 2013 -0400
@@ -192,8 +192,9 @@
* The following code can be used to dump the list into a newly
* allocated array of <tt>String</tt>:
*
- * <pre>
- * String[] y = x.toArray(new String[0]);</pre>
+ * <pre>{@code
+ * String[] y = x.toArray(new String[0]);
+ * }</pre>
*
* Note that <tt>toArray(new Object[0])</tt> is identical in function to
* <tt>toArray()</tt>.
@@ -383,14 +384,13 @@
*
* @implSpec
* The default implementation is equivalent to, for this {@code list}:
- * <pre>
- * {@code
- * final ListIterator<E> li = list.listIterator();
- * while (li.hasNext()) {
- * li.set(operator.apply(li.next()));
- * }
- * }
- * </pre>
+ * <pre>{@code
+ * final ListIterator<E> li = list.listIterator();
+ * while (li.hasNext()) {
+ * li.set(operator.apply(li.next()));
+ * }
+ * }</pre>
+ *
* If the list's list-iterator does not support the {@code set} operation
* then an {@code UnsupportedOperationException} will be thrown when
* replacing the first element.
@@ -469,11 +469,11 @@
/**
* Returns the hash code value for this list. The hash code of a list
* is defined to be the result of the following calculation:
- * <pre>
- * int hashCode = 1;
- * for (E e : list)
- * hashCode = 31*hashCode + (e==null ? 0 : e.hashCode());
- * </pre>
+ * <pre>{@code
+ * int hashCode = 1;
+ * for (E e : list)
+ * hashCode = 31*hashCode + (e==null ? 0 : e.hashCode());
+ * }</pre>
* This ensures that <tt>list1.equals(list2)</tt> implies that
* <tt>list1.hashCode()==list2.hashCode()</tt> for any two lists,
* <tt>list1</tt> and <tt>list2</tt>, as required by the general
@@ -640,9 +640,9 @@
* a list can be used as a range operation by passing a subList view
* instead of a whole list. For example, the following idiom
* removes a range of elements from a list:
- * <pre>
+ * <pre>{@code
* list.subList(from, to).clear();
- * </pre>
+ * }</pre>
* Similar idioms may be constructed for <tt>indexOf</tt> and
* <tt>lastIndexOf</tt>, and all of the algorithms in the
* <tt>Collections</tt> class can be applied to a subList.<p>
--- a/jdk/src/share/classes/java/util/Locale.java Tue Oct 22 19:37:11 2013 -0400
+++ b/jdk/src/share/classes/java/util/Locale.java Tue Oct 22 19:43:42 2013 -0400
@@ -1248,7 +1248,7 @@
* Returns a string representation of this <code>Locale</code>
* object, consisting of language, country, variant, script,
* and extensions as below:
- * <p><blockquote>
+ * <blockquote>
* language + "_" + country + "_" + (variant + "_#" | "#") + script + "-" + extensions
* </blockquote>
*
@@ -2199,7 +2199,7 @@
* are exactly "ja", "JP", "JP" or "th", "TH", "TH" and script/extensions
* fields are empty, this method supplies <code>UNICODE_LOCALE_EXTENSION</code>
* "ca"/"japanese" (calendar type is "japanese") or "nu"/"thai" (number script
- * type is "thai"). See <a href="Locale.html#special_cases_constructor"/>Special Cases</a>
+ * type is "thai"). See <a href="Locale.html#special_cases_constructor">Special Cases</a>
* for more information.
*
* @return an instance of <code>Locale</code> equivalent to
--- a/jdk/src/share/classes/java/util/Map.java Tue Oct 22 19:37:11 2013 -0400
+++ b/jdk/src/share/classes/java/util/Map.java Tue Oct 22 19:43:42 2013 -0400
@@ -562,9 +562,8 @@
// Defaultable methods
/**
- * Returns the value to which the specified key is mapped,
- * or {@code defaultValue} if this map contains no mapping
- * for the key.
+ * Returns the value to which the specified key is mapped, or
+ * {@code defaultValue} if this map contains no mapping for the key.
*
* <p>The default implementation makes no guarantees about synchronization
* or atomicity properties of this method. Any implementation providing
@@ -591,9 +590,10 @@
}
/**
- * Performs the given action on each entry in this map, in the order entries
- * are returned by an entry set iterator (which may be unspecified), until
- * all entries have been processed or the action throws an {@code Exception}.
+ * Performs the given action for each entry in this map until all entries
+ * have been processed or the action throws an exception. Unless
+ * otherwise specified by the implementing class, actions are performed in
+ * the order of entry set iteration (if an iteration order is specified.)
* Exceptions thrown by the action are relayed to the caller.
*
* <p>The default implementation should be overridden by implementations if
@@ -636,9 +636,9 @@
/**
* Replaces each entry's value with the result of invoking the given
- * function on that entry, in the order entries are returned by an entry
- * set iterator, until all entries have been processed or the function
- * throws an exception.
+ * function on that entry until all entries have been processed or the
+ * function throws an exception. Exceptions thrown by the function are
+ * relayed to the caller.
*
* <p>The default implementation makes no guarantees about synchronization
* or atomicity properties of this method. Any implementation providing
--- a/jdk/src/share/classes/java/util/PrimitiveIterator.java Tue Oct 22 19:37:11 2013 -0400
+++ b/jdk/src/share/classes/java/util/PrimitiveIterator.java Tue Oct 22 19:43:42 2013 -0400
@@ -76,6 +76,7 @@
* @param action The action to be performed for each element
* @throws NullPointerException if the specified action is null
*/
+ @SuppressWarnings("overloads")
void forEachRemaining(T_CONS action);
/**
@@ -93,10 +94,10 @@
int nextInt();
/**
- * Performs the given action for each remaining element, in the order
- * elements occur when iterating, until all elements have been processed
- * or the action throws an exception. Errors or runtime exceptions
- * thrown by the action are relayed to the caller.
+ * Performs the given action for each remaining element until all elements
+ * have been processed or the action throws an exception. Actions are
+ * performed in the order of iteration, if that order is specified.
+ * Exceptions thrown by the action are relayed to the caller.
*
* @implSpec
* <p>The default implementation behaves as if:
@@ -167,10 +168,10 @@
long nextLong();
/**
- * Performs the given action for each remaining element, in the order
- * elements occur when iterating, until all elements have been processed
- * or the action throws an exception. Errors or runtime exceptions
- * thrown by the action are relayed to the caller.
+ * Performs the given action for each remaining element until all elements
+ * have been processed or the action throws an exception. Actions are
+ * performed in the order of iteration, if that order is specified.
+ * Exceptions thrown by the action are relayed to the caller.
*
* @implSpec
* <p>The default implementation behaves as if:
@@ -240,10 +241,10 @@
double nextDouble();
/**
- * Performs the given action for each remaining element, in the order
- * elements occur when iterating, until all elements have been processed
- * or the action throws an exception. Errors or runtime exceptions
- * thrown by the action are relayed to the caller.
+ * Performs the given action for each remaining element until all elements
+ * have been processed or the action throws an exception. Actions are
+ * performed in the order of iteration, if that order is specified.
+ * Exceptions thrown by the action are relayed to the caller.
*
* @implSpec
* <p>The default implementation behaves as if:
--- a/jdk/src/share/classes/java/util/Properties.java Tue Oct 22 19:37:11 2013 -0400
+++ b/jdk/src/share/classes/java/util/Properties.java Tue Oct 22 19:43:42 2013 -0400
@@ -244,7 +244,6 @@
* As an example, each of the following three lines specifies the key
* {@code "Truth"} and the associated element value
* {@code "Beauty"}:
- * <p>
* <pre>
* Truth = Beauty
* Truth:Beauty
@@ -252,14 +251,12 @@
* </pre>
* As another example, the following three lines specify a single
* property:
- * <p>
* <pre>
* fruits apple, banana, pear, \
* cantaloupe, watermelon, \
* kiwi, mango
* </pre>
* The key is {@code "fruits"} and the associated element is:
- * <p>
* <pre>"apple, banana, pear, cantaloupe, watermelon, kiwi, mango"</pre>
* Note that a space appears before each {@code \} so that a space
* will appear after each comma in the final result; the {@code \},
@@ -268,13 +265,11 @@
* characters.
* <p>
* As a third example, the line:
- * <p>
* <pre>cheeses
* </pre>
* specifies that the key is {@code "cheeses"} and the associated
- * element is the empty string {@code ""}.<p>
+ * element is the empty string {@code ""}.
* <p>
- *
* <a name="unicodeescapes"></a>
* Characters in keys and elements can be represented in escape
* sequences similar to those used for character and string literals
--- a/jdk/src/share/classes/java/util/PropertyPermission.java Tue Oct 22 19:37:11 2013 -0400
+++ b/jdk/src/share/classes/java/util/PropertyPermission.java Tue Oct 22 19:43:42 2013 -0400
@@ -51,11 +51,10 @@
* signify a wildcard match. For example: "java.*" and "*" signify a wildcard
* match, while "*java" and "a*b" do not.
* <P>
- * <P>
* The actions to be granted are passed to the constructor in a string containing
* a list of one or more comma-separated keywords. The possible keywords are
* "read" and "write". Their meaning is defined as follows:
- * <P>
+ *
* <DL>
* <DT> read
* <DD> read permission. Allows <code>System.getProperty</code> to
@@ -166,11 +165,11 @@
* Checks if this PropertyPermission object "implies" the specified
* permission.
* <P>
- * More specifically, this method returns true if:<p>
+ * More specifically, this method returns true if:
* <ul>
- * <li> <i>p</i> is an instanceof PropertyPermission,<p>
+ * <li> <i>p</i> is an instanceof PropertyPermission,
* <li> <i>p</i>'s actions are a subset of this
- * object's actions, and <p>
+ * object's actions, and
* <li> <i>p</i>'s name is implied by this object's
* name. For example, "java.*" implies "java.home".
* </ul>
--- a/jdk/src/share/classes/java/util/Queue.java Tue Oct 22 19:37:11 2013 -0400
+++ b/jdk/src/share/classes/java/util/Queue.java Tue Oct 22 19:43:42 2013 -0400
@@ -47,7 +47,6 @@
* implementations; in most implementations, insert operations cannot
* fail.
*
- * <p>
* <table BORDER CELLPADDING=3 CELLSPACING=1>
* <caption>Summary of Queue methods</caption>
* <tr>
--- a/jdk/src/share/classes/java/util/ResourceBundle.java Tue Oct 22 19:37:11 2013 -0400
+++ b/jdk/src/share/classes/java/util/ResourceBundle.java Tue Oct 22 19:43:42 2013 -0400
@@ -1084,7 +1084,6 @@
* bundles. Conceptually, the bundle loading process with the given
* <code>control</code> is performed in the following steps.
*
- * <p>
* <ol>
* <li>This factory method looks up the resource bundle in the cache for
* the specified <code>baseName</code>, <code>targetLocale</code> and
--- a/jdk/src/share/classes/java/util/Scanner.java Tue Oct 22 19:37:11 2013 -0400
+++ b/jdk/src/share/classes/java/util/Scanner.java Tue Oct 22 19:43:42 2013 -0400
@@ -216,7 +216,6 @@
* are specified in terms of the following regular-expression grammar, where
* Rmax is the highest digit in the radix being used (for example, Rmax is 9 in base 10).
*
- * <p>
* <dl>
* <dt><i>NonAsciiDigit</i>:
* <dd>A non-ASCII character c for which
--- a/jdk/src/share/classes/java/util/Spliterator.java Tue Oct 22 19:37:11 2013 -0400
+++ b/jdk/src/share/classes/java/util/Spliterator.java Tue Oct 22 19:43:42 2013 -0400
@@ -613,6 +613,7 @@
* upon entry to this method, else {@code true}.
* @throws NullPointerException if the specified action is null
*/
+ @SuppressWarnings("overloads")
boolean tryAdvance(T_CONS action);
/**
@@ -630,6 +631,7 @@
* @param action The action
* @throws NullPointerException if the specified action is null
*/
+ @SuppressWarnings("overloads")
default void forEachRemaining(T_CONS action) {
do { } while (tryAdvance(action));
}
--- a/jdk/src/share/classes/java/util/TimeZone.java Tue Oct 22 19:37:11 2013 -0400
+++ b/jdk/src/share/classes/java/util/TimeZone.java Tue Oct 22 19:43:42 2013 -0400
@@ -606,7 +606,7 @@
* Otherwise, the method takes the following steps to determine the default
* time zone.
*
- * <p><ul>
+ * <ul>
* <li>Use the {@code user.timezone} property value as the default
* time zone ID if it's available.</li>
* <li>Detect the platform time zone ID. The source of the
--- a/jdk/src/share/classes/java/util/UUID.java Tue Oct 22 19:37:11 2013 -0400
+++ b/jdk/src/share/classes/java/util/UUID.java Tue Oct 22 19:43:42 2013 -0400
@@ -233,7 +233,7 @@
* number describes how this {@code UUID} was generated.
*
* The version number has the following meaning:
- * <p><ul>
+ * <ul>
* <li>1 Time-based UUID
* <li>2 DCE security UUID
* <li>3 Name-based UUID
@@ -252,7 +252,7 @@
* number describes the layout of the {@code UUID}.
*
* The variant number has the following meaning:
- * <p><ul>
+ * <ul>
* <li>0 Reserved for NCS backward compatibility
* <li>2 <a href="http://www.ietf.org/rfc/rfc4122.txt">IETF RFC 4122</a>
* (Leach-Salz), used by this class
--- a/jdk/src/share/classes/java/util/concurrent/BlockingDeque.java Tue Oct 22 19:37:11 2013 -0400
+++ b/jdk/src/share/classes/java/util/concurrent/BlockingDeque.java Tue Oct 22 19:43:42 2013 -0400
@@ -50,7 +50,6 @@
* and the fourth blocks for only a given maximum time limit before giving
* up. These methods are summarized in the following table:
*
- * <p>
* <table BORDER CELLPADDING=3 CELLSPACING=1>
* <caption>Summary of BlockingDeque methods</caption>
* <tr>
@@ -126,7 +125,6 @@
* {@code BlockingQueue} interface are precisely equivalent to
* {@code BlockingDeque} methods as indicated in the following table:
*
- * <p>
* <table BORDER CELLPADDING=3 CELLSPACING=1>
* <caption>Comparison of BlockingQueue and BlockingDeque methods</caption>
* <tr>
--- a/jdk/src/share/classes/java/util/concurrent/BlockingQueue.java Tue Oct 22 19:37:11 2013 -0400
+++ b/jdk/src/share/classes/java/util/concurrent/BlockingQueue.java Tue Oct 22 19:43:42 2013 -0400
@@ -53,7 +53,6 @@
* and the fourth blocks for only a given maximum time limit before giving
* up. These methods are summarized in the following table:
*
- * <p>
* <table BORDER CELLPADDING=3 CELLSPACING=1>
* <caption>Summary of BlockingQueue methods</caption>
* <tr>
--- a/jdk/src/share/classes/java/util/concurrent/Future.java Tue Oct 22 19:37:11 2013 -0400
+++ b/jdk/src/share/classes/java/util/concurrent/Future.java Tue Oct 22 19:43:42 2013 -0400
@@ -52,8 +52,8 @@
*
* <p>
* <b>Sample Usage</b> (Note that the following classes are all
- * made-up.) <p>
- * <pre> {@code
+ * made-up.)
+ * <pre> {@code
* interface ArchiveSearcher { String search(String target); }
* class App {
* ExecutorService executor = ...
--- a/jdk/src/share/classes/java/util/concurrent/locks/ReentrantReadWriteLock.java Tue Oct 22 19:37:11 2013 -0400
+++ b/jdk/src/share/classes/java/util/concurrent/locks/ReentrantReadWriteLock.java Tue Oct 22 19:43:42 2013 -0400
@@ -56,7 +56,6 @@
* constraints. A nonfair lock that is continuously contended may
* indefinitely postpone one or more reader or writer threads, but
* will normally have higher throughput than a fair lock.
- * <p>
*
* <dt><b><i>Fair mode</i></b>
* <dd>When constructed as fair, threads contend for entry using an
--- a/jdk/src/share/classes/java/util/function/package-info.java Tue Oct 22 19:37:11 2013 -0400
+++ b/jdk/src/share/classes/java/util/function/package-info.java Tue Oct 22 19:43:42 2013 -0400
@@ -60,7 +60,11 @@
* actions, or predicates. In documenting functional interfaces, or referring
* to variables typed as functional interfaces, it is common to refer directly
* to those abstract concepts, for example using "this function" instead of
- * "the function represented by this object".
+ * "the function represented by this object". When an API method is said to
+ * accept or return a functional interface in this manner, such as "applies the
+ * provided function to...", this is understood to mean a <i>non-null</i>
+ * reference to an object implementing the appropriate functional interface,
+ * unless potential nullity is explicitly specified.
*
* <p>The functional interfaces in this package follow an extensible naming
* convention, as follows:
--- a/jdk/src/share/classes/java/util/jar/Pack200.java Tue Oct 22 19:37:11 2013 -0400
+++ b/jdk/src/share/classes/java/util/jar/Pack200.java Tue Oct 22 19:43:42 2013 -0400
@@ -44,7 +44,7 @@
* The unpacker engine is used by deployment applications to
* transform the byte-stream back to JAR format.
* <p>
- * Here is an example using packer and unpacker:<p>
+ * Here is an example using packer and unpacker:
* <pre>{@code
* import java.util.jar.Pack200;
* import java.util.jar.Pack200.*;
--- a/jdk/src/share/classes/java/util/logging/Logger.java Tue Oct 22 19:37:11 2013 -0400
+++ b/jdk/src/share/classes/java/util/logging/Logger.java Tue Oct 22 19:43:42 2013 -0400
@@ -150,7 +150,7 @@
* has or inherited a resource bundle name, then that resource bundle name
* will be mapped to a {@code ResourceBundle} object, using the default Locale
* at the time of logging.
- * <br><a name="ResourceBundleMapping"/>When mapping resource bundle names to
+ * <br id="ResourceBundleMapping">When mapping resource bundle names to
* {@code ResourceBundle} objects, the logger will first try to use the
* Thread's {@linkplain java.lang.Thread#getContextClassLoader() context class
* loader} to map the given resource bundle name to a {@code ResourceBundle}.
--- a/jdk/src/share/classes/java/util/regex/Pattern.java Tue Oct 22 19:37:11 2013 -0400
+++ b/jdk/src/share/classes/java/util/regex/Pattern.java Tue Oct 22 19:43:42 2013 -0400
@@ -618,7 +618,7 @@
* are in conformance with the recommendation of <i>Annex C: Compatibility Properties</i>
* of <a href="http://www.unicode.org/reports/tr18/"><i>Unicode Regular Expression
* </i></a>, when {@link #UNICODE_CHARACTER_CLASS} flag is specified.
- * <p>
+ *
* <table border="0" cellpadding="1" cellspacing="0"
* summary="predefined and posix character classes in Unicode mode">
* <tr align="left">
--- a/jdk/src/share/classes/java/util/spi/LocaleServiceProvider.java Tue Oct 22 19:37:11 2013 -0400
+++ b/jdk/src/share/classes/java/util/spi/LocaleServiceProvider.java Tue Oct 22 19:43:42 2013 -0400
@@ -41,7 +41,7 @@
* <code>java.util</code> packages use implementations of the provider
* interfaces to offer support for locales beyond the set of locales
* supported by the Java runtime environment itself.
- * <p>
+ *
* <h3>Packaging of Locale Sensitive Service Provider Implementations</h3>
* Implementations of these locale sensitive services are packaged using the
* <a href="../../../../technotes/guides/extensions/index.html">Java Extension Mechanism</a>
--- a/jdk/src/share/classes/java/util/stream/BaseStream.java Tue Oct 22 19:37:11 2013 -0400
+++ b/jdk/src/share/classes/java/util/stream/BaseStream.java Tue Oct 22 19:43:42 2013 -0400
@@ -35,9 +35,10 @@
import java.util.function.Predicate;
/**
- * A sequence of elements supporting sequential and parallel aggregate
- * operations. The following example illustrates an aggregate operation using
- * {@link Stream} and {@link IntStream}:
+ * Base interface for streams, which are sequences of elements supporting
+ * sequential and parallel aggregate operations. The following example
+ * illustrates an aggregate operation using the stream types {@link Stream}
+ * and {@link IntStream}, computing the sum of the weights of the red widgets:
*
* <pre>{@code
* int sum = widgets.stream()
@@ -46,80 +47,18 @@
* .sum();
* }</pre>
*
- * In this example, {@code widgets} is a {@code Collection<Widget>}. We create
- * a stream of {@code Widget} objects via {@link Collection#stream Collection.stream()},
- * filter it to produce a stream containing only the red widgets, and then
- * transform it into a stream of {@code int} values representing the weight of
- * each red widget. Then this stream is summed to produce a total weight.
- *
- * <p>To perform a computation, stream
- * <a href="package-summary.html#StreamOps">operations</a> are composed into a
- * <em>stream pipeline</em>. A stream pipeline consists of a source (which
- * might be an array, a collection, a generator function, an IO channel,
- * etc), zero or more <em>intermediate operations</em> (which transform a
- * stream into another stream, such as {@link Stream#filter(Predicate)}), and a
- * <em>terminal operation</em> (which produces a result or side-effect, such
- * as {@link IntStream#sum()} or {@link IntStream#forEach(IntConsumer)}).
- * Streams are lazy; computation on the source data is only performed when the
- * terminal operation is initiated, and source elements are consumed only
- * as needed.
- *
- * <p>Collections and streams, while bearing some superficial similarities,
- * have different goals. Collections are primarily concerned with the efficient
- * management of, and access to, their elements. By contrast, streams do not
- * provide a means to directly access or manipulate their elements, and are
- * instead concerned with declaratively describing their source and the
- * computational operations which will be performed in aggregate on that source.
- * However, if the provided stream operations do not offer the desired
- * functionality, the {@link #iterator()} and {@link #spliterator()} operations
- * can be used to perform a controlled traversal.
- *
- * <p>A stream pipeline, like the "widgets" example above, can be viewed as
- * a <em>query</em> on the stream source. Unless the source was explicitly
- * designed for concurrent modification (such as a {@link ConcurrentHashMap}),
- * unpredictable or erroneous behavior may result from modifying the stream
- * source while it is being queried.
- *
- * <p>Most stream operations accept parameters that describe user-specified
- * behavior, such as the lambda expression {@code w -> w.getWeight()} passed to
- * {@code mapToInt} in the example above. Such parameters are always instances
- * of a <a href="../function/package-summary.html">functional interface</a> such
- * as {@link java.util.function.Function}, and are often lambda expressions or
- * method references. These parameters can never be null, should not modify the
- * stream source, and should be
- * <a href="package-summary.html#NonInterference">effectively stateless</a>
- * (their result should not depend on any state that might change during
- * execution of the stream pipeline.)
- *
- * <p>A stream should be operated on (invoking an intermediate or terminal stream
- * operation) only once. This rules out, for example, "forked" streams, where
- * the same source feeds two or more pipelines, or multiple traversals of the
- * same stream. A stream implementation may throw {@link IllegalStateException}
- * if it detects that the stream is being reused. However, since some stream
- * operations may return their receiver rather than a new stream object, it may
- * not be possible to detect reuse in all cases.
- *
- * <p>Streams have a {@link #close()} method and implement {@link AutoCloseable},
- * but nearly all stream instances do not actually need to be closed after use.
- * Generally, only streams whose source is an IO channel (such as those returned
- * by {@link Files#lines(Path, Charset)}) will require closing. Most streams
- * are backed by collections, arrays, or generating functions, which require no
- * special resource management. (If a stream does require closing, it can be
- * declared as a resource in a {@code try}-with-resources statement.)
- *
- * <p>Stream pipelines may execute either sequentially or in
- * <a href="package-summary.html#Parallelism">parallel</a>. This
- * execution mode is a property of the stream. Streams are created
- * with an initial choice of sequential or parallel execution. (For example,
- * {@link Collection#stream() Collection.stream()} creates a sequential stream,
- * and {@link Collection#parallelStream() Collection.parallelStream()} creates
- * a parallel one.) This choice of execution mode may be modified by the
- * {@link #sequential()} or {@link #parallel()} methods, and may be queried with
- * the {@link #isParallel()} method.
+ * See the class documentation for {@link Stream} and the package documentation
+ * for <a href="package-summary.html">java.util.stream</a> for additional
+ * specification of streams, stream operations, stream pipelines, and
+ * parallelism, which governs the behavior of all stream types.
*
* @param <T> the type of the stream elements
* @param <S> the type of of the stream implementing {@code BaseStream}
* @since 1.8
+ * @see Stream
+ * @see IntStream
+ * @see LongStream
+ * @see DoubleStream
* @see <a href="package-summary.html">java.util.stream</a>
*/
public interface BaseStream<T, S extends BaseStream<T, S>>
--- a/jdk/src/share/classes/java/util/stream/Collectors.java Tue Oct 22 19:37:11 2013 -0400
+++ b/jdk/src/share/classes/java/util/stream/Collectors.java Tue Oct 22 19:43:42 2013 -0400
@@ -462,7 +462,7 @@
*/
public static <T> Collector<T, ?, Integer>
summingInt(ToIntFunction<? super T> mapper) {
- return new CollectorImpl<T, int[], Integer>(
+ return new CollectorImpl<>(
() -> new int[1],
(a, t) -> { a[0] += mapper.applyAsInt(t); },
(a, b) -> { a[0] += b[0]; return a; },
@@ -480,7 +480,7 @@
*/
public static <T> Collector<T, ?, Long>
summingLong(ToLongFunction<? super T> mapper) {
- return new CollectorImpl<T, long[], Long>(
+ return new CollectorImpl<>(
() -> new long[1],
(a, t) -> { a[0] += mapper.applyAsLong(t); },
(a, b) -> { a[0] += b[0]; return a; },
@@ -505,7 +505,7 @@
*/
public static <T> Collector<T, ?, Double>
summingDouble(ToDoubleFunction<? super T> mapper) {
- return new CollectorImpl<T, double[], Double>(
+ return new CollectorImpl<>(
() -> new double[1],
(a, t) -> { a[0] += mapper.applyAsDouble(t); },
(a, b) -> { a[0] += b[0]; return a; },
@@ -523,7 +523,7 @@
*/
public static <T> Collector<T, ?, Double>
averagingInt(ToIntFunction<? super T> mapper) {
- return new CollectorImpl<T, long[], Double>(
+ return new CollectorImpl<>(
() -> new long[2],
(a, t) -> { a[0] += mapper.applyAsInt(t); a[1]++; },
(a, b) -> { a[0] += b[0]; a[1] += b[1]; return a; },
@@ -541,7 +541,7 @@
*/
public static <T> Collector<T, ?, Double>
averagingLong(ToLongFunction<? super T> mapper) {
- return new CollectorImpl<T, long[], Double>(
+ return new CollectorImpl<>(
() -> new long[2],
(a, t) -> { a[0] += mapper.applyAsLong(t); a[1]++; },
(a, b) -> { a[0] += b[0]; a[1] += b[1]; return a; },
@@ -566,7 +566,7 @@
*/
public static <T> Collector<T, ?, Double>
averagingDouble(ToDoubleFunction<? super T> mapper) {
- return new CollectorImpl<T, double[], Double>(
+ return new CollectorImpl<>(
() -> new double[2],
(a, t) -> { a[0] += mapper.applyAsDouble(t); a[1]++; },
(a, b) -> { a[0] += b[0]; a[1] += b[1]; return a; },
@@ -723,6 +723,14 @@
* groupingBy(classifier, toList());
* }</pre>
*
+ * @implNote
+ * The returned {@code Collector} is not concurrent. For parallel stream
+ * pipelines, the {@code combiner} function operates by merging the keys
+ * from one map into another, which can be an expensive operation. If
+ * preservation of the order in which elements appear in the resulting {@code Map}
+ * collector is not required, using {@link #groupingByConcurrent(Function)}
+ * may offer better parallel performance.
+ *
* @param <T> the type of the input elements
* @param <K> the type of the keys
* @param classifier the classifier function mapping input elements to keys
@@ -759,6 +767,14 @@
* mapping(Person::getLastName, toSet())));
* }</pre>
*
+ * @implNote
+ * The returned {@code Collector} is not concurrent. For parallel stream
+ * pipelines, the {@code combiner} function operates by merging the keys
+ * from one map into another, which can be an expensive operation. If
+ * preservation of the order in which elements are presented to the downstream
+ * collector is not required, using {@link #groupingByConcurrent(Function, Collector)}
+ * may offer better parallel performance.
+ *
* @param <T> the type of the input elements
* @param <K> the type of the keys
* @param <A> the intermediate accumulation type of the downstream collector
@@ -798,6 +814,14 @@
* mapping(Person::getLastName, toSet())));
* }</pre>
*
+ * @implNote
+ * The returned {@code Collector} is not concurrent. For parallel stream
+ * pipelines, the {@code combiner} function operates by merging the keys
+ * from one map into another, which can be an expensive operation. If
+ * preservation of the order in which elements are presented to the downstream
+ * collector is not required, using {@link #groupingByConcurrent(Function, Supplier, Collector)}
+ * may offer better parallel performance.
+ *
* @param <T> the type of the input elements
* @param <K> the type of the keys
* @param <A> the intermediate accumulation type of the downstream collector
@@ -871,7 +895,7 @@
* @param <T> the type of the input elements
* @param <K> the type of the keys
* @param classifier a classifier function mapping input elements to keys
- * @return a {@code Collector} implementing the group-by operation
+ * @return a concurrent, unordered {@code Collector} implementing the group-by operation
*
* @see #groupingBy(Function)
* @see #groupingByConcurrent(Function, Collector)
@@ -912,7 +936,7 @@
* @param <D> the result type of the downstream reduction
* @param classifier a classifier function mapping input elements to keys
* @param downstream a {@code Collector} implementing the downstream reduction
- * @return a {@code Collector} implementing the cascaded group-by operation
+ * @return a concurrent, unordered {@code Collector} implementing the cascaded group-by operation
*
* @see #groupingBy(Function, Collector)
* @see #groupingByConcurrent(Function)
@@ -958,7 +982,7 @@
* @param downstream a {@code Collector} implementing the downstream reduction
* @param mapFactory a function which, when called, produces a new empty
* {@code ConcurrentMap} of the desired type
- * @return a {@code Collector} implementing the cascaded group-by operation
+ * @return a concurrent, unordered {@code Collector} implementing the cascaded group-by operation
*
* @see #groupingByConcurrent(Function)
* @see #groupingByConcurrent(Function, Collector)
@@ -1072,7 +1096,7 @@
}
/**
- * Returns a {@code Collector} that accumulate elements into a
+ * Returns a {@code Collector} that accumulates elements into a
* {@code Map} whose keys and values are the result of applying the provided
* mapping functions to the input elements.
*
@@ -1101,6 +1125,14 @@
* Functions.identity());
* }</pre>
*
+ * @implNote
+ * The returned {@code Collector} is not concurrent. For parallel stream
+ * pipelines, the {@code combiner} function operates by merging the keys
+ * from one map into another, which can be an expensive operation. If it is
+ * not required that results are inserted into the {@code Map} in encounter
+ * order, using {@link #toConcurrentMap(Function, Function)}
+ * may offer better parallel performance.
+ *
* @param <T> the type of the input elements
* @param <K> the output type of the key mapping function
* @param <U> the output type of the value mapping function
@@ -1121,7 +1153,7 @@
}
/**
- * Returns a {@code Collector} that accumulate elements into a
+ * Returns a {@code Collector} that accumulates elements into a
* {@code Map} whose keys and values are the result of applying the provided
* mapping functions to the input elements.
*
@@ -1146,6 +1178,14 @@
* (s, a) -> s + ", " + a));
* }</pre>
*
+ * @implNote
+ * The returned {@code Collector} is not concurrent. For parallel stream
+ * pipelines, the {@code combiner} function operates by merging the keys
+ * from one map into another, which can be an expensive operation. If it is
+ * not required that results are merged into the {@code Map} in encounter
+ * order, using {@link #toConcurrentMap(Function, Function, BinaryOperator)}
+ * may offer better parallel performance.
+ *
* @param <T> the type of the input elements
* @param <K> the output type of the key mapping function
* @param <U> the output type of the value mapping function
@@ -1172,7 +1212,7 @@
}
/**
- * Returns a {@code Collector} that accumulate elements into a
+ * Returns a {@code Collector} that accumulates elements into a
* {@code Map} whose keys and values are the result of applying the provided
* mapping functions to the input elements.
*
@@ -1182,6 +1222,14 @@
* results are merged using the provided merging function. The {@code Map}
* is created by a provided supplier function.
*
+ * @implNote
+ * The returned {@code Collector} is not concurrent. For parallel stream
+ * pipelines, the {@code combiner} function operates by merging the keys
+ * from one map into another, which can be an expensive operation. If it is
+ * not required that results are merged into the {@code Map} in encounter
+ * order, using {@link #toConcurrentMap(Function, Function, BinaryOperator, Supplier)}
+ * may offer better parallel performance.
+ *
* @param <T> the type of the input elements
* @param <K> the output type of the key mapping function
* @param <U> the output type of the value mapping function
@@ -1215,7 +1263,7 @@
}
/**
- * Returns a {@code Collector} that accumulate elements into a
+ * Returns a concurrent {@code Collector} that accumulates elements into a
* {@code ConcurrentMap} whose keys and values are the result of applying
* the provided mapping functions to the input elements.
*
@@ -1252,7 +1300,7 @@
* @param <U> the output type of the value mapping function
* @param keyMapper the mapping function to produce keys
* @param valueMapper the mapping function to produce values
- * @return a concurrent {@code Collector} which collects elements into a
+ * @return a concurrent, unordered {@code Collector} which collects elements into a
* {@code ConcurrentMap} whose keys are the result of applying a key mapping
* function to the input elements, and whose values are the result of
* applying a value mapping function to the input elements
@@ -1268,7 +1316,7 @@
}
/**
- * Returns a {@code Collector} that accumulate elements into a
+ * Returns a concurrent {@code Collector} that accumulates elements into a
* {@code ConcurrentMap} whose keys and values are the result of applying
* the provided mapping functions to the input elements.
*
@@ -1303,7 +1351,7 @@
* @param mergeFunction a merge function, used to resolve collisions between
* values associated with the same key, as supplied
* to {@link Map#merge(Object, Object, BiFunction)}
- * @return a concurrent {@code Collector} which collects elements into a
+ * @return a concurrent, unordered {@code Collector} which collects elements into a
* {@code ConcurrentMap} whose keys are the result of applying a key mapping
* function to the input elements, and whose values are the result of
* applying a value mapping function to all input elements equal to the key
@@ -1322,7 +1370,7 @@
}
/**
- * Returns a {@code Collector} that accumulate elements into a
+ * Returns a concurrent {@code Collector} that accumulates elements into a
* {@code ConcurrentMap} whose keys and values are the result of applying
* the provided mapping functions to the input elements.
*
@@ -1345,7 +1393,7 @@
* to {@link Map#merge(Object, Object, BiFunction)}
* @param mapSupplier a function which returns a new, empty {@code Map} into
* which the results will be inserted
- * @return a concurrent {@code Collector} which collects elements into a
+ * @return a concurrent, unordered {@code Collector} which collects elements into a
* {@code ConcurrentMap} whose keys are the result of applying a key mapping
* function to the input elements, and whose values are the result of
* applying a value mapping function to all input elements equal to the key
--- a/jdk/src/share/classes/java/util/stream/DoubleStream.java Tue Oct 22 19:37:11 2013 -0400
+++ b/jdk/src/share/classes/java/util/stream/DoubleStream.java Tue Oct 22 19:43:42 2013 -0400
@@ -50,9 +50,13 @@
import java.util.function.Supplier;
/**
- * A sequence of elements supporting sequential and parallel aggregate
- * operations. The following example illustrates an aggregate operation using
- * {@link Stream} and {@link DoubleStream}:
+ * A sequence of primitive double-valued elements supporting sequential and parallel
+ * aggregate operations. This is the {@code double} primitive specialization of
+ * {@link Stream}.
+ *
+ * <p>The following example illustrates an aggregate operation using
+ * {@link Stream} and {@link DoubleStream}, computing the sum of the weights of the
+ * red widgets:
*
* <pre>{@code
* double sum = widgets.stream()
@@ -61,78 +65,13 @@
* .sum();
* }</pre>
*
- * In this example, {@code widgets} is a {@code Collection<Widget>}. We create
- * a stream of {@code Widget} objects via {@link Collection#stream Collection.stream()},
- * filter it to produce a stream containing only the red widgets, and then
- * transform it into a stream of {@code double} values representing the weight of
- * each red widget. Then this stream is summed to produce a total weight.
- *
- * <p>To perform a computation, stream
- * <a href="package-summary.html#StreamOps">operations</a> are composed into a
- * <em>stream pipeline</em>. A stream pipeline consists of a source (which
- * might be an array, a collection, a generator function, an IO channel,
- * etc), zero or more <em>intermediate operations</em> (which transform a
- * stream into another stream, such as {@link DoubleStream#filter(DoublePredicate)}), and a
- * <em>terminal operation</em> (which produces a result or side-effect, such
- * as {@link DoubleStream#sum()} or {@link DoubleStream#forEach(DoubleConsumer)}.
- * Streams are lazy; computation on the source data is only performed when the
- * terminal operation is initiated, and source elements are consumed only
- * as needed.
- *
- * <p>Collections and streams, while bearing some superficial similarities,
- * have different goals. Collections are primarily concerned with the efficient
- * management of, and access to, their elements. By contrast, streams do not
- * provide a means to directly access or manipulate their elements, and are
- * instead concerned with declaratively describing their source and the
- * computational operations which will be performed in aggregate on that source.
- * However, if the provided stream operations do not offer the desired
- * functionality, the {@link #iterator()} and {@link #spliterator()} operations
- * can be used to perform a controlled traversal.
- *
- * <p>A stream pipeline, like the "widgets" example above, can be viewed as
- * a <em>query</em> on the stream source. Unless the source was explicitly
- * designed for concurrent modification (such as a {@link ConcurrentHashMap}),
- * unpredictable or erroneous behavior may result from modifying the stream
- * source while it is being queried.
- *
- * <p>Most stream operations accept parameters that describe user-specified
- * behavior, such as the lambda expression {@code w -> w.getWeight()} passed to
- * {@code mapToDouble} in the example above. Such parameters are always instances
- * of a <a href="../function/package-summary.html">functional interface</a> such
- * as {@link java.util.function.Function}, and are often lambda expressions or
- * method references. These parameters can never be null, should not modify the
- * stream source, and should be
- * <a href="package-summary.html#NonInterference">effectively stateless</a>
- * (their result should not depend on any state that might change during
- * execution of the stream pipeline.)
- *
- * <p>A stream should be operated on (invoking an intermediate or terminal stream
- * operation) only once. This rules out, for example, "forked" streams, where
- * the same source feeds two or more pipelines, or multiple traversals of the
- * same stream. A stream implementation may throw {@link IllegalStateException}
- * if it detects that the stream is being reused. However, since some stream
- * operations may return their receiver rather than a new stream object, it may
- * not be possible to detect reuse in all cases.
- *
- * <p>Streams have a {@link #close()} method and implement {@link AutoCloseable},
- * but nearly all stream instances do not actually need to be closed after use.
- * Generally, only streams whose source is an IO channel (such as those returned
- * by {@link Files#lines(Path, Charset)}) will require closing. Most streams
- * are backed by collections, arrays, or generating functions, which require no
- * special resource management. (If a stream does require closing, it can be
- * declared as a resource in a {@code try}-with-resources statement.)
- *
- * <p>Stream pipelines may execute either sequentially or in
- * <a href="package-summary.html#Parallelism">parallel</a>. This
- * execution mode is a property of the stream. Streams are created
- * with an initial choice of sequential or parallel execution. (For example,
- * {@link Collection#stream() Collection.stream()} creates a sequential stream,
- * and {@link Collection#parallelStream() Collection.parallelStream()} creates
- * a parallel one.) This choice of execution mode may be modified by the
- * {@link #sequential()} or {@link #parallel()} methods, and may be queried with
- * the {@link #isParallel()} method.
+ * See the class documentation for {@link Stream} and the package documentation
+ * for <a href="package-summary.html">java.util.stream</a> for additional
+ * specification of streams, stream operations, stream pipelines, and
+ * parallelism.
*
* @since 1.8
+ * @see Stream
* @see <a href="package-summary.html">java.util.stream</a>
*/
public interface DoubleStream extends BaseStream<Double, DoubleStream> {
@@ -144,9 +83,10 @@
* <p>This is an <a href="package-summary.html#StreamOps">intermediate
* operation</a>.
*
- * @param predicate a <a href="package-summary.html#NonInterference">
- * non-interfering, stateless</a> predicate to apply to
- * each element to determine if it should be included
+ * @param predicate a <a href="package-summary.html#NonInterference">non-interfering</a>,
+ * <a href="package-summary.html#Statelessness">stateless</a>
+ * predicate to apply to each element to determine if it
+ * should be included
* @return the new stream
*/
DoubleStream filter(DoublePredicate predicate);
@@ -158,9 +98,9 @@
* <p>This is an <a href="package-summary.html#StreamOps">intermediate
* operation</a>.
*
- * @param mapper a <a href="package-summary.html#NonInterference">
- * non-interfering, stateless</a> function to apply to
- * each element
+ * @param mapper a <a href="package-summary.html#NonInterference">non-interfering</a>,
+ * <a href="package-summary.html#Statelessness">stateless</a>
+ * function to apply to each element
* @return the new stream
*/
DoubleStream map(DoubleUnaryOperator mapper);
@@ -173,9 +113,9 @@
* intermediate operation</a>.
*
* @param <U> the element type of the new stream
- * @param mapper a <a href="package-summary.html#NonInterference">
- * non-interfering, stateless</a> function to apply to each
- * element
+ * @param mapper a <a href="package-summary.html#NonInterference">non-interfering</a>,
+ * <a href="package-summary.html#Statelessness">stateless</a>
+ * function to apply to each element
* @return the new stream
*/
<U> Stream<U> mapToObj(DoubleFunction<? extends U> mapper);
@@ -187,9 +127,9 @@
* <p>This is an <a href="package-summary.html#StreamOps">intermediate
* operation</a>.
*
- * @param mapper a <a href="package-summary.html#NonInterference">
- * non-interfering, stateless</a> function to apply to each
- * element
+ * @param mapper a <a href="package-summary.html#NonInterference">non-interfering</a>,
+ * <a href="package-summary.html#Statelessness">stateless</a>
+ * function to apply to each element
* @return the new stream
*/
IntStream mapToInt(DoubleToIntFunction mapper);
@@ -201,9 +141,9 @@
* <p>This is an <a href="package-summary.html#StreamOps">intermediate
* operation</a>.
*
- * @param mapper a <a href="package-summary.html#NonInterference">
- * non-interfering, stateless</a> function to apply to each
- * element
+ * @param mapper a <a href="package-summary.html#NonInterference">non-interfering</a>,
+ * <a href="package-summary.html#Statelessness">stateless</a>
+ * function to apply to each element
* @return the new stream
*/
LongStream mapToLong(DoubleToLongFunction mapper);
@@ -218,10 +158,10 @@
* <p>This is an <a href="package-summary.html#StreamOps">intermediate
* operation</a>.
*
- * @param mapper a <a href="package-summary.html#NonInterference">
- * non-interfering, stateless</a> function to apply to
- * each element which produces an {@code DoubleStream} of new
- * values
+ * @param mapper a <a href="package-summary.html#NonInterference">non-interfering</a>,
+ * <a href="package-summary.html#Statelessness">stateless</a>
+ * function to apply to each element which produces a
+ * {@code DoubleStream} of new values
* @return the new stream
* @see Stream#flatMap(Function)
*/
@@ -276,8 +216,8 @@
* }</pre>
*
* @param action a <a href="package-summary.html#NonInterference">
- * non-interfering</a> action to perform on the elements as
- * they are consumed from the stream
+ * non-interfering</a> action to perform on the elements as
+ * they are consumed from the stream
* @return the new stream
*/
DoubleStream peek(DoubleConsumer action);
@@ -423,9 +363,10 @@
* synchronization and with greatly reduced risk of data races.
*
* @param identity the identity value for the accumulating function
- * @param op an <a href="package-summary.html#Associativity">associative</a>
- * <a href="package-summary.html#NonInterference">non-interfering,
- * stateless</a> function for combining two values
+ * @param op an <a href="package-summary.html#Associativity">associative</a>,
+ * <a href="package-summary.html#NonInterference">non-interfering</a>,
+ * <a href="package-summary.html#Statelessness">stateless</a>
+ * function for combining two values
* @return the result of the reduction
* @see #sum()
* @see #min()
@@ -462,9 +403,10 @@
* <p>This is a <a href="package-summary.html#StreamOps">terminal
* operation</a>.
*
- * @param op an <a href="package-summary.html#Associativity">associative</a>
- * <a href="package-summary.html#NonInterference">non-interfering,
- * stateless</a> function for combining two values
+ * @param op an <a href="package-summary.html#Associativity">associative</a>,
+ * <a href="package-summary.html#NonInterference">non-interfering</a>,
+ * <a href="package-summary.html#Statelessness">stateless</a>
+ * function for combining two values
* @return the result of the reduction
* @see #reduce(double, DoubleBinaryOperator)
*/
@@ -495,14 +437,15 @@
* @param supplier a function that creates a new result container. For a
* parallel execution, this function may be called
* multiple times and must return a fresh value each time.
- * @param accumulator an <a href="package-summary.html#Associativity">associative</a>
- * <a href="package-summary.html#NonInterference">non-interfering,
- * stateless</a> function for incorporating an additional
- * element into a result
- * @param combiner an <a href="package-summary.html#Associativity">associative</a>
- * <a href="package-summary.html#NonInterference">non-interfering,
- * stateless</a> function for combining two values, which
- * must be compatible with the accumulator function
+ * @param accumulator an <a href="package-summary.html#Associativity">associative</a>,
+ * <a href="package-summary.html#NonInterference">non-interfering</a>,
+ * <a href="package-summary.html#Statelessness">stateless</a>
+ * function for incorporating an additional element into a result
+ * @param combiner an <a href="package-summary.html#Associativity">associative</a>,
+ * <a href="package-summary.html#NonInterference">non-interfering</a>,
+ * <a href="package-summary.html#Statelessness">stateless</a>
+ * function for combining two values, which must be
+ * compatible with the accumulator function
* @return the result of the reduction
* @see Stream#collect(Supplier, BiConsumer, BiConsumer)
*/
@@ -544,8 +487,8 @@
* <p>This is a <a href="package-summary.html#StreamOps">terminal
* operation</a>.
*
- * @apiNote Sorting values by increasing absolute magnitude tends to yield
- * more accurate results.
+ * @apiNote Elements sorted by increasing absolute magnitude tend
+ * to yield more accurate results.
*
* @return the sum of elements in this stream
*/
@@ -651,48 +594,67 @@
/**
* Returns whether any elements of this stream match the provided
* predicate. May not evaluate the predicate on all elements if not
- * necessary for determining the result.
+ * necessary for determining the result. If the stream is empty then
+ * {@code false} is returned and the predicate is not evaluated.
*
* <p>This is a <a href="package-summary.html#StreamOps">short-circuiting
* terminal operation</a>.
*
- * @param predicate a <a href="package-summary.html#NonInterference">non-interfering,
- * stateless</a> predicate to apply to elements of this
- * stream
+ * @apiNote
+ * This method evaluates the <em>existential quantification</em> of the
+ * predicate over the elements of the stream (for some x P(x)).
+ *
+ * @param predicate a <a href="package-summary.html#NonInterference">non-interfering</a>,
+ * <a href="package-summary.html#Statelessness">stateless</a>
+ * predicate to apply to elements of this stream
* @return {@code true} if any elements of the stream match the provided
- * predicate otherwise {@code false}
+ * predicate, otherwise {@code false}
*/
boolean anyMatch(DoublePredicate predicate);
/**
* Returns whether all elements of this stream match the provided predicate.
* May not evaluate the predicate on all elements if not necessary for
- * determining the result.
+ * determining the result. If the stream is empty then {@code true} is
+ * returned and the predicate is not evaluated.
*
* <p>This is a <a href="package-summary.html#StreamOps">short-circuiting
* terminal operation</a>.
*
- * @param predicate a <a href="package-summary.html#NonInterference">non-interfering,
- * stateless</a> predicate to apply to elements of this
- * stream
- * @return {@code true} if all elements of the stream match the provided
- * predicate otherwise {@code false}
+ * @apiNote
+ * This method evaluates the <em>universal quantification</em> of the
+ * predicate over the elements of the stream (for all x P(x)). If the
+ * stream is empty, the quantification is said to be <em>vacuously
+ * satisfied</em> and is always {@code true} (regardless of P(x)).
+ *
+ * @param predicate a <a href="package-summary.html#NonInterference">non-interfering</a>,
+ * <a href="package-summary.html#Statelessness">stateless</a>
+ * predicate to apply to elements of this stream
+ * @return {@code true} if either all elements of the stream match the
+ * provided predicate or the stream is empty, otherwise {@code false}
*/
boolean allMatch(DoublePredicate predicate);
/**
* Returns whether no elements of this stream match the provided predicate.
* May not evaluate the predicate on all elements if not necessary for
- * determining the result.
+ * determining the result. If the stream is empty then {@code true} is
+ * returned and the predicate is not evaluated.
*
* <p>This is a <a href="package-summary.html#StreamOps">short-circuiting
* terminal operation</a>.
*
- * @param predicate a <a href="package-summary.html#NonInterference">non-interfering,
- * stateless</a> predicate to apply to elements of this
- * stream
- * @return {@code true} if no elements of the stream match the provided
- * predicate otherwise {@code false}
+ * @apiNote
+ * This method evaluates the <em>universal quantification</em> of the
+ * negated predicate over the elements of the stream (for all x ~P(x)). If
+ * the stream is empty, the quantification is said to be vacuously satisfied
+ * and is always {@code true}, regardless of P(x).
+ *
+ * @param predicate a <a href="package-summary.html#NonInterference">non-interfering</a>,
+ * <a href="package-summary.html#Statelessness">stateless</a>
+ * predicate to apply to elements of this stream
+ * @return {@code true} if either no elements of the stream match the
+ * provided predicate or the stream is empty, otherwise {@code false}
*/
boolean noneMatch(DoublePredicate predicate);
@@ -832,12 +794,12 @@
}
/**
- * Returns a sequential stream where each element is generated by
- * the provided {@code DoubleSupplier}. This is suitable for generating
- * constant streams, streams of random elements, etc.
+ * Returns an infinite sequential unordered stream where each element is
+ * generated by the provided {@code DoubleSupplier}. This is suitable for
+ * generating constant streams, streams of random elements, etc.
*
* @param s the {@code DoubleSupplier} for generated elements
- * @return a new sequential {@code DoubleStream}
+ * @return a new infinite sequential unordered {@code DoubleStream}
*/
public static DoubleStream generate(DoubleSupplier s) {
Objects.requireNonNull(s);
@@ -848,11 +810,16 @@
/**
* Creates a lazily concatenated stream whose elements are all the
* elements of the first stream followed by all the elements of the
- * second stream. The resulting stream is ordered if both
+ * second stream. The resulting stream is ordered if both
* of the input streams are ordered, and parallel if either of the input
* streams is parallel. When the resulting stream is closed, the close
* handlers for both input streams are invoked.
*
+ * @implNote
+ * Use caution when constructing streams from repeated concatenation.
+ * Accessing an element of a deeply concatenated stream can result in deep
+ * call chains, or even {@code StackOverflowException}.
+ *
* @param a the first stream
* @param b the second stream
* @return the concatenation of the two input streams
--- a/jdk/src/share/classes/java/util/stream/IntStream.java Tue Oct 22 19:37:11 2013 -0400
+++ b/jdk/src/share/classes/java/util/stream/IntStream.java Tue Oct 22 19:43:42 2013 -0400
@@ -24,11 +24,7 @@
*/
package java.util.stream;
-import java.nio.charset.Charset;
-import java.nio.file.Files;
-import java.nio.file.Path;
import java.util.Arrays;
-import java.util.Collection;
import java.util.IntSummaryStatistics;
import java.util.Objects;
import java.util.OptionalDouble;
@@ -36,7 +32,6 @@
import java.util.PrimitiveIterator;
import java.util.Spliterator;
import java.util.Spliterators;
-import java.util.concurrent.ConcurrentHashMap;
import java.util.function.BiConsumer;
import java.util.function.Function;
import java.util.function.IntBinaryOperator;
@@ -51,9 +46,13 @@
import java.util.function.Supplier;
/**
- * A sequence of elements supporting sequential and parallel aggregate
- * operations. The following example illustrates an aggregate operation using
- * {@link Stream} and {@link IntStream}:
+ * A sequence of primitive int-valued elements supporting sequential and parallel
+ * aggregate operations. This is the {@code int} primitive specialization of
+ * {@link Stream}.
+ *
+ * <p>The following example illustrates an aggregate operation using
+ * {@link Stream} and {@link IntStream}, computing the sum of the weights of the
+ * red widgets:
*
* <pre>{@code
* int sum = widgets.stream()
@@ -62,78 +61,13 @@
* .sum();
* }</pre>
*
- * In this example, {@code widgets} is a {@code Collection<Widget>}. We create
- * a stream of {@code Widget} objects via {@link Collection#stream Collection.stream()},
- * filter it to produce a stream containing only the red widgets, and then
- * transform it into a stream of {@code int} values representing the weight of
- * each red widget. Then this stream is summed to produce a total weight.
- *
- * <p>To perform a computation, stream
- * <a href="package-summary.html#StreamOps">operations</a> are composed into a
- * <em>stream pipeline</em>. A stream pipeline consists of a source (which
- * might be an array, a collection, a generator function, an IO channel,
- * etc), zero or more <em>intermediate operations</em> (which transform a
- * stream into another stream, such as {@link IntStream#filter(IntPredicate)}), and a
- * <em>terminal operation</em> (which produces a result or side-effect, such
- * as {@link IntStream#sum()} or {@link IntStream#forEach(IntConsumer)}).
- * Streams are lazy; computation on the source data is only performed when the
- * terminal operation is initiated, and source elements are consumed only
- * as needed.
- *
- * <p>Collections and streams, while bearing some superficial similarities,
- * have different goals. Collections are primarily concerned with the efficient
- * management of, and access to, their elements. By contrast, streams do not
- * provide a means to directly access or manipulate their elements, and are
- * instead concerned with declaratively describing their source and the
- * computational operations which will be performed in aggregate on that source.
- * However, if the provided stream operations do not offer the desired
- * functionality, the {@link #iterator()} and {@link #spliterator()} operations
- * can be used to perform a controlled traversal.
- *
- * <p>A stream pipeline, like the "widgets" example above, can be viewed as
- * a <em>query</em> on the stream source. Unless the source was explicitly
- * designed for concurrent modification (such as a {@link ConcurrentHashMap}),
- * unpredictable or erroneous behavior may result from modifying the stream
- * source while it is being queried.
- *
- * <p>Most stream operations accept parameters that describe user-specified
- * behavior, such as the lambda expression {@code w -> w.getWeight()} passed to
- * {@code mapToInt} in the example above. Such parameters are always instances
- * of a <a href="../function/package-summary.html">functional interface</a> such
- * as {@link java.util.function.Function}, and are often lambda expressions or
- * method references. These parameters can never be null, should not modify the
- * stream source, and should be
- * <a href="package-summary.html#NonInterference">effectively stateless</a>
- * (their result should not depend on any state that might change during
- * execution of the stream pipeline.)
- *
- * <p>A stream should be operated on (invoking an intermediate or terminal stream
- * operation) only once. This rules out, for example, "forked" streams, where
- * the same source feeds two or more pipelines, or multiple traversals of the
- * same stream. A stream implementation may throw {@link IllegalStateException}
- * if it detects that the stream is being reused. However, since some stream
- * operations may return their receiver rather than a new stream object, it may
- * not be possible to detect reuse in all cases.
- *
- * <p>Streams have a {@link #close()} method and implement {@link AutoCloseable},
- * but nearly all stream instances do not actually need to be closed after use.
- * Generally, only streams whose source is an IO channel (such as those returned
- * by {@link Files#lines(Path, Charset)}) will require closing. Most streams
- * are backed by collections, arrays, or generating functions, which require no
- * special resource management. (If a stream does require closing, it can be
- * declared as a resource in a {@code try}-with-resources statement.)
- *
- * <p>Stream pipelines may execute either sequentially or in
- * <a href="package-summary.html#Parallelism">parallel</a>. This
- * execution mode is a property of the stream. Streams are created
- * with an initial choice of sequential or parallel execution. (For example,
- * {@link Collection#stream() Collection.stream()} creates a sequential stream,
- * and {@link Collection#parallelStream() Collection.parallelStream()} creates
- * a parallel one.) This choice of execution mode may be modified by the
- * {@link #sequential()} or {@link #parallel()} methods, and may be queried with
- * the {@link #isParallel()} method.
+ * See the class documentation for {@link Stream} and the package documentation
+ * for <a href="package-summary.html">java.util.stream</a> for additional
+ * specification of streams, stream operations, stream pipelines, and
+ * parallelism.
*
* @since 1.8
+ * @see Stream
* @see <a href="package-summary.html">java.util.stream</a>
*/
public interface IntStream extends BaseStream<Integer, IntStream> {
@@ -145,9 +79,10 @@
* <p>This is an <a href="package-summary.html#StreamOps">intermediate
* operation</a>.
*
- * @param predicate a <a href="package-summary.html#NonInterference">
- * non-interfering, stateless</a> predicate to apply to
- * each element to determine if it should be included
+ * @param predicate a <a href="package-summary.html#NonInterference">non-interfering</a>,
+ * <a href="package-summary.html#Statelessness">stateless</a>
+ * predicate to apply to each element to determine if it
+ * should be included
* @return the new stream
*/
IntStream filter(IntPredicate predicate);
@@ -159,9 +94,9 @@
* <p>This is an <a href="package-summary.html#StreamOps">intermediate
* operation</a>.
*
- * @param mapper a <a href="package-summary.html#NonInterference">
- * non-interfering, stateless</a> function to apply to each
- * element
+ * @param mapper a <a href="package-summary.html#NonInterference">non-interfering</a>,
+ * <a href="package-summary.html#Statelessness">stateless</a>
+ * function to apply to each element
* @return the new stream
*/
IntStream map(IntUnaryOperator mapper);
@@ -174,9 +109,9 @@
* intermediate operation</a>.
*
* @param <U> the element type of the new stream
- * @param mapper a <a href="package-summary.html#NonInterference">
- * non-interfering, stateless</a> function to apply to each
- * element
+ * @param mapper a <a href="package-summary.html#NonInterference">non-interfering</a>,
+ * <a href="package-summary.html#Statelessness">stateless</a>
+ * function to apply to each element
* @return the new stream
*/
<U> Stream<U> mapToObj(IntFunction<? extends U> mapper);
@@ -188,9 +123,9 @@
* <p>This is an <a href="package-summary.html#StreamOps">intermediate
* operation</a>.
*
- * @param mapper a <a href="package-summary.html#NonInterference">
- * non-interfering, stateless</a> function to apply to each
- * element
+ * @param mapper a <a href="package-summary.html#NonInterference">non-interfering</a>,
+ * <a href="package-summary.html#Statelessness">stateless</a>
+ * function to apply to each element
* @return the new stream
*/
LongStream mapToLong(IntToLongFunction mapper);
@@ -202,9 +137,9 @@
* <p>This is an <a href="package-summary.html#StreamOps">intermediate
* operation</a>.
*
- * @param mapper a <a href="package-summary.html#NonInterference">
- * non-interfering, stateless</a> function to apply to each
- * element
+ * @param mapper a <a href="package-summary.html#NonInterference">non-interfering</a>,
+ * <a href="package-summary.html#Statelessness">stateless</a>
+ * function to apply to each element
* @return the new stream
*/
DoubleStream mapToDouble(IntToDoubleFunction mapper);
@@ -219,10 +154,10 @@
* <p>This is an <a href="package-summary.html#StreamOps">intermediate
* operation</a>.
*
- * @param mapper a <a href="package-summary.html#NonInterference">
- * non-interfering, stateless</a> function to apply to
- * each element which produces an {@code IntStream} of new
- * values
+ * @param mapper a <a href="package-summary.html#NonInterference">non-interfering</a>,
+ * <a href="package-summary.html#Statelessness">stateless</a>
+ * function to apply to each element which produces an
+ * {@code IntStream} of new values
* @return the new stream
* @see Stream#flatMap(Function)
*/
@@ -421,9 +356,10 @@
* synchronization and with greatly reduced risk of data races.
*
* @param identity the identity value for the accumulating function
- * @param op an <a href="package-summary.html#Associativity">associative</a>
- * <a href="package-summary.html#NonInterference">non-interfering,
- * stateless</a> function for combining two values
+ * @param op an <a href="package-summary.html#Associativity">associative</a>,
+ * <a href="package-summary.html#NonInterference">non-interfering</a>,
+ * <a href="package-summary.html#Statelessness">stateless</a>
+ * function for combining two values
* @return the result of the reduction
* @see #sum()
* @see #min()
@@ -460,9 +396,10 @@
* <p>This is a <a href="package-summary.html#StreamOps">terminal
* operation</a>.
*
- * @param op an <a href="package-summary.html#Associativity">associative</a>
- * <a href="package-summary.html#NonInterference">non-interfering,
- * stateless</a> function for combining two values
+ * @param op an <a href="package-summary.html#Associativity">associative</a>,
+ * <a href="package-summary.html#NonInterference">non-interfering</a>,
+ * <a href="package-summary.html#Statelessness">stateless</a>
+ * function for combining two values
* @return the result of the reduction
* @see #reduce(int, IntBinaryOperator)
*/
@@ -492,14 +429,15 @@
* @param supplier a function that creates a new result container. For a
* parallel execution, this function may be called
* multiple times and must return a fresh value each time.
- * @param accumulator an <a href="package-summary.html#Associativity">associative</a>
- * <a href="package-summary.html#NonInterference">non-interfering,
- * stateless</a> function for incorporating an additional
- * element into a result
- * @param combiner an <a href="package-summary.html#Associativity">associative</a>
- * <a href="package-summary.html#NonInterference">non-interfering,
- * stateless</a> function for combining two values, which
- * must be compatible with the accumulator function
+ * @param accumulator an <a href="package-summary.html#Associativity">associative</a>,
+ * <a href="package-summary.html#NonInterference">non-interfering</a>,
+ * <a href="package-summary.html#Statelessness">stateless</a>
+ * function for incorporating an additional element into a result
+ * @param combiner an <a href="package-summary.html#Associativity">associative</a>,
+ * <a href="package-summary.html#NonInterference">non-interfering</a>,
+ * <a href="package-summary.html#Statelessness">stateless</a>
+ * function for combining two values, which must be
+ * compatible with the accumulator function
* @return the result of the reduction
* @see Stream#collect(Supplier, BiConsumer, BiConsumer)
*/
@@ -599,48 +537,67 @@
/**
* Returns whether any elements of this stream match the provided
* predicate. May not evaluate the predicate on all elements if not
- * necessary for determining the result.
+ * necessary for determining the result. If the stream is empty then
+ * {@code false} is returned and the predicate is not evaluated.
*
* <p>This is a <a href="package-summary.html#StreamOps">short-circuiting
* terminal operation</a>.
*
- * @param predicate a <a href="package-summary.html#NonInterference">non-interfering,
- * stateless</a> predicate to apply to elements of this
- * stream
+ * @apiNote
+ * This method evaluates the <em>existential quantification</em> of the
+ * predicate over the elements of the stream (for some x P(x)).
+ *
+ * @param predicate a <a href="package-summary.html#NonInterference">non-interfering</a>,
+ * <a href="package-summary.html#Statelessness">stateless</a>
+ * predicate to apply to elements of this stream
* @return {@code true} if any elements of the stream match the provided
- * predicate otherwise {@code false}
+ * predicate, otherwise {@code false}
*/
boolean anyMatch(IntPredicate predicate);
/**
* Returns whether all elements of this stream match the provided predicate.
* May not evaluate the predicate on all elements if not necessary for
- * determining the result.
+ * determining the result. If the stream is empty then {@code true} is
+ * returned and the predicate is not evaluated.
*
* <p>This is a <a href="package-summary.html#StreamOps">short-circuiting
* terminal operation</a>.
*
- * @param predicate a <a href="package-summary.html#NonInterference">non-interfering,
- * stateless</a> predicate to apply to elements of this
- * stream
- * @return {@code true} if all elements of the stream match the provided
- * predicate otherwise {@code false}
+ * @apiNote
+ * This method evaluates the <em>universal quantification</em> of the
+ * predicate over the elements of the stream (for all x P(x)). If the
+ * stream is empty, the quantification is said to be <em>vacuously
+ * satisfied</em> and is always {@code true} (regardless of P(x)).
+ *
+ * @param predicate a <a href="package-summary.html#NonInterference">non-interfering</a>,
+ * <a href="package-summary.html#Statelessness">stateless</a>
+ * predicate to apply to elements of this stream
+ * @return {@code true} if either all elements of the stream match the
+ * provided predicate or the stream is empty, otherwise {@code false}
*/
boolean allMatch(IntPredicate predicate);
/**
* Returns whether no elements of this stream match the provided predicate.
* May not evaluate the predicate on all elements if not necessary for
- * determining the result.
+ * determining the result. If the stream is empty then {@code true} is
+ * returned and the predicate is not evaluated.
*
* <p>This is a <a href="package-summary.html#StreamOps">short-circuiting
* terminal operation</a>.
*
- * @param predicate a <a href="package-summary.html#NonInterference">non-interfering,
- * stateless</a> predicate to apply to elements of this
- * stream
- * @return {@code true} if no elements of the stream match the provided
- * predicate otherwise {@code false}
+ * @apiNote
+ * This method evaluates the <em>universal quantification</em> of the
+ * negated predicate over the elements of the stream (for all x ~P(x)). If
+ * the stream is empty, the quantification is said to be vacuously satisfied
+ * and is always {@code true}, regardless of P(x).
+ *
+ * @param predicate a <a href="package-summary.html#NonInterference">non-interfering</a>,
+ * <a href="package-summary.html#Statelessness">stateless</a>
+ * predicate to apply to elements of this stream
+ * @return {@code true} if either no elements of the stream match the
+ * provided predicate or the stream is empty, otherwise {@code false}
*/
boolean noneMatch(IntPredicate predicate);
@@ -803,12 +760,12 @@
}
/**
- * Returns a sequential stream where each element is generated by
- * the provided {@code IntSupplier}. This is suitable for generating
- * constant streams, streams of random elements, etc.
+ * Returns an infinite sequential unordered stream where each element is
+ * generated by the provided {@code IntSupplier}. This is suitable for
+ * generating constant streams, streams of random elements, etc.
*
* @param s the {@code IntSupplier} for generated elements
- * @return a new sequential {@code IntStream}
+ * @return a new infinite sequential unordered {@code IntStream}
*/
public static IntStream generate(IntSupplier s) {
Objects.requireNonNull(s);
@@ -871,11 +828,16 @@
/**
* Creates a lazily concatenated stream whose elements are all the
* elements of the first stream followed by all the elements of the
- * second stream. The resulting stream is ordered if both
+ * second stream. The resulting stream is ordered if both
* of the input streams are ordered, and parallel if either of the input
* streams is parallel. When the resulting stream is closed, the close
* handlers for both input streams are invoked.
*
+ * @implNote
+ * Use caution when constructing streams from repeated concatenation.
+ * Accessing an element of a deeply concatenated stream can result in deep
+ * call chains, or even {@code StackOverflowException}.
+ *
* @param a the first stream
* @param b the second stream
* @return the concatenation of the two input streams
--- a/jdk/src/share/classes/java/util/stream/LongStream.java Tue Oct 22 19:37:11 2013 -0400
+++ b/jdk/src/share/classes/java/util/stream/LongStream.java Tue Oct 22 19:43:42 2013 -0400
@@ -51,9 +51,13 @@
import java.util.function.Supplier;
/**
- * A sequence of elements supporting sequential and parallel aggregate
- * operations. The following example illustrates an aggregate operation using
- * {@link Stream} and {@link LongStream}:
+ * A sequence of primitive long-valued elements supporting sequential and parallel
+ * aggregate operations. This is the {@code long} primitive specialization of
+ * {@link Stream}.
+ *
+ * <p>The following example illustrates an aggregate operation using
+ * {@link Stream} and {@link LongStream}, computing the sum of the weights of the
+ * red widgets:
*
* <pre>{@code
* long sum = widgets.stream()
@@ -62,78 +66,13 @@
* .sum();
* }</pre>
*
- * In this example, {@code widgets} is a {@code Collection<Widget>}. We create
- * a stream of {@code Widget} objects via {@link Collection#stream Collection.stream()},
- * filter it to produce a stream containing only the red widgets, and then
- * transform it into a stream of {@code long} values representing the weight of
- * each red widget. Then this stream is summed to produce a total weight.
- *
- * <p>To perform a computation, stream
- * <a href="package-summary.html#StreamOps">operations</a> are composed into a
- * <em>stream pipeline</em>. A stream pipeline consists of a source (which
- * might be an array, a collection, a generator function, an IO channel,
- * etc), zero or more <em>intermediate operations</em> (which transform a
- * stream into another stream, such as {@link LongStream#filter(LongPredicate)}), and a
- * <em>terminal operation</em> (which produces a result or side-effect, such
- * as {@link LongStream#sum()} or {@link LongStream#forEach(LongConsumer)}).
- * Streams are lazy; computation on the source data is only performed when the
- * terminal operation is initiated, and source elements are consumed only
- * as needed.
- *
- * <p>Collections and streams, while bearing some superficial similarities,
- * have different goals. Collections are primarily concerned with the efficient
- * management of, and access to, their elements. By contrast, streams do not
- * provide a means to directly access or manipulate their elements, and are
- * instead concerned with declaratively describing their source and the
- * computational operations which will be performed in aggregate on that source.
- * However, if the provided stream operations do not offer the desired
- * functionality, the {@link #iterator()} and {@link #spliterator()} operations
- * can be used to perform a controlled traversal.
- *
- * <p>A stream pipeline, like the "widgets" example above, can be viewed as
- * a <em>query</em> on the stream source. Unless the source was explicitly
- * designed for concurrent modification (such as a {@link ConcurrentHashMap}),
- * unpredictable or erroneous behavior may result from modifying the stream
- * source while it is being queried.
- *
- * <p>Most stream operations accept parameters that describe user-specified
- * behavior, such as the lambda expression {@code w -> w.getWeight()} passed to
- * {@code mapToLong} in the example above. Such parameters are always instances
- * of a <a href="../function/package-summary.html">functional interface</a> such
- * as {@link java.util.function.Function}, and are often lambda expressions or
- * method references. These parameters can never be null, should not modify the
- * stream source, and should be
- * <a href="package-summary.html#NonInterference">effectively stateless</a>
- * (their result should not depend on any state that might change during
- * execution of the stream pipeline.)
- *
- * <p>A stream should be operated on (invoking an intermediate or terminal stream
- * operation) only once. This rules out, for example, "forked" streams, where
- * the same source feeds two or more pipelines, or multiple traversals of the
- * same stream. A stream implementation may throw {@link IllegalStateException}
- * if it detects that the stream is being reused. However, since some stream
- * operations may return their receiver rather than a new stream object, it may
- * not be possible to detect reuse in all cases.
- *
- * <p>Streams have a {@link #close()} method and implement {@link AutoCloseable},
- * but nearly all stream instances do not actually need to be closed after use.
- * Generally, only streams whose source is an IO channel (such as those returned
- * by {@link Files#lines(Path, Charset)}) will require closing. Most streams
- * are backed by collections, arrays, or generating functions, which require no
- * special resource management. (If a stream does require closing, it can be
- * declared as a resource in a {@code try}-with-resources statement.)
- *
- * <p>Stream pipelines may execute either sequentially or in
- * <a href="package-summary.html#Parallelism">parallel</a>. This
- * execution mode is a property of the stream. Streams are created
- * with an initial choice of sequential or parallel execution. (For example,
- * {@link Collection#stream() Collection.stream()} creates a sequential stream,
- * and {@link Collection#parallelStream() Collection.parallelStream()} creates
- * a parallel one.) This choice of execution mode may be modified by the
- * {@link #sequential()} or {@link #parallel()} methods, and may be queried with
- * the {@link #isParallel()} method.
+ * See the class documentation for {@link Stream} and the package documentation
+ * for <a href="package-summary.html">java.util.stream</a> for additional
+ * specification of streams, stream operations, stream pipelines, and
+ * parallelism.
*
* @since 1.8
+ * @see Stream
* @see <a href="package-summary.html">java.util.stream</a>
*/
public interface LongStream extends BaseStream<Long, LongStream> {
@@ -145,9 +84,10 @@
* <p>This is an <a href="package-summary.html#StreamOps">intermediate
* operation</a>.
*
- * @param predicate a <a href="package-summary.html#NonInterference">
- * non-interfering, stateless</a> predicate to apply to
- * each element to determine if it should be included
+ * @param predicate a <a href="package-summary.html#NonInterference">non-interfering</a>,
+ * <a href="package-summary.html#Statelessness">stateless</a>
+ * predicate to apply to each element to determine if it
+ * should be included
* @return the new stream
*/
LongStream filter(LongPredicate predicate);
@@ -159,9 +99,9 @@
* <p>This is an <a href="package-summary.html#StreamOps">intermediate
* operation</a>.
*
- * @param mapper a <a href="package-summary.html#NonInterference">
- * non-interfering, stateless</a> function to apply to each
- * element
+ * @param mapper a <a href="package-summary.html#NonInterference">non-interfering</a>,
+ * <a href="package-summary.html#Statelessness">stateless</a>
+ * function to apply to each element
* @return the new stream
*/
LongStream map(LongUnaryOperator mapper);
@@ -174,9 +114,9 @@
* intermediate operation</a>.
*
* @param <U> the element type of the new stream
- * @param mapper a <a href="package-summary.html#NonInterference">
- * non-interfering, stateless</a> function to apply to each
- * element
+ * @param mapper a <a href="package-summary.html#NonInterference">non-interfering</a>,
+ * <a href="package-summary.html#Statelessness">stateless</a>
+ * function to apply to each element
* @return the new stream
*/
<U> Stream<U> mapToObj(LongFunction<? extends U> mapper);
@@ -188,9 +128,9 @@
* <p>This is an <a href="package-summary.html#StreamOps">intermediate
* operation</a>.
*
- * @param mapper a <a href="package-summary.html#NonInterference">
- * non-interfering, stateless</a> function to apply to each
- * element
+ * @param mapper a <a href="package-summary.html#NonInterference">non-interfering</a>,
+ * <a href="package-summary.html#Statelessness">stateless</a>
+ * function to apply to each element
* @return the new stream
*/
IntStream mapToInt(LongToIntFunction mapper);
@@ -202,9 +142,9 @@
* <p>This is an <a href="package-summary.html#StreamOps">intermediate
* operation</a>.
*
- * @param mapper a <a href="package-summary.html#NonInterference">
- * non-interfering, stateless</a> function to apply to each
- * element
+ * @param mapper a <a href="package-summary.html#NonInterference">non-interfering</a>,
+ * <a href="package-summary.html#Statelessness">stateless</a>
+ * function to apply to each element
* @return the new stream
*/
DoubleStream mapToDouble(LongToDoubleFunction mapper);
@@ -219,10 +159,10 @@
* <p>This is an <a href="package-summary.html#StreamOps">intermediate
* operation</a>.
*
- * @param mapper a <a href="package-summary.html#NonInterference">
- * non-interfering, stateless</a> function to apply to
- * each element which produces an {@code LongStream} of new
- * values
+ * @param mapper a <a href="package-summary.html#NonInterference">non-interfering</a>,
+ * <a href="package-summary.html#Statelessness">stateless</a>
+ * function to apply to each element which produces a
+ * {@code LongStream} of new values
* @return the new stream
* @see Stream#flatMap(Function)
*/
@@ -421,9 +361,10 @@
* synchronization and with greatly reduced risk of data races.
*
* @param identity the identity value for the accumulating function
- * @param op an <a href="package-summary.html#Associativity">associative</a>
- * <a href="package-summary.html#NonInterference">non-interfering,
- * stateless</a> function for combining two values
+ * @param op an <a href="package-summary.html#Associativity">associative</a>,
+ * <a href="package-summary.html#NonInterference">non-interfering</a>,
+ * <a href="package-summary.html#Statelessness">stateless</a>
+ * function for combining two values
* @return the result of the reduction
* @see #sum()
* @see #min()
@@ -460,9 +401,10 @@
* <p>This is a <a href="package-summary.html#StreamOps">terminal
* operation</a>.
*
- * @param op an <a href="package-summary.html#Associativity">associative</a>
- * <a href="package-summary.html#NonInterference">non-interfering,
- * stateless</a> function for combining two values
+ * @param op an <a href="package-summary.html#Associativity">associative</a>,
+ * <a href="package-summary.html#NonInterference">non-interfering</a>,
+ * <a href="package-summary.html#Statelessness">stateless</a>
+ * function for combining two values
* @return the result of the reduction
* @see #reduce(long, LongBinaryOperator)
*/
@@ -492,14 +434,15 @@
* @param supplier a function that creates a new result container. For a
* parallel execution, this function may be called
* multiple times and must return a fresh value each time.
- * @param accumulator an <a href="package-summary.html#Associativity">associative</a>
- * <a href="package-summary.html#NonInterference">non-interfering,
- * stateless</a> function for incorporating an additional
- * element into a result
- * @param combiner an <a href="package-summary.html#Associativity">associative</a>
- * <a href="package-summary.html#NonInterference">non-interfering,
- * stateless</a> function for combining two values, which
- * must be compatible with the accumulator function
+ * @param accumulator an <a href="package-summary.html#Associativity">associative</a>,
+ * <a href="package-summary.html#NonInterference">non-interfering</a>,
+ * <a href="package-summary.html#Statelessness">stateless</a>
+ * function for incorporating an additional element into a result
+ * @param combiner an <a href="package-summary.html#Associativity">associative</a>,
+ * <a href="package-summary.html#NonInterference">non-interfering</a>,
+ * <a href="package-summary.html#Statelessness">stateless</a>
+ * function for combining two values, which must be
+ * compatible with the accumulator function
* @return the result of the reduction
* @see Stream#collect(Supplier, BiConsumer, BiConsumer)
*/
@@ -599,48 +542,67 @@
/**
* Returns whether any elements of this stream match the provided
* predicate. May not evaluate the predicate on all elements if not
- * necessary for determining the result.
+ * necessary for determining the result. If the stream is empty then
+ * {@code false} is returned and the predicate is not evaluated.
*
* <p>This is a <a href="package-summary.html#StreamOps">short-circuiting
* terminal operation</a>.
*
- * @param predicate a <a href="package-summary.html#NonInterference">non-interfering,
- * stateless</a> predicate to apply to elements of this
- * stream
+ * @apiNote
+ * This method evaluates the <em>existential quantification</em> of the
+ * predicate over the elements of the stream (for some x P(x)).
+ *
+ * @param predicate a <a href="package-summary.html#NonInterference">non-interfering</a>,
+ * <a href="package-summary.html#Statelessness">stateless</a>
+ * predicate to apply to elements of this stream
* @return {@code true} if any elements of the stream match the provided
- * predicate otherwise {@code false}
+ * predicate, otherwise {@code false}
*/
boolean anyMatch(LongPredicate predicate);
/**
* Returns whether all elements of this stream match the provided predicate.
* May not evaluate the predicate on all elements if not necessary for
- * determining the result.
+ * determining the result. If the stream is empty then {@code true} is
+ * returned and the predicate is not evaluated.
*
* <p>This is a <a href="package-summary.html#StreamOps">short-circuiting
* terminal operation</a>.
*
- * @param predicate a <a href="package-summary.html#NonInterference">non-interfering,
- * stateless</a> predicate to apply to elements of this
- * stream
- * @return {@code true} if all elements of the stream match the provided
- * predicate otherwise {@code false}
+ * @apiNote
+ * This method evaluates the <em>universal quantification</em> of the
+ * predicate over the elements of the stream (for all x P(x)). If the
+ * stream is empty, the quantification is said to be <em>vacuously
+ * satisfied</em> and is always {@code true} (regardless of P(x)).
+ *
+ * @param predicate a <a href="package-summary.html#NonInterference">non-interfering</a>,
+ * <a href="package-summary.html#Statelessness">stateless</a>
+ * predicate to apply to elements of this stream
+ * @return {@code true} if either all elements of the stream match the
+ * provided predicate or the stream is empty, otherwise {@code false}
*/
boolean allMatch(LongPredicate predicate);
/**
- * Returns whether no elements of this stream match the provided predicate.
+ * Returns whether no elements of this stream match the provided predicate.
* May not evaluate the predicate on all elements if not necessary for
- * determining the result.
+ * determining the result. If the stream is empty then {@code true} is
+ * returned and the predicate is not evaluated.
*
* <p>This is a <a href="package-summary.html#StreamOps">short-circuiting
* terminal operation</a>.
*
- * @param predicate a <a href="package-summary.html#NonInterference">non-interfering,
- * stateless</a> predicate to apply to elements of this
- * stream
- * @return {@code true} if no elements of the stream match the provided
- * predicate otherwise {@code false}
+ * @apiNote
+ * This method evaluates the <em>universal quantification</em> of the
+ * negated predicate over the elements of the stream (for all x ~P(x)). If
+ * the stream is empty, the quantification is said to be vacuously satisfied
+ * and is always {@code true}, regardless of P(x).
+ *
+ * @param predicate a <a href="package-summary.html#NonInterference">non-interfering</a>,
+ * <a href="package-summary.html#Statelessness">stateless</a>
+ * predicate to apply to elements of this stream
+ * @return {@code true} if either no elements of the stream match the
+ * provided predicate or the stream is empty, otherwise {@code false}
*/
boolean noneMatch(LongPredicate predicate);
@@ -791,12 +753,12 @@
}
/**
- * Returns a sequential stream where each element is generated by
- * the provided {@code LongSupplier}. This is suitable for generating
- * constant streams, streams of random elements, etc.
+ * Returns an infinite sequential unordered stream where each element is
+ * generated by the provided {@code LongSupplier}. This is suitable for
+ * generating constant streams, streams of random elements, etc.
*
* @param s the {@code LongSupplier} for generated elements
- * @return a new sequential {@code LongStream}
+ * @return a new infinite sequential unordered {@code LongStream}
*/
public static LongStream generate(LongSupplier s) {
Objects.requireNonNull(s);
@@ -874,11 +836,16 @@
/**
* Creates a lazily concatenated stream whose elements are all the
* elements of the first stream followed by all the elements of the
- * second stream. The resulting stream is ordered if both
+ * second stream. The resulting stream is ordered if both
* of the input streams are ordered, and parallel if either of the input
* streams is parallel. When the resulting stream is closed, the close
* handlers for both input streams are invoked.
*
+ * @implNote
+ * Use caution when constructing streams from repeated concatenation.
+ * Accessing an element of a deeply concatenated stream can result in deep
+ * call chains, or even {@code StackOverflowException}.
+ *
* @param a the first stream
* @param b the second stream
* @return the concatenation of the two input streams
--- a/jdk/src/share/classes/java/util/stream/Node.java Tue Oct 22 19:37:11 2013 -0400
+++ b/jdk/src/share/classes/java/util/stream/Node.java Tue Oct 22 19:43:42 2013 -0400
@@ -241,6 +241,7 @@
* @param action a consumer that is to be invoked with each
* element in this {@code Node.OfPrimitive}
*/
+ @SuppressWarnings("overloads")
void forEach(T_CONS action);
@Override
--- a/jdk/src/share/classes/java/util/stream/SpinedBuffer.java Tue Oct 22 19:37:11 2013 -0400
+++ b/jdk/src/share/classes/java/util/stream/SpinedBuffer.java Tue Oct 22 19:43:42 2013 -0400
@@ -579,6 +579,7 @@
spineIndex = 0;
}
+ @SuppressWarnings("overloads")
public void forEach(T_CONS consumer) {
// completed chunks, if any
for (int j = 0; j < spineIndex; j++)
--- a/jdk/src/share/classes/java/util/stream/Stream.java Tue Oct 22 19:37:11 2013 -0400
+++ b/jdk/src/share/classes/java/util/stream/Stream.java Tue Oct 22 19:43:42 2013 -0400
@@ -67,6 +67,11 @@
* transform it into a stream of {@code int} values representing the weight of
* each red widget. Then this stream is summed to produce a total weight.
*
+ * <p>In addition to {@code Stream}, which is a stream of object references,
+ * there are primitive specializations for {@link IntStream}, {@link LongStream},
+ * and {@link DoubleStream}, all of which are referred to as "streams" and
+ * conform to the characteristics and restrictions described here.
+ *
* <p>To perform a computation, stream
* <a href="package-summary.html#StreamOps">operations</a> are composed into a
* <em>stream pipeline</em>. A stream pipeline consists of a source (which
@@ -97,14 +102,21 @@
*
* <p>Most stream operations accept parameters that describe user-specified
* behavior, such as the lambda expression {@code w -> w.getWeight()} passed to
- * {@code mapToInt} in the example above. Such parameters are always instances
- * of a <a href="../function/package-summary.html">functional interface</a> such
+ * {@code mapToInt} in the example above. To preserve correct behavior,
+ * these <em>behavioral parameters</em>:
+ * <ul>
+ * <li>must be <a href="package-summary.html#NonInterference">non-interfering</a>
+ * (they do not modify the stream source); and</li>
+ * <li>in most cases must be <a href="package-summary.html#Statelessness">stateless</a>
+ * (their result should not depend on any state that might change during execution
+ * of the stream pipeline).</li>
+ * </ul>
+ *
+ * <p>Such parameters are always instances of a
+ * <a href="../function/package-summary.html">functional interface</a> such
* as {@link java.util.function.Function}, and are often lambda expressions or
- * method references. These parameters can never be null, should not modify the
- * stream source, and should be
- * <a href="package-summary.html#NonInterference">effectively stateless</a>
- * (their result should not depend on any state that might change during
- * execution of the stream pipeline.)
+ * method references. Unless otherwise specified these parameters must be
+ * <em>non-null</em>.
*
* <p>A stream should be operated on (invoking an intermediate or terminal stream
* operation) only once. This rules out, for example, "forked" streams, where
@@ -134,6 +146,9 @@
*
* @param <T> the type of the stream elements
* @since 1.8
+ * @see IntStream
+ * @see LongStream
+ * @see DoubleStream
* @see <a href="package-summary.html">java.util.stream</a>
*/
public interface Stream<T> extends BaseStream<T, Stream<T>> {
@@ -145,9 +160,10 @@
* <p>This is an <a href="package-summary.html#StreamOps">intermediate
* operation</a>.
*
- * @param predicate a <a href="package-summary.html#NonInterference">
- * non-interfering, stateless</a> predicate to apply to
- * each element to determine if it should be included
+ * @param predicate a <a href="package-summary.html#NonInterference">non-interfering</a>,
+ * <a href="package-summary.html#Statelessness">stateless</a>
+ * predicate to apply to each element to determine if it
+ * should be included
* @return the new stream
*/
Stream<T> filter(Predicate<? super T> predicate);
@@ -160,9 +176,9 @@
* operation</a>.
*
* @param <R> The element type of the new stream
- * @param mapper a <a href="package-summary.html#NonInterference">
- * non-interfering, stateless</a> function to apply to each
- * element
+ * @param mapper a <a href="package-summary.html#NonInterference">non-interfering</a>,
+ * <a href="package-summary.html#Statelessness">stateless</a>
+ * function to apply to each element
* @return the new stream
*/
<R> Stream<R> map(Function<? super T, ? extends R> mapper);
@@ -174,9 +190,9 @@
* <p>This is an <a href="package-summary.html#StreamOps">
* intermediate operation</a>.
*
- * @param mapper a <a href="package-summary.html#NonInterference">
- * non-interfering, stateless</a> function to apply to each
- * element
+ * @param mapper a <a href="package-summary.html#NonInterference">non-interfering</a>,
+ * <a href="package-summary.html#Statelessness">stateless</a>
+ * function to apply to each element
* @return the new stream
*/
IntStream mapToInt(ToIntFunction<? super T> mapper);
@@ -188,9 +204,9 @@
* <p>This is an <a href="package-summary.html#StreamOps">intermediate
* operation</a>.
*
- * @param mapper a <a href="package-summary.html#NonInterference">
- * non-interfering, stateless</a> function to apply to each
- * element
+ * @param mapper a <a href="package-summary.html#NonInterference">non-interfering</a>,
+ * <a href="package-summary.html#Statelessness">stateless</a>
+ * function to apply to each element
* @return the new stream
*/
LongStream mapToLong(ToLongFunction<? super T> mapper);
@@ -202,9 +218,9 @@
* <p>This is an <a href="package-summary.html#StreamOps">intermediate
* operation</a>.
*
- * @param mapper a <a href="package-summary.html#NonInterference">
- * non-interfering, stateless</a> function to apply to each
- * element
+ * @param mapper a <a href="package-summary.html#NonInterference">non-interfering</a>,
+ * <a href="package-summary.html#Statelessness">stateless</a>
+ * function to apply to each element
* @return the new stream
*/
DoubleStream mapToDouble(ToDoubleFunction<? super T> mapper);
@@ -221,19 +237,33 @@
*
* @apiNote
* The {@code flatMap()} operation has the effect of applying a one-to-many
- * tranformation to the elements of the stream, and then flattening the
- * resulting elements into a new stream. For example, if {@code orders}
- * is a stream of purchase orders, and each purchase order contains a
- * collection of line items, then the following produces a stream of line
- * items:
+ * transformation to the elements of the stream, and then flattening the
+ * resulting elements into a new stream.
+ *
+ * <p><b>Examples.</b>
+ *
+ * <p>If {@code orders} is a stream of purchase orders, and each purchase
+ * order contains a collection of line items, then the following produces a
+ * stream containing all the line items in all the orders:
* <pre>{@code
- * orderStream.flatMap(order -> order.getLineItems().stream())...
+ * orders.flatMap(order -> order.getLineItems().stream())...
* }</pre>
*
+ * <p>If {@code path} is the path to a file, then the following produces a
+ * stream of the {@code words} contained in that file:
+ * <pre>{@code
+ * Stream<String> lines = Files.lines(path, StandardCharsets.UTF_8);
+ * Stream<String> words = lines.flatMap(line -> Stream.of(line.split(" +")));
+ * }</pre>
+ * The {@code mapper} function passed to {@code flatMap} splits a line,
+ * using a simple regular expression, into an array of words, and then
+ * creates a stream of words from that array.
+ *
* @param <R> The element type of the new stream
- * @param mapper a <a href="package-summary.html#NonInterference">
- * non-interfering, stateless</a> function to apply to each
- * element which produces a stream of new values
+ * @param mapper a <a href="package-summary.html#NonInterference">non-interfering</a>,
+ * <a href="package-summary.html#Statelessness">stateless</a>
+ * function to apply to each element which produces a stream
+ * of new values
* @return the new stream
*/
<R> Stream<R> flatMap(Function<? super T, ? extends Stream<? extends R>> mapper);
@@ -248,10 +278,12 @@
* <p>This is an <a href="package-summary.html#StreamOps">intermediate
* operation</a>.
*
- * @param mapper a <a href="package-summary.html#NonInterference">
- * non-interfering, stateless</a> function to apply to each
- * element which produces a stream of new values
+ * @param mapper a <a href="package-summary.html#NonInterference">non-interfering</a>,
+ * <a href="package-summary.html#Statelessness">stateless</a>
+ * function to apply to each element which produces a stream
+ * of new values
* @return the new stream
+ * @see #flatMap(Function)
*/
IntStream flatMapToInt(Function<? super T, ? extends IntStream> mapper);
@@ -265,10 +297,12 @@
* <p>This is an <a href="package-summary.html#StreamOps">intermediate
* operation</a>.
*
- * @param mapper a <a href="package-summary.html#NonInterference">
- * non-interfering, stateless</a> function to apply to
- * each element which produces a stream of new values
+ * @param mapper a <a href="package-summary.html#NonInterference">non-interfering</a>,
+ * <a href="package-summary.html#Statelessness">stateless</a>
+ * function to apply to each element which produces a stream
+ * of new values
* @return the new stream
+ * @see #flatMap(Function)
*/
LongStream flatMapToLong(Function<? super T, ? extends LongStream> mapper);
@@ -282,10 +316,12 @@
* <p>This is an <a href="package-summary.html#StreamOps">intermediate
* operation</a>.
*
- * @param mapper a <a href="package-summary.html#NonInterference">
- * non-interfering, stateless</a> function to apply to each
- * element which produces a stream of new values
+ * @param mapper a <a href="package-summary.html#NonInterference">non-interfering</a>,
+ * <a href="package-summary.html#Statelessness">stateless</a>
+ * function to apply to each element which produces a stream
+ * of new values
* @return the new stream
+ * @see #flatMap(Function)
*/
DoubleStream flatMapToDouble(Function<? super T, ? extends DoubleStream> mapper);
@@ -293,9 +329,27 @@
* Returns a stream consisting of the distinct elements (according to
* {@link Object#equals(Object)}) of this stream.
*
+ * <p>For ordered streams, the selection of distinct elements is stable
+ * (for duplicated elements, the element appearing first in the encounter
+ * order is preserved.) For unordered streams, no stability guarantees
+ * are made.
+ *
* <p>This is a <a href="package-summary.html#StreamOps">stateful
* intermediate operation</a>.
*
+ * @apiNote
+ * Preserving stability for {@code distinct()} in parallel pipelines is
+ * relatively expensive (requires that the operation act as a full barrier,
+ * with substantial buffering overhead), and stability is often not needed.
+ * Using an unordered stream source (such as {@link #generate(Supplier)})
+ * or removing the ordering constraint with {@link #unordered()} may result
+ * in significantly more efficient execution for {@code distinct()} in parallel
+ * pipelines, if the semantics of your situation permit. If consistency
+ * with encounter order is required, and you are experiencing poor performance
+ * or memory utilization with {@code distinct()} in parallel pipelines,
+ * switching to sequential execution with {@link #sequential()} may improve
+ * performance.
+ *
* @return the new stream
*/
Stream<T> distinct();
@@ -306,6 +360,9 @@
* {@code Comparable}, a {@code java.lang.ClassCastException} may be thrown
* when the terminal operation is executed.
*
+ * <p>For ordered streams, the sort is stable. For unordered streams, no
+ * stability guarantees are made.
+ *
* <p>This is a <a href="package-summary.html#StreamOps">stateful
* intermediate operation</a>.
*
@@ -317,12 +374,15 @@
* Returns a stream consisting of the elements of this stream, sorted
* according to the provided {@code Comparator}.
*
+ * <p>For ordered streams, the sort is stable. For unordered streams, no
+ * stability guarantees are made.
+ *
* <p>This is a <a href="package-summary.html#StreamOps">stateful
* intermediate operation</a>.
*
- * @param comparator a <a href="package-summary.html#NonInterference">
- * non-interfering, stateless</a> {@code Comparator} to
- * be used to compare stream elements
+ * @param comparator a <a href="package-summary.html#NonInterference">non-interfering</a>,
+ * <a href="package-summary.html#Statelessness">stateless</a>
+ * {@code Comparator} to be used to compare stream elements
* @return the new stream
*/
Stream<T> sorted(Comparator<? super T> comparator);
@@ -420,7 +480,8 @@
* <p>This is a <a href="package-summary.html#StreamOps">terminal
* operation</a>.
*
- * <p>For parallel stream pipelines, this operation does <em>not</em>
+ * <p>The behavior of this operation is explicitly nondeterministic.
+ * For parallel stream pipelines, this operation does <em>not</em>
* guarantee to respect the encounter order of the stream, as doing so
* would sacrifice the benefit of parallelism. For any given element, the
* action may be performed at whatever time and in whatever thread the
@@ -433,13 +494,18 @@
void forEach(Consumer<? super T> action);
/**
- * Performs an action for each element of this stream, guaranteeing that
- * each element is processed in encounter order for streams that have a
- * defined encounter order.
+ * Performs an action for each element of this stream, in the encounter
+ * order of the stream if the stream has a defined encounter order.
*
* <p>This is a <a href="package-summary.html#StreamOps">terminal
* operation</a>.
*
+ * <p>This operation processes the elements one at a time, in encounter
+ * order if one exists. Performing the action for one element
+ * <a href="../concurrent/package-summary.html#MemoryVisibility"><i>happens-before</i></a>
+ * performing the action for subsequent elements, but for any given element,
+ * the action may be performed in whatever thread the library chooses.
+ *
* @param action a <a href="package-summary.html#NonInterference">
* non-interfering</a> action to perform on the elements
* @see #forEach(Consumer)
@@ -528,9 +594,10 @@
* synchronization and with greatly reduced risk of data races.
*
* @param identity the identity value for the accumulating function
- * @param accumulator an <a href="package-summary.html#Associativity">associative</a>
- * <a href="package-summary.html#NonInterference">non-interfering,
- * stateless</a> function for combining two values
+ * @param accumulator an <a href="package-summary.html#Associativity">associative</a>,
+ * <a href="package-summary.html#NonInterference">non-interfering</a>,
+ * <a href="package-summary.html#Statelessness">stateless</a>
+ * function for combining two values
* @return the result of the reduction
*/
T reduce(T identity, BinaryOperator<T> accumulator);
@@ -563,14 +630,15 @@
* <p>This is a <a href="package-summary.html#StreamOps">terminal
* operation</a>.
*
- * @param accumulator an <a href="package-summary.html#Associativity">associative</a>
- * <a href="package-summary.html#NonInterference">non-interfering,
- * stateless</a> function for combining two values
+ * @param accumulator an <a href="package-summary.html#Associativity">associative</a>,
+ * <a href="package-summary.html#NonInterference">non-interfering</a>,
+ * <a href="package-summary.html#Statelessness">stateless</a>
+ * function for combining two values
* @return an {@link Optional} describing the result of the reduction
* @throws NullPointerException if the result of the reduction is null
* @see #reduce(Object, BinaryOperator)
- * @see #min(java.util.Comparator)
- * @see #max(java.util.Comparator)
+ * @see #min(Comparator)
+ * @see #max(Comparator)
*/
Optional<T> reduce(BinaryOperator<T> accumulator);
@@ -608,14 +676,15 @@
*
* @param <U> The type of the result
* @param identity the identity value for the combiner function
- * @param accumulator an <a href="package-summary.html#Associativity">associative</a>
- * <a href="package-summary.html#NonInterference">non-interfering,
- * stateless</a> function for incorporating an additional
- * element into a result
- * @param combiner an <a href="package-summary.html#Associativity">associative</a>
- * <a href="package-summary.html#NonInterference">non-interfering,
- * stateless</a> function for combining two values, which
- * must be compatible with the accumulator function
+ * @param accumulator an <a href="package-summary.html#Associativity">associative</a>,
+ * <a href="package-summary.html#NonInterference">non-interfering</a>,
+ * <a href="package-summary.html#Statelessness">stateless</a>
+ * function for incorporating an additional element into a result
+ * @param combiner an <a href="package-summary.html#Associativity">associative</a>,
+ * <a href="package-summary.html#NonInterference">non-interfering</a>,
+ * <a href="package-summary.html#Statelessness">stateless</a>
+ * function for combining two values, which must be
+ * compatible with the accumulator function
* @return the result of the reduction
* @see #reduce(BinaryOperator)
* @see #reduce(Object, BinaryOperator)
@@ -664,14 +733,15 @@
* @param supplier a function that creates a new result container. For a
* parallel execution, this function may be called
* multiple times and must return a fresh value each time.
- * @param accumulator an <a href="package-summary.html#Associativity">associative</a>
- * <a href="package-summary.html#NonInterference">non-interfering,
- * stateless</a> function for incorporating an additional
- * element into a result
- * @param combiner an <a href="package-summary.html#Associativity">associative</a>
- * <a href="package-summary.html#NonInterference">non-interfering,
- * stateless</a> function for combining two values, which
- * must be compatible with the accumulator function
+ * @param accumulator an <a href="package-summary.html#Associativity">associative</a>,
+ * <a href="package-summary.html#NonInterference">non-interfering</a>,
+ * <a href="package-summary.html#Statelessness">stateless</a>
+ * function for incorporating an additional element into a result
+ * @param combiner an <a href="package-summary.html#Associativity">associative</a>,
+ * <a href="package-summary.html#NonInterference">non-interfering</a>,
+ * <a href="package-summary.html#Statelessness">stateless</a>
+ * function for combining two values, which must be
+ * compatible with the accumulator function
* @return the result of the reduction
*/
<R> R collect(Supplier<R> supplier,
@@ -687,6 +757,13 @@
* collection strategies and composition of collect operations such as
* multiple-level grouping or partitioning.
*
+ * <p>If the stream is parallel, and the {@code Collector}
+ * is {@link Collector.Characteristics#CONCURRENT concurrent}, and
+ * either the stream is unordered or the collector is
+ * {@link Collector.Characteristics#UNORDERED unordered},
+ * then a concurrent reduction will be performed (see {@link Collector} for
+ * details on concurrent reduction.)
+ *
* <p>This is a <a href="package-summary.html#StreamOps">terminal
* operation</a>.
*
@@ -732,9 +809,9 @@
*
* <p>This is a <a href="package-summary.html#StreamOps">terminal operation</a>.
*
- * @param comparator a <a href="package-summary.html#NonInterference">non-interfering,
- * stateless</a> {@code Comparator} to use to compare
- * elements of this stream
+ * @param comparator a <a href="package-summary.html#NonInterference">non-interfering</a>,
+ * <a href="package-summary.html#Statelessness">stateless</a>
+ * {@code Comparator} to compare elements of this stream
* @return an {@code Optional} describing the minimum element of this stream,
* or an empty {@code Optional} if the stream is empty
* @throws NullPointerException if the minimum element is null
@@ -749,9 +826,9 @@
* <p>This is a <a href="package-summary.html#StreamOps">terminal
* operation</a>.
*
- * @param comparator a <a href="package-summary.html#NonInterference">non-interfering,
- * stateless</a> {@code Comparator} to use to compare
- * elements of this stream
+ * @param comparator a <a href="package-summary.html#NonInterference">non-interfering</a>,
+ * <a href="package-summary.html#Statelessness">stateless</a>
+ * {@code Comparator} to compare elements of this stream
* @return an {@code Optional} describing the maximum element of this stream,
* or an empty {@code Optional} if the stream is empty
* @throws NullPointerException if the maximum element is null
@@ -775,48 +852,67 @@
/**
* Returns whether any elements of this stream match the provided
* predicate. May not evaluate the predicate on all elements if not
- * necessary for determining the result.
+ * necessary for determining the result. If the stream is empty then
+ * {@code false} is returned and the predicate is not evaluated.
*
* <p>This is a <a href="package-summary.html#StreamOps">short-circuiting
* terminal operation</a>.
*
- * @param predicate a <a href="package-summary.html#NonInterference">non-interfering,
- * stateless</a> predicate to apply to elements of this
- * stream
+ * @apiNote
+ * This method evaluates the <em>existential quantification</em> of the
+ * predicate over the elements of the stream (for some x P(x)).
+ *
+ * @param predicate a <a href="package-summary.html#NonInterference">non-interfering</a>,
+ * <a href="package-summary.html#Statelessness">stateless</a>
+ * predicate to apply to elements of this stream
* @return {@code true} if any elements of the stream match the provided
- * predicate otherwise {@code false}
+ * predicate, otherwise {@code false}
*/
boolean anyMatch(Predicate<? super T> predicate);
/**
* Returns whether all elements of this stream match the provided predicate.
* May not evaluate the predicate on all elements if not necessary for
- * determining the result.
+ * determining the result. If the stream is empty then {@code true} is
+ * returned and the predicate is not evaluated.
*
* <p>This is a <a href="package-summary.html#StreamOps">short-circuiting
* terminal operation</a>.
*
- * @param predicate a <a href="package-summary.html#NonInterference">non-interfering,
- * stateless</a> predicate to apply to elements of this
- * stream
- * @return {@code true} if all elements of the stream match the provided
- * predicate otherwise {@code false}
+ * @apiNote
+ * This method evaluates the <em>universal quantification</em> of the
+ * predicate over the elements of the stream (for all x P(x)). If the
+ * stream is empty, the quantification is said to be <em>vacuously
+ * satisfied</em> and is always {@code true} (regardless of P(x)).
+ *
+ * @param predicate a <a href="package-summary.html#NonInterference">non-interfering</a>,
+ * <a href="package-summary.html#Statelessness">stateless</a>
+ * predicate to apply to elements of this stream
+ * @return {@code true} if either all elements of the stream match the
+ * provided predicate or the stream is empty, otherwise {@code false}
*/
boolean allMatch(Predicate<? super T> predicate);
/**
* Returns whether no elements of this stream match the provided predicate.
* May not evaluate the predicate on all elements if not necessary for
- * determining the result.
+ * determining the result. If the stream is empty then {@code true} is
+ * returned and the predicate is not evaluated.
*
* <p>This is a <a href="package-summary.html#StreamOps">short-circuiting
* terminal operation</a>.
*
- * @param predicate a <a href="package-summary.html#NonInterference">non-interfering,
- * stateless</a> predicate to apply to elements of this
- * stream
- * @return {@code true} if no elements of the stream match the provided
- * predicate otherwise {@code false}
+ * @apiNote
+ * This method evaluates the <em>universal quantification</em> of the
+ * negated predicate over the elements of the stream (for all x ~P(x)). If
+ * the stream is empty, the quantification is said to be vacuously satisfied
+ * and is always {@code true}, regardless of P(x).
+ *
+ * @param predicate a <a href="package-summary.html#NonInterference">non-interfering</a>,
+ * <a href="package-summary.html#Statelessness">stateless</a>
+ * predicate to apply to elements of this stream
+ * @return {@code true} if either no elements of the stream match the
+ * provided predicate or the stream is empty, otherwise {@code false}
*/
boolean noneMatch(Predicate<? super T> predicate);
@@ -939,13 +1035,13 @@
}
/**
- * Returns a sequential stream where each element is generated by
- * the provided {@code Supplier}. This is suitable for generating
- * constant streams, streams of random elements, etc.
+ * Returns an infinite sequential unordered stream where each element is
+ * generated by the provided {@code Supplier}. This is suitable for
+ * generating constant streams, streams of random elements, etc.
*
* @param <T> the type of stream elements
* @param s the {@code Supplier} of generated elements
- * @return a new sequential {@code Stream}
+ * @return a new infinite sequential unordered {@code Stream}
*/
public static<T> Stream<T> generate(Supplier<T> s) {
Objects.requireNonNull(s);
@@ -956,11 +1052,16 @@
/**
* Creates a lazily concatenated stream whose elements are all the
* elements of the first stream followed by all the elements of the
- * second stream. The resulting stream is ordered if both
+ * second stream. The resulting stream is ordered if both
* of the input streams are ordered, and parallel if either of the input
* streams is parallel. When the resulting stream is closed, the close
* handlers for both input streams are invoked.
*
+ * @implNote
+ * Use caution when constructing streams from repeated concatenation.
+ * Accessing an element of a deeply concatenated stream can result in deep
+ * call chains, or even {@code StackOverflowException}.
+ *
* @param <T> The type of stream elements
* @param a the first stream
* @param b the second stream
--- a/jdk/src/share/classes/java/util/stream/StreamSupport.java Tue Oct 22 19:37:11 2013 -0400
+++ b/jdk/src/share/classes/java/util/stream/StreamSupport.java Tue Oct 22 19:43:42 2013 -0400
@@ -96,7 +96,8 @@
* @param supplier a {@code Supplier} of a {@code Spliterator}
* @param characteristics Spliterator characteristics of the supplied
* {@code Spliterator}. The characteristics must be equal to
- * {@code supplier.get().characteristics()}.
+ * {@code supplier.get().characteristics()}, otherwise undefined
+ * behavior may occur when terminal operation commences.
* @param parallel if {@code true} then the returned stream is a parallel
* stream; if {@code false} the returned stream is a sequential
* stream.
@@ -163,7 +164,8 @@
* @param supplier a {@code Supplier} of a {@code Spliterator.OfInt}
* @param characteristics Spliterator characteristics of the supplied
* {@code Spliterator.OfInt}. The characteristics must be equal to
- * {@code supplier.get().characteristics()}
+ * {@code supplier.get().characteristics()}, otherwise undefined
+ * behavior may occur when terminal operation commences.
* @param parallel if {@code true} then the returned stream is a parallel
* stream; if {@code false} the returned stream is a sequential
* stream.
@@ -230,7 +232,8 @@
* @param supplier a {@code Supplier} of a {@code Spliterator.OfLong}
* @param characteristics Spliterator characteristics of the supplied
* {@code Spliterator.OfLong}. The characteristics must be equal to
- * {@code supplier.get().characteristics()}
+ * {@code supplier.get().characteristics()}, otherwise undefined
+ * behavior may occur when terminal operation commences.
* @param parallel if {@code true} then the returned stream is a parallel
* stream; if {@code false} the returned stream is a sequential
* stream.
@@ -297,7 +300,8 @@
* @param supplier A {@code Supplier} of a {@code Spliterator.OfDouble}
* @param characteristics Spliterator characteristics of the supplied
* {@code Spliterator.OfDouble}. The characteristics must be equal to
- * {@code supplier.get().characteristics()}
+ * {@code supplier.get().characteristics()}, otherwise undefined
+ * behavior may occur when terminal operation commences.
* @param parallel if {@code true} then the returned stream is a parallel
* stream; if {@code false} the returned stream is a sequential
* stream.
--- a/jdk/src/share/classes/java/util/stream/package-info.java Tue Oct 22 19:37:11 2013 -0400
+++ b/jdk/src/share/classes/java/util/stream/package-info.java Tue Oct 22 19:43:42 2013 -0400
@@ -219,31 +219,18 @@
* <em>not modified at all</em> during the execution of the stream pipeline.
* The notable exception to this are streams whose sources are concurrent
* collections, which are specifically designed to handle concurrent modification.
+ * Concurrent stream sources are those whose {@code Spliterator} reports the
+ * {@code CONCURRENT} characteristic.
*
- * <p>Accordingly, behavioral parameters passed to stream methods should never
- * modify the stream's data source. An implementation is said to
- * <em>interfere</em> with the data source if it modifies, or causes to be
+ * <p>Accordingly, behavioral parameters in stream pipelines whose source might
+ * not be concurrent should never modify the stream's data source.
+ * A behavioral parameter is said to <em>interfere</em> with a non-concurrent
+ * data source if it modifies, or causes to be
* modified, the stream's data source. The need for non-interference applies
* to all pipelines, not just parallel ones. Unless the stream source is
* concurrent, modifying a stream's data source during execution of a stream
* pipeline can cause exceptions, incorrect answers, or nonconformant behavior.
*
- * <p>Results may be nondeterministic or incorrect if the behavioral
- * parameters of stream operations are <em>stateful</em>. A stateful lambda
- * (or other object implementing the appropriate functional interface) is one
- * whose result depends on any state which might change during the execution
- * of the stream pipeline. An example of a stateful lambda is:
- *
- * <pre>{@code
- * Set<Integer> seen = Collections.synchronizedSet(new HashSet<>());
- * stream.parallel().map(e -> { if (seen.add(e)) return 0; else return e; })...
- * }</pre>
- *
- * Here, if the mapping operation is performed in parallel, the results for the
- * same input could vary from run to run, due to thread scheduling differences,
- * whereas, with a stateless lambda expression the results would always be the
- * same.
- *
* For well-behaved stream sources, the source can be modified before the
* terminal operation commences and those modifications will be reflected in
* the covered elements. For example, consider the following code:
@@ -265,26 +252,54 @@
* <a href="package-summary.html#StreamSources">Low-level stream
* construction</a> for requirements for building well-behaved streams.
*
- * <p>Some streams, particularly those whose stream sources are concurrent, can
- * tolerate concurrent modification during execution of a stream pipeline.
- * However, in no case -- even if the stream source is concurrent -- should
- * behavioral parameters to stream operations modify the stream source. Modifying
- * the stream source from within the stream source may cause pipeline execution
- * to fail to terminate, produce inaccurate results, or throw exceptions.
- * The following example shows inappropriate interference with the source:
+ * <h3><a name="Statelessness">Stateless behaviors</a></h3>
+ *
+ * Stream pipeline results may be nondeterministic or incorrect if the behavioral
+ * parameters to the stream operations are <em>stateful</em>. A stateful lambda
+ * (or other object implementing the appropriate functional interface) is one
+ * whose result depends on any state which might change during the execution
+ * of the stream pipeline. An example of a stateful lambda is the parameter
+ * to {@code map()} in:
+ *
* <pre>{@code
- * // Don't do this!
- * List<String> l = new ArrayList(Arrays.asList("one", "two"));
- * Stream<String> sl = l.stream();
- * String s = sl.peek(s -> l.add("BAD LAMBDA")).collect(joining(" "));
+ * Set<Integer> seen = Collections.synchronizedSet(new HashSet<>());
+ * stream.parallel().map(e -> { if (seen.add(e)) return 0; else return e; })...
* }</pre>
*
+ * Here, if the mapping operation is performed in parallel, the results for the
+ * same input could vary from run to run, due to thread scheduling differences,
+ * whereas, with a stateless lambda expression the results would always be the
+ * same.
+ *
+ * <p>Note also that attempting to access mutable state from behavioral parameters
+ * presents you with a bad choice with respect to safety and performance; if
+ * you do not synchronize access to that state, you have a data race and
+ * therefore your code is broken, but if you do synchronize access to that
+ * state, you risk having contention undermine the parallelism you are seeking
+ * to benefit from. The best approach is to avoid stateful behavioral
+ * parameters to stream operations entirely; there is usually a way to
+ * restructure the stream pipeline to avoid statefulness.
+ *
* <h3>Side-effects</h3>
*
* Side-effects in behavioral parameters to stream operations are, in general,
* discouraged, as they can often lead to unwitting violations of the
- * statelessness requirement, as well as other thread-safety hazards. Many
- * computations where one might be tempted to use side effects can be more
+ * statelessness requirement, as well as other thread-safety hazards.
+ *
+ * <p>If the behavioral parameters do have side-effects, unless explicitly
+ * stated, there are no guarantees as to the
+ * <a href="../concurrent/package-summary.html#MemoryVisibility"><i>visibility</i></a>
+ * of those side-effects to other threads, nor are there any guarantees that
+ * different operations on the "same" element within the same stream pipeline
+ * are executed in the same thread. Further, the ordering of those effects
+ * may be surprising. Even when a pipeline is constrained to produce a
+ * <em>result</em> that is consistent with the encounter order of the stream
+ * source (for example, {@code IntStream.range(0,5).parallel().map(x -> x*2).toArray()}
+ * must produce {@code [0, 2, 4, 6, 8]}), no guarantees are made as to the order
+ * in which the mapper function is applied to individual elements, or in what
+ * thread any behavioral parameter is executed for a given element.
+ *
+ * <p>Many computations where one might be tempted to use side effects can be more
* safely and efficiently expressed without side-effects, such as using
* <a href="package-summary.html#Reduction">reduction</a> instead of mutable
* accumulators. However, side-effects such as using {@code println()} for debugging
--- a/jdk/src/share/classes/sun/security/tools/jarsigner/Resources_ja.java Tue Oct 22 19:37:11 2013 -0400
+++ b/jdk/src/share/classes/sun/security/tools/jarsigner/Resources_ja.java Tue Oct 22 19:43:42 2013 -0400
@@ -79,7 +79,7 @@
{".verbose.suboptions.verbose.output.when.signing.verifying.",
"[-verbose[:suboptions]] \u7F72\u540D/\u691C\u8A3C\u6642\u306E\u8A73\u7D30\u51FA\u529B\u3002"},
{".suboptions.can.be.all.grouped.or.summary",
- " \u30B5\u30D6\u30AA\u30D7\u30B7\u30E7\u30F3\u3068\u3057\u3066\u3001\u3059\u3079\u3066\u3001\u30B0\u30EB\u30FC\u30D7\u307E\u305F\u306F\u30B5\u30DE\u30EA\u30FC\u3092\u4F7F\u7528\u3067\u304D\u307E\u3059"},
+ " \u30B5\u30D6\u30AA\u30D7\u30B7\u30E7\u30F3\u3068\u3057\u3066\u3001all\u3001grouped\u307E\u305F\u306Fsummary\u3092\u4F7F\u7528\u3067\u304D\u307E\u3059"},
{".certs.display.certificates.when.verbose.and.verifying",
"[-certs] \u8A73\u7D30\u51FA\u529B\u304A\u3088\u3073\u691C\u8A3C\u6642\u306B\u8A3C\u660E\u66F8\u3092\u8868\u793A"},
{".tsa.url.location.of.the.Timestamping.Authority",
--- a/jdk/src/share/demo/jfc/Notepad/resources/Notepad_fr.properties Tue Oct 22 19:37:11 2013 -0400
+++ /dev/null Thu Jan 01 00:00:00 1970 +0000
@@ -1,17 +0,0 @@
-#
-# Resource strings for Notepad example
-
-Title=Notepad
-
-# Menu labels
-fileLabel=Fichier
-openLabel=Ouvrir
-newLabel=Nouveau
-saveLabel=Sauver
-exitLabel=Quitter
-
-editLabel=Edition
-cutLabel=Couper
-copyLabel=Copier
-pasteLabel=Coller
-
--- a/jdk/src/share/demo/jfc/Notepad/resources/Notepad_sv.properties Tue Oct 22 19:37:11 2013 -0400
+++ /dev/null Thu Jan 01 00:00:00 1970 +0000
@@ -1,17 +0,0 @@
-#
-# Resource strings for Notepad example
-
-Title=Notepad
-
-# Menu labels
-fileLabel=Arkiv
-openLabel=Öppna
-newLabel=Ny
-saveLabel=Spara
-exitLabel=Avsluta
-
-editLabel=Redigera
-cutLabel=Klippa
-copyLabel=Kopiera
-pasteLabel=Klistra
-
--- a/jdk/test/java/time/tck/java/time/serial/TCKOffsetDateTimeSerialization.java Tue Oct 22 19:37:11 2013 -0400
+++ b/jdk/test/java/time/tck/java/time/serial/TCKOffsetDateTimeSerialization.java Tue Oct 22 19:43:42 2013 -0400
@@ -59,9 +59,6 @@
*/
package tck.java.time.serial;
-import org.testng.annotations.BeforeMethod;
-import org.testng.annotations.Test;
-import tck.java.time.AbstractTCKTest;
import java.io.ByteArrayOutputStream;
import java.io.DataOutputStream;
@@ -69,6 +66,10 @@
import java.time.OffsetDateTime;
import java.time.ZoneOffset;
+import org.testng.annotations.BeforeMethod;
+import org.testng.annotations.Test;
+import tck.java.time.AbstractTCKTest;
+
/**
* Test OffsetDateTime serialization.
*/
@@ -96,11 +97,6 @@
ByteArrayOutputStream baos = new ByteArrayOutputStream();
try (DataOutputStream dos = new DataOutputStream(baos) ) {
dos.writeByte(10); // java.time.Ser.OFFSET_DATE_TIME_TYPE
- }
- byte[] bytes = baos.toByteArray();
- ByteArrayOutputStream baosDateTime = new ByteArrayOutputStream();
- try (DataOutputStream dos = new DataOutputStream(baosDateTime) ) {
- dos.writeByte(5);
dos.writeInt(2012);
dos.writeByte(9);
dos.writeByte(16);
@@ -108,17 +104,11 @@
dos.writeByte(17);
dos.writeByte(59);
dos.writeInt(464_000_000);
- }
- byte[] bytesDateTime = baosDateTime.toByteArray();
- ByteArrayOutputStream baosOffset = new ByteArrayOutputStream();
- try (DataOutputStream dos = new DataOutputStream(baosOffset) ) {
- dos.writeByte(8);
dos.writeByte(4); // quarter hours stored: 3600 / 900
}
- byte[] bytesOffset = baosOffset.toByteArray();
+ byte[] bytes = baos.toByteArray();
LocalDateTime ldt = LocalDateTime.of(2012, 9, 16, 22, 17, 59, 464_000_000);
- assertSerializedBySer(OffsetDateTime.of(ldt, ZoneOffset.ofHours(1)), bytes, bytesDateTime, bytesOffset);
+ assertSerializedBySer(OffsetDateTime.of(ldt, ZoneOffset.ofHours(1)), bytes);
}
-
}
--- a/jdk/test/java/time/tck/java/time/serial/TCKOffsetTimeSerialization.java Tue Oct 22 19:37:11 2013 -0400
+++ b/jdk/test/java/time/tck/java/time/serial/TCKOffsetTimeSerialization.java Tue Oct 22 19:43:42 2013 -0400
@@ -97,25 +97,14 @@
ByteArrayOutputStream baos = new ByteArrayOutputStream();
try (DataOutputStream dos = new DataOutputStream(baos) ) {
dos.writeByte(9); // java.time.Ser.OFFSET_TIME_TYPE
- }
- byte[] bytes = baos.toByteArray();
- ByteArrayOutputStream baosTime = new ByteArrayOutputStream();
- try (DataOutputStream dos = new DataOutputStream(baosTime) ) {
- dos.writeByte(4);
dos.writeByte(22);
dos.writeByte(17);
dos.writeByte(59);
dos.writeInt(464_000_000);
- }
- byte[] bytesTime = baosTime.toByteArray();
- ByteArrayOutputStream baosOffset = new ByteArrayOutputStream();
- try (DataOutputStream dos = new DataOutputStream(baosOffset) ) {
- dos.writeByte(8);
dos.writeByte(4); // quarter hours stored: 3600 / 900
}
- byte[] bytesOffset = baosOffset.toByteArray();
- assertSerializedBySer(OffsetTime.of(22, 17, 59, 464_000_000, ZoneOffset.ofHours(1)), bytes,
- bytesTime, bytesOffset);
+ byte[] bytes = baos.toByteArray();
+ assertSerializedBySer(OffsetTime.of(22, 17, 59, 464_000_000, ZoneOffset.ofHours(1)), bytes);
}