--- old/src/share/classes/java/io/RandomAccessFile.java 2012-01-23 09:34:29.000000000 -0800
+++ new/src/share/classes/java/io/RandomAccessFile.java 2012-01-23 09:34:29.000000000 -0800
@@ -1,5 +1,5 @@
/*
- * Copyright (c) 1994, 2011, Oracle and/or its affiliates. All rights reserved.
+ * Copyright (c) 1994, 2012, 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
@@ -41,16 +41,16 @@
* the file pointer past the bytes written. Output operations that write
* past the current end of the implied array cause the array to be
* extended. The file pointer can be read by the
- * getFilePointer
method and set by the seek
+ * {@code getFilePointer} method and set by the {@code seek}
* method.
*
* It is generally true of all the reading routines in this class that
* if end-of-file is reached before the desired number of bytes has been
- * read, an EOFException
(which is a kind of
- * IOException
) is thrown. If any byte cannot be read for
- * any reason other than end-of-file, an IOException
other
- * than EOFException
is thrown. In particular, an
- * IOException
may be thrown if the stream has been closed.
+ * read, an {@code EOFException} (which is a kind of
+ * {@code IOException}) is thrown. If any byte cannot be read for
+ * any reason other than end-of-file, an {@code IOException} other
+ * than {@code EOFException} is thrown. In particular, an
+ * {@code IOException} may be thrown if the stream has been closed.
*
* @author unascribed
* @since JDK1.0
@@ -82,12 +82,12 @@
* href="#mode">RandomAccessFile(File,String) constructor.
*
*
- * If there is a security manager, its checkRead
method
- * is called with the name
argument
+ * If there is a security manager, its {@code checkRead} method
+ * is called with the {@code name} argument
* as its argument to see if read access to the file is allowed.
* If the mode allows writing, the security manager's
- * checkWrite
method
- * is also called with the name
argument
+ * {@code checkWrite} method
+ * is also called with the {@code name} argument
* as its argument to see if write access to the file is allowed.
*
* @param name the system-dependent filename
@@ -103,9 +103,9 @@
* that name cannot be created, or if some other error occurs
* while opening or creating the file
* @exception SecurityException if a security manager exists and its
- * checkRead
method denies read access to the file
+ * {@code checkRead} method denies read access to the file
* or the mode is "rw" and the security manager's
- * checkWrite
method denies write access to the file
+ * {@code checkWrite} method denies write access to the file
* @see java.lang.SecurityException
* @see java.lang.SecurityManager#checkRead(java.lang.String)
* @see java.lang.SecurityManager#checkWrite(java.lang.String)
@@ -164,10 +164,10 @@
* updates to both the file's content and its metadata to be written, which
* generally requires at least one more low-level I/O operation.
*
- *
If there is a security manager, its checkRead
method is
- * called with the pathname of the file
argument as its
+ *
If there is a security manager, its {@code checkRead} method is
+ * called with the pathname of the {@code file} argument as its
* argument to see if read access to the file is allowed. If the mode
- * allows writing, the security manager's checkWrite
method is
+ * allows writing, the security manager's {@code checkWrite} method is
* also called with the path argument to see if write access to the file is
* allowed.
*
@@ -185,9 +185,9 @@
* that name cannot be created, or if some other error occurs
* while opening or creating the file
* @exception SecurityException if a security manager exists and its
- * checkRead
method denies read access to the file
+ * {@code checkRead} method denies read access to the file
* or the mode is "rw" and the security manager's
- * checkWrite
method denies write access to the file
+ * {@code checkWrite} method denies write access to the file
* @see java.lang.SecurityManager#checkRead(java.lang.String)
* @see java.lang.SecurityManager#checkWrite(java.lang.String)
* @see java.nio.channels.FileChannel#force(boolean)
@@ -253,7 +253,7 @@
* object associated with this file.
*
*
The {@link java.nio.channels.FileChannel#position()
- * position
- * Although
- * Although
- * Although
*
* This method may skip over some smaller number of bytes, possibly zero.
* This may result from any of a number of conditions; reaching end of
- * file before If the present length of the file as returned by the
- * If the present length of the file as returned by the
- *
* This method blocks until the four bytes are read, the end of the
* stream is detected, or an exception is thrown.
*
* @return the next four bytes of this file, interpreted as a
- *
* This method blocks until the eight bytes are read, the end of the
* stream is detected, or an exception is thrown.
*
* @return the next eight bytes of this file, interpreted as a
- * A line of text is terminated by a carriage-return character
- * (
* The first two bytes are read, starting from the current file
* pointer, as if by
- *
* First, two bytes are written to the file, starting at the
* current file pointer, as if by the
- * } of the returned channel will always be equal to
+ * position} of the returned channel will always be equal to
* this object's file-pointer offset as returned by the {@link
* #getFilePointer getFilePointer} method. Changing this object's
* file-pointer offset, whether explicitly or by reading or writing bytes,
@@ -277,9 +277,9 @@
/**
* Opens a file and returns the file descriptor. The file is
- * opened in read-write mode if the O_RDWR bit in
mode
+ * opened in read-write mode if the O_RDWR bit in {@code mode}
* is true, else the file is opened as read-only.
- * If the name
refers to a directory, an IOException
+ * If the {@code name} refers to a directory, an IOException
* is thrown.
*
* @param name the name of the file
@@ -293,15 +293,15 @@
/**
* Reads a byte of data from this file. The byte is returned as an
- * integer in the range 0 to 255 (0x00-0x0ff
). This
+ * integer in the range 0 to 255 ({@code 0x00-0x0ff}). This
* method blocks if no input is yet available.
* RandomAccessFile
is not a subclass of
- * InputStream
, this method behaves in exactly the same
+ * Although {@code RandomAccessFile} is not a subclass of
+ * {@code InputStream}, this method behaves in exactly the same
* way as the {@link InputStream#read()} method of
- * InputStream
.
+ * {@code InputStream}.
*
- * @return the next byte of data, or -1
if the end of the
+ * @return the next byte of data, or {@code -1} if the end of the
* file has been reached.
* @exception IOException if an I/O error occurs. Not thrown if
* end-of-file has been reached.
@@ -318,59 +318,59 @@
private native int readBytes(byte b[], int off, int len) throws IOException;
/**
- * Reads up to len
bytes of data from this file into an
+ * Reads up to {@code len} bytes of data from this file into an
* array of bytes. This method blocks until at least one byte of input
* is available.
* RandomAccessFile
is not a subclass of
- * InputStream
, this method behaves in exactly the
+ * Although {@code RandomAccessFile} is not a subclass of
+ * {@code InputStream}, this method behaves in exactly the
* same way as the {@link InputStream#read(byte[], int, int)} method of
- * InputStream
.
+ * {@code InputStream}.
*
* @param b the buffer into which the data is read.
- * @param off the start offset in array b
+ * @param off the start offset in array {@code b}
* at which the data is written.
* @param len the maximum number of bytes read.
* @return the total number of bytes read into the buffer, or
- * -1
if there is no more data because the end of
+ * {@code -1} if there is no more data because the end of
* the file has been reached.
* @exception IOException If the first byte cannot be read for any reason
* other than end of file, or if the random access file has been closed, or if
* some other I/O error occurs.
- * @exception NullPointerException If b
is null
.
- * @exception IndexOutOfBoundsException If off
is negative,
- * len
is negative, or len
is greater than
- * b.length - off
+ * @exception NullPointerException If {@code b} is {@code null}.
+ * @exception IndexOutOfBoundsException If {@code off} is negative,
+ * {@code len} is negative, or {@code len} is greater than
+ * {@code b.length - off}
*/
public int read(byte b[], int off, int len) throws IOException {
return readBytes(b, off, len);
}
/**
- * Reads up to b.length
bytes of data from this file
+ * Reads up to {@code b.length} bytes of data from this file
* into an array of bytes. This method blocks until at least one byte
* of input is available.
* RandomAccessFile
is not a subclass of
- * InputStream
, this method behaves in exactly the
+ * Although {@code RandomAccessFile} is not a subclass of
+ * {@code InputStream}, this method behaves in exactly the
* same way as the {@link InputStream#read(byte[])} method of
- * InputStream
.
+ * {@code InputStream}.
*
* @param b the buffer into which the data is read.
* @return the total number of bytes read into the buffer, or
- * -1
if there is no more data because the end of
+ * {@code -1} if there is no more data because the end of
* this file has been reached.
* @exception IOException If the first byte cannot be read for any reason
* other than end of file, or if the random access file has been closed, or if
* some other I/O error occurs.
- * @exception NullPointerException If b
is null
.
+ * @exception NullPointerException If {@code b} is {@code null}.
*/
public int read(byte b[]) throws IOException {
return readBytes(b, 0, b.length);
}
/**
- * Reads b.length
bytes from this file into the byte
+ * Reads {@code b.length} bytes from this file into the byte
* array, starting at the current file pointer. This method reads
* repeatedly from the file until the requested number of bytes are
* read. This method blocks until the requested number of bytes are
@@ -386,7 +386,7 @@
}
/**
- * Reads exactly len
bytes from this file into the byte
+ * Reads exactly {@code len} bytes from this file into the byte
* array, starting at the current file pointer. This method reads
* repeatedly from the file until the requested number of bytes are
* read. This method blocks until the requested number of bytes are
@@ -410,15 +410,15 @@
}
/**
- * Attempts to skip over n
bytes of input discarding the
+ * Attempts to skip over {@code n} bytes of input discarding the
* skipped bytes.
* n
bytes have been skipped is only one
- * possibility. This method never throws an EOFException
.
- * The actual number of bytes skipped is returned. If n
+ * file before {@code n} bytes have been skipped is only one
+ * possibility. This method never throws an {@code EOFException}.
+ * The actual number of bytes skipped is returned. If {@code n}
* is negative, no bytes are skipped.
*
* @param n the number of bytes to be skipped.
@@ -451,7 +451,7 @@
* Writes the specified byte to this file. The write starts at
* the current file pointer.
*
- * @param b the byte
to be written.
+ * @param b the {@code byte} to be written.
* @exception IOException if an I/O error occurs.
*/
public native void write(int b) throws IOException;
@@ -467,7 +467,7 @@
private native void writeBytes(byte b[], int off, int len) throws IOException;
/**
- * Writes b.length
bytes from the specified byte array
+ * Writes {@code b.length} bytes from the specified byte array
* to this file, starting at the current file pointer.
*
* @param b the data.
@@ -478,8 +478,8 @@
}
/**
- * Writes len
bytes from the specified byte array
- * starting at offset off
to this file.
+ * Writes {@code len} bytes from the specified byte array
+ * starting at offset {@code off} to this file.
*
* @param b the data.
* @param off the start offset in the data.
@@ -512,8 +512,8 @@
* @param pos the offset position, measured in bytes from the
* beginning of the file, at which to set the file
* pointer.
- * @exception IOException if pos
is less than
- * 0
or if an I/O error occurs.
+ * @exception IOException if {@code pos} is less than
+ * {@code 0} or if an I/O error occurs.
*/
public native void seek(long pos) throws IOException;
@@ -529,14 +529,14 @@
* Sets the length of this file.
*
* length
method is greater than the newLength
+ * {@code length} method is greater than the {@code newLength}
* argument then the file will be truncated. In this case, if the file
- * offset as returned by the getFilePointer
method is greater
- * than newLength
then after this method returns the offset
- * will be equal to newLength
.
+ * offset as returned by the {@code getFilePointer} method is greater
+ * than {@code newLength} then after this method returns the offset
+ * will be equal to {@code newLength}.
*
* length
method is smaller than the newLength
+ * {@code length} method is smaller than the {@code newLength}
* argument then the file will be extended. In this case, the contents of
* the extended portion of the file are not defined.
*
@@ -584,14 +584,14 @@
//
/**
- * Reads a boolean
from this file. This method reads a
+ * Reads a {@code boolean} from this file. This method reads a
* single byte from the file, starting at the current file pointer.
- * A value of 0
represents
- * false
. Any other value represents true
.
+ * A value of {@code 0} represents
+ * {@code false}. Any other value represents {@code true}.
* This method blocks until the byte is read, the end of the stream
* is detected, or an exception is thrown.
*
- * @return the boolean
value read.
+ * @return the {@code boolean} value read.
* @exception EOFException if this file has reached the end.
* @exception IOException if an I/O error occurs.
*/
@@ -605,7 +605,7 @@
/**
* Reads a signed eight-bit value from this file. This method reads a
* byte from the file, starting from the current file pointer.
- * If the byte read is b
, where
+ * If the byte read is {@code b}, where
* 0 <= b <= 255
,
* then the result is:
*
@@ -616,7 +616,7 @@
* is detected, or an exception is thrown.
*
* @return the next byte of this file as a signed eight-bit
- *
byte
.
+ * {@code byte}.
* @exception EOFException if this file has reached the end.
* @exception IOException if an I/O error occurs.
*/
@@ -651,8 +651,8 @@
* Reads a signed 16-bit number from this file. The method reads two
* bytes from this file, starting at the current file pointer.
* If the two bytes read, in order, are
- * b1
and b2
, where each of the two values is
- * between 0
and 255
, inclusive, then the
+ * {@code b1} and {@code b2}, where each of the two values is
+ * between {@code 0} and {@code 255}, inclusive, then the
* result is equal to:
*
* (short)((b1 << 8) | b2)
@@ -679,7 +679,7 @@
* Reads an unsigned 16-bit number from this file. This method reads
* two bytes from the file, starting at the current file pointer.
* If the bytes read, in order, are
- *
b1
and b2
, where
+ * {@code b1} and {@code b2}, where
* 0 <= b1, b2 <= 255
,
* then the result is equal to:
*
@@ -707,7 +707,7 @@
* Reads a character from this file. This method reads two
* bytes from the file, starting at the current file pointer.
* If the bytes read, in order, are
- *
b1
and b2
, where
+ * {@code b1} and {@code b2}, where
* 0 <= b1, b2 <= 255
,
* then the result is equal to:
*
@@ -718,7 +718,7 @@
* stream is detected, or an exception is thrown.
*
* @return the next two bytes of this file, interpreted as a
- *
char
.
+ * {@code char}.
* @exception EOFException if this file reaches the end before reading
* two bytes.
* @exception IOException if an I/O error occurs.
@@ -734,8 +734,8 @@
/**
* Reads a signed 32-bit integer from this file. This method reads 4
* bytes from the file, starting at the current file pointer.
- * If the bytes read, in order, are b1
,
- * b2
, b3
, and b4
, where
+ * If the bytes read, in order, are {@code b1},
+ * {@code b2}, {@code b3}, and {@code b4}, where
* 0 <= b1, b2, b3, b4 <= 255
,
* then the result is equal to:
*
@@ -746,7 +746,7 @@
* stream is detected, or an exception is thrown.
*
* @return the next four bytes of this file, interpreted as an
- *
int
.
+ * {@code int}.
* @exception EOFException if this file reaches the end before reading
* four bytes.
* @exception IOException if an I/O error occurs.
@@ -765,9 +765,9 @@
* Reads a signed 64-bit integer from this file. This method reads eight
* bytes from the file, starting at the current file pointer.
* If the bytes read, in order, are
- * b1
, b2
, b3
,
- * b4
, b5
, b6
,
- * b7
, and b8,
where:
+ * {@code b1}, {@code b2}, {@code b3},
+ * {@code b4}, {@code b5}, {@code b6},
+ * {@code b7}, and {@code b8,} where:
*
@@ -784,7 +784,7 @@
* stream is detected, or an exception is thrown.
*
* @return the next eight bytes of this file, interpreted as a
- *
* 0 <= b1, b2, b3, b4, b5, b6, b7, b8 <=255,
*
long
.
+ * {@code long}.
* @exception EOFException if this file reaches the end before reading
* eight bytes.
* @exception IOException if an I/O error occurs.
@@ -794,18 +794,18 @@
}
/**
- * Reads a float
from this file. This method reads an
- * int
value, starting at the current file pointer,
- * as if by the readInt
method
- * and then converts that int
to a float
- * using the intBitsToFloat
method in class
- * Float
.
+ * Reads a {@code float} from this file. This method reads an
+ * {@code int} value, starting at the current file pointer,
+ * as if by the {@code readInt} method
+ * and then converts that {@code int} to a {@code float}
+ * using the {@code intBitsToFloat} method in class
+ * {@code Float}.
* float
.
+ * {@code float}.
* @exception EOFException if this file reaches the end before reading
* four bytes.
* @exception IOException if an I/O error occurs.
@@ -817,18 +817,18 @@
}
/**
- * Reads a double
from this file. This method reads a
- * long
value, starting at the current file pointer,
- * as if by the readLong
method
- * and then converts that long
to a double
- * using the longBitsToDouble
method in
- * class Double
.
+ * Reads a {@code double} from this file. This method reads a
+ * {@code long} value, starting at the current file pointer,
+ * as if by the {@code readLong} method
+ * and then converts that {@code long} to a {@code double}
+ * using the {@code longBitsToDouble} method in
+ * class {@code Double}.
* double
.
+ * {@code double}.
* @exception EOFException if this file reaches the end before reading
* eight bytes.
* @exception IOException if an I/O error occurs.
@@ -849,7 +849,7 @@
* therefore, support the full Unicode character set.
*
* '\r'
), a newline character ('\n'
), a
+ * ({@code '\u005Cr'}), a newline character ({@code '\u005Cn'}), a
* carriage-return character immediately followed by a newline character,
* or the end of the file. Line-terminating characters are discarded and
* are not included as part of the string returned.
@@ -901,7 +901,7 @@
* readUnsignedShort
. This value gives the number of
+ * {@code readUnsignedShort}. This value gives the number of
* following bytes that are in the encoded string, not
* the length of the resulting string. The following bytes are then
* interpreted as bytes encoding characters in the modified UTF-8 format
@@ -923,13 +923,13 @@
}
/**
- * Writes a boolean
to the file as a one-byte value. The
- * value true
is written out as the value
- * (byte)1
; the value false
is written out
- * as the value (byte)0
. The write starts at
+ * Writes a {@code boolean} to the file as a one-byte value. The
+ * value {@code true} is written out as the value
+ * {@code (byte)1}; the value {@code false} is written out
+ * as the value {@code (byte)0}. The write starts at
* the current position of the file pointer.
*
- * @param v a boolean
value to be written.
+ * @param v a {@code boolean} value to be written.
* @exception IOException if an I/O error occurs.
*/
public final void writeBoolean(boolean v) throws IOException {
@@ -938,10 +938,10 @@
}
/**
- * Writes a byte
to the file as a one-byte value. The
+ * Writes a {@code byte} to the file as a one-byte value. The
* write starts at the current position of the file pointer.
*
- * @param v a byte
value to be written.
+ * @param v a {@code byte} value to be written.
* @exception IOException if an I/O error occurs.
*/
public final void writeByte(int v) throws IOException {
@@ -950,10 +950,10 @@
}
/**
- * Writes a short
to the file as two bytes, high byte first.
+ * Writes a {@code short} to the file as two bytes, high byte first.
* The write starts at the current position of the file pointer.
*
- * @param v a short
to be written.
+ * @param v a {@code short} to be written.
* @exception IOException if an I/O error occurs.
*/
public final void writeShort(int v) throws IOException {
@@ -963,11 +963,11 @@
}
/**
- * Writes a char
to the file as a two-byte value, high
+ * Writes a {@code char} to the file as a two-byte value, high
* byte first. The write starts at the current position of the
* file pointer.
*
- * @param v a char
value to be written.
+ * @param v a {@code char} value to be written.
* @exception IOException if an I/O error occurs.
*/
public final void writeChar(int v) throws IOException {
@@ -977,10 +977,10 @@
}
/**
- * Writes an int
to the file as four bytes, high byte first.
+ * Writes an {@code int} to the file as four bytes, high byte first.
* The write starts at the current position of the file pointer.
*
- * @param v an int
to be written.
+ * @param v an {@code int} to be written.
* @exception IOException if an I/O error occurs.
*/
public final void writeInt(int v) throws IOException {
@@ -992,10 +992,10 @@
}
/**
- * Writes a long
to the file as eight bytes, high byte first.
+ * Writes a {@code long} to the file as eight bytes, high byte first.
* The write starts at the current position of the file pointer.
*
- * @param v a long
to be written.
+ * @param v a {@code long} to be written.
* @exception IOException if an I/O error occurs.
*/
public final void writeLong(long v) throws IOException {
@@ -1011,13 +1011,13 @@
}
/**
- * Converts the float argument to an int
using the
- * floatToIntBits
method in class Float
,
- * and then writes that int
value to the file as a
+ * Converts the float argument to an {@code int} using the
+ * {@code floatToIntBits} method in class {@code Float},
+ * and then writes that {@code int} value to the file as a
* four-byte quantity, high byte first. The write starts at the
* current position of the file pointer.
*
- * @param v a float
value to be written.
+ * @param v a {@code float} value to be written.
* @exception IOException if an I/O error occurs.
* @see java.lang.Float#floatToIntBits(float)
*/
@@ -1026,13 +1026,13 @@
}
/**
- * Converts the double argument to a long
using the
- * doubleToLongBits
method in class Double
,
- * and then writes that long
value to the file as an
+ * Converts the double argument to a {@code long} using the
+ * {@code doubleToLongBits} method in class {@code Double},
+ * and then writes that {@code long} value to the file as an
* eight-byte quantity, high byte first. The write starts at the current
* position of the file pointer.
*
- * @param v a double
value to be written.
+ * @param v a {@code double} value to be written.
* @exception IOException if an I/O error occurs.
* @see java.lang.Double#doubleToLongBits(double)
*/
@@ -1060,10 +1060,10 @@
/**
* Writes a string to the file as a sequence of characters. Each
* character is written to the data output stream as if by the
- * writeChar
method. The write starts at the current
+ * {@code writeChar} method. The write starts at the current
* position of the file pointer.
*
- * @param s a String
value to be written.
+ * @param s a {@code String} value to be written.
* @exception IOException if an I/O error occurs.
* @see java.io.RandomAccessFile#writeChar(int)
*/
@@ -1087,7 +1087,7 @@
* writeShort
method giving the number of bytes to
+ * {@code writeShort} method giving the number of bytes to
* follow. This value is the number of bytes actually written out,
* not the length of the string. Following the length, each character
* of the string is output, in sequence, using the modified UTF-8 encoding