Home » openjdk-7 » java » io » [javadoc | source]

    1   /*
    2    * Copyright (c) 1994, 2007, Oracle and/or its affiliates. All rights reserved.
    3    * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
    4    *
    5    * This code is free software; you can redistribute it and/or modify it
    6    * under the terms of the GNU General Public License version 2 only, as
    7    * published by the Free Software Foundation.  Oracle designates this
    8    * particular file as subject to the "Classpath" exception as provided
    9    * by Oracle in the LICENSE file that accompanied this code.
   10    *
   11    * This code is distributed in the hope that it will be useful, but WITHOUT
   12    * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
   13    * FITNESS FOR A PARTICULAR PURPOSE.  See the GNU General Public License
   14    * version 2 for more details (a copy is included in the LICENSE file that
   15    * accompanied this code).
   16    *
   17    * You should have received a copy of the GNU General Public License version
   18    * 2 along with this work; if not, write to the Free Software Foundation,
   19    * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA.
   20    *
   21    * Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA
   22    * or visit www.oracle.com if you need additional information or have any
   23    * questions.
   24    */
   25   
   26   package java.io;
   27   
   28   import java.nio.channels.FileChannel;
   29   import sun.nio.ch.FileChannelImpl;
   30   
   31   
   32   /**
   33    * Instances of this class support both reading and writing to a
   34    * random access file. A random access file behaves like a large
   35    * array of bytes stored in the file system. There is a kind of cursor,
   36    * or index into the implied array, called the <em>file pointer</em>;
   37    * input operations read bytes starting at the file pointer and advance
   38    * the file pointer past the bytes read. If the random access file is
   39    * created in read/write mode, then output operations are also available;
   40    * output operations write bytes starting at the file pointer and advance
   41    * the file pointer past the bytes written. Output operations that write
   42    * past the current end of the implied array cause the array to be
   43    * extended. The file pointer can be read by the
   44    * <code>getFilePointer</code> method and set by the <code>seek</code>
   45    * method.
   46    * <p>
   47    * It is generally true of all the reading routines in this class that
   48    * if end-of-file is reached before the desired number of bytes has been
   49    * read, an <code>EOFException</code> (which is a kind of
   50    * <code>IOException</code>) is thrown. If any byte cannot be read for
   51    * any reason other than end-of-file, an <code>IOException</code> other
   52    * than <code>EOFException</code> is thrown. In particular, an
   53    * <code>IOException</code> may be thrown if the stream has been closed.
   54    *
   55    * @author  unascribed
   56    * @since   JDK1.0
   57    */
   58   
   59   public class RandomAccessFile implements DataOutput, DataInput, Closeable {
   60   
   61       private FileDescriptor fd;
   62       private FileChannel channel = null;
   63       private boolean rw;
   64   
   65       private Object closeLock = new Object();
   66       private volatile boolean closed = false;
   67   
   68       private static final int O_RDONLY = 1;
   69       private static final int O_RDWR =   2;
   70       private static final int O_SYNC =   4;
   71       private static final int O_DSYNC =  8;
   72   
   73       /**
   74        * Creates a random access file stream to read from, and optionally
   75        * to write to, a file with the specified name. A new
   76        * {@link FileDescriptor} object is created to represent the
   77        * connection to the file.
   78        *
   79        * <p> The <tt>mode</tt> argument specifies the access mode with which the
   80        * file is to be opened.  The permitted values and their meanings are as
   81        * specified for the <a
   82        * href="#mode"><tt>RandomAccessFile(File,String)</tt></a> constructor.
   83        *
   84        * <p>
   85        * If there is a security manager, its <code>checkRead</code> method
   86        * is called with the <code>name</code> argument
   87        * as its argument to see if read access to the file is allowed.
   88        * If the mode allows writing, the security manager's
   89        * <code>checkWrite</code> method
   90        * is also called with the <code>name</code> argument
   91        * as its argument to see if write access to the file is allowed.
   92        *
   93        * @param      name   the system-dependent filename
   94        * @param      mode   the access <a href="#mode">mode</a>
   95        * @exception  IllegalArgumentException  if the mode argument is not equal
   96        *               to one of <tt>"r"</tt>, <tt>"rw"</tt>, <tt>"rws"</tt>, or
   97        *               <tt>"rwd"</tt>
   98        * @exception FileNotFoundException
   99        *            if the mode is <tt>"r"</tt> but the given string does not
  100        *            denote an existing regular file, or if the mode begins with
  101        *            <tt>"rw"</tt> but the given string does not denote an
  102        *            existing, writable regular file and a new regular file of
  103        *            that name cannot be created, or if some other error occurs
  104        *            while opening or creating the file
  105        * @exception  SecurityException         if a security manager exists and its
  106        *               <code>checkRead</code> method denies read access to the file
  107        *               or the mode is "rw" and the security manager's
  108        *               <code>checkWrite</code> method denies write access to the file
  109        * @see        java.lang.SecurityException
  110        * @see        java.lang.SecurityManager#checkRead(java.lang.String)
  111        * @see        java.lang.SecurityManager#checkWrite(java.lang.String)
  112        * @revised 1.4
  113        * @spec JSR-51
  114        */
  115       public RandomAccessFile(String name, String mode)
  116           throws FileNotFoundException
  117       {
  118           this(name != null ? new File(name) : null, mode);
  119       }
  120   
  121       /**
  122        * Creates a random access file stream to read from, and optionally to
  123        * write to, the file specified by the {@link File} argument.  A new {@link
  124        * FileDescriptor} object is created to represent this file connection.
  125        *
  126        * <a name="mode"><p> The <tt>mode</tt> argument specifies the access mode
  127        * in which the file is to be opened.  The permitted values and their
  128        * meanings are:
  129        *
  130        * <blockquote><table summary="Access mode permitted values and meanings">
  131        * <tr><th><p align="left">Value</p></th><th><p align="left">Meaning</p></th></tr>
  132        * <tr><td valign="top"><tt>"r"</tt></td>
  133        *     <td> Open for reading only.  Invoking any of the <tt>write</tt>
  134        *     methods of the resulting object will cause an {@link
  135        *     java.io.IOException} to be thrown. </td></tr>
  136        * <tr><td valign="top"><tt>"rw"</tt></td>
  137        *     <td> Open for reading and writing.  If the file does not already
  138        *     exist then an attempt will be made to create it. </td></tr>
  139        * <tr><td valign="top"><tt>"rws"</tt></td>
  140        *     <td> Open for reading and writing, as with <tt>"rw"</tt>, and also
  141        *     require that every update to the file's content or metadata be
  142        *     written synchronously to the underlying storage device.  </td></tr>
  143        * <tr><td valign="top"><tt>"rwd"&nbsp;&nbsp;</tt></td>
  144        *     <td> Open for reading and writing, as with <tt>"rw"</tt>, and also
  145        *     require that every update to the file's content be written
  146        *     synchronously to the underlying storage device. </td></tr>
  147        * </table></blockquote>
  148        *
  149        * The <tt>"rws"</tt> and <tt>"rwd"</tt> modes work much like the {@link
  150        * java.nio.channels.FileChannel#force(boolean) force(boolean)} method of
  151        * the {@link java.nio.channels.FileChannel} class, passing arguments of
  152        * <tt>true</tt> and <tt>false</tt>, respectively, except that they always
  153        * apply to every I/O operation and are therefore often more efficient.  If
  154        * the file resides on a local storage device then when an invocation of a
  155        * method of this class returns it is guaranteed that all changes made to
  156        * the file by that invocation will have been written to that device.  This
  157        * is useful for ensuring that critical information is not lost in the
  158        * event of a system crash.  If the file does not reside on a local device
  159        * then no such guarantee is made.
  160        *
  161        * <p> The <tt>"rwd"</tt> mode can be used to reduce the number of I/O
  162        * operations performed.  Using <tt>"rwd"</tt> only requires updates to the
  163        * file's content to be written to storage; using <tt>"rws"</tt> requires
  164        * updates to both the file's content and its metadata to be written, which
  165        * generally requires at least one more low-level I/O operation.
  166        *
  167        * <p> If there is a security manager, its <code>checkRead</code> method is
  168        * called with the pathname of the <code>file</code> argument as its
  169        * argument to see if read access to the file is allowed.  If the mode
  170        * allows writing, the security manager's <code>checkWrite</code> method is
  171        * also called with the path argument to see if write access to the file is
  172        * allowed.
  173        *
  174        * @param      file   the file object
  175        * @param      mode   the access mode, as described
  176        *                    <a href="#mode">above</a>
  177        * @exception  IllegalArgumentException  if the mode argument is not equal
  178        *               to one of <tt>"r"</tt>, <tt>"rw"</tt>, <tt>"rws"</tt>, or
  179        *               <tt>"rwd"</tt>
  180        * @exception FileNotFoundException
  181        *            if the mode is <tt>"r"</tt> but the given file object does
  182        *            not denote an existing regular file, or if the mode begins
  183        *            with <tt>"rw"</tt> but the given file object does not denote
  184        *            an existing, writable regular file and a new regular file of
  185        *            that name cannot be created, or if some other error occurs
  186        *            while opening or creating the file
  187        * @exception  SecurityException         if a security manager exists and its
  188        *               <code>checkRead</code> method denies read access to the file
  189        *               or the mode is "rw" and the security manager's
  190        *               <code>checkWrite</code> method denies write access to the file
  191        * @see        java.lang.SecurityManager#checkRead(java.lang.String)
  192        * @see        java.lang.SecurityManager#checkWrite(java.lang.String)
  193        * @see        java.nio.channels.FileChannel#force(boolean)
  194        * @revised 1.4
  195        * @spec JSR-51
  196        */
  197       public RandomAccessFile(File file, String mode)
  198           throws FileNotFoundException
  199       {
  200           String name = (file != null ? file.getPath() : null);
  201           int imode = -1;
  202           if (mode.equals("r"))
  203               imode = O_RDONLY;
  204           else if (mode.startsWith("rw")) {
  205               imode = O_RDWR;
  206               rw = true;
  207               if (mode.length() > 2) {
  208                   if (mode.equals("rws"))
  209                       imode |= O_SYNC;
  210                   else if (mode.equals("rwd"))
  211                       imode |= O_DSYNC;
  212                   else
  213                       imode = -1;
  214               }
  215           }
  216           if (imode < 0)
  217               throw new IllegalArgumentException("Illegal mode \"" + mode
  218                                                  + "\" must be one of "
  219                                                  + "\"r\", \"rw\", \"rws\","
  220                                                  + " or \"rwd\"");
  221           SecurityManager security = System.getSecurityManager();
  222           if (security != null) {
  223               security.checkRead(name);
  224               if (rw) {
  225                   security.checkWrite(name);
  226               }
  227           }
  228           if (name == null) {
  229               throw new NullPointerException();
  230           }
  231           fd = new FileDescriptor();
  232           fd.incrementAndGetUseCount();
  233           open(name, imode);
  234       }
  235   
  236       /**
  237        * Returns the opaque file descriptor object associated with this
  238        * stream. </p>
  239        *
  240        * @return     the file descriptor object associated with this stream.
  241        * @exception  IOException  if an I/O error occurs.
  242        * @see        java.io.FileDescriptor
  243        */
  244       public final FileDescriptor getFD() throws IOException {
  245           if (fd != null) return fd;
  246           throw new IOException();
  247       }
  248   
  249       /**
  250        * Returns the unique {@link java.nio.channels.FileChannel FileChannel}
  251        * object associated with this file.
  252        *
  253        * <p> The {@link java.nio.channels.FileChannel#position()
  254        * </code>position<code>} of the returned channel will always be equal to
  255        * this object's file-pointer offset as returned by the {@link
  256        * #getFilePointer getFilePointer} method.  Changing this object's
  257        * file-pointer offset, whether explicitly or by reading or writing bytes,
  258        * will change the position of the channel, and vice versa.  Changing the
  259        * file's length via this object will change the length seen via the file
  260        * channel, and vice versa.
  261        *
  262        * @return  the file channel associated with this file
  263        *
  264        * @since 1.4
  265        * @spec JSR-51
  266        */
  267       public final FileChannel getChannel() {
  268           synchronized (this) {
  269               if (channel == null) {
  270                   channel = FileChannelImpl.open(fd, true, rw, this);
  271   
  272                   /*
  273                    * FileDescriptor could be shared by FileInputStream or
  274                    * FileOutputStream.
  275                    * Ensure that FD is GC'ed only when all the streams/channels
  276                    * are done using it.
  277                    * Increment fd's use count. Invoking the channel's close()
  278                    * method will result in decrementing the use count set for
  279                    * the channel.
  280                    */
  281                   fd.incrementAndGetUseCount();
  282               }
  283               return channel;
  284           }
  285       }
  286   
  287       /**
  288        * Opens a file and returns the file descriptor.  The file is
  289        * opened in read-write mode if the O_RDWR bit in <code>mode</code>
  290        * is true, else the file is opened as read-only.
  291        * If the <code>name</code> refers to a directory, an IOException
  292        * is thrown.
  293        *
  294        * @param name the name of the file
  295        * @param mode the mode flags, a combination of the O_ constants
  296        *             defined above
  297        */
  298       private native void open(String name, int mode)
  299           throws FileNotFoundException;
  300   
  301       // 'Read' primitives
  302   
  303       /**
  304        * Reads a byte of data from this file. The byte is returned as an
  305        * integer in the range 0 to 255 (<code>0x00-0x0ff</code>). This
  306        * method blocks if no input is yet available.
  307        * <p>
  308        * Although <code>RandomAccessFile</code> is not a subclass of
  309        * <code>InputStream</code>, this method behaves in exactly the same
  310        * way as the {@link InputStream#read()} method of
  311        * <code>InputStream</code>.
  312        *
  313        * @return     the next byte of data, or <code>-1</code> if the end of the
  314        *             file has been reached.
  315        * @exception  IOException  if an I/O error occurs. Not thrown if
  316        *                          end-of-file has been reached.
  317        */
  318       public native int read() throws IOException;
  319   
  320       /**
  321        * Reads a sub array as a sequence of bytes.
  322        * @param b the buffer into which the data is read.
  323        * @param off the start offset of the data.
  324        * @param len the number of bytes to read.
  325        * @exception IOException If an I/O error has occurred.
  326        */
  327       private native int readBytes(byte b[], int off, int len) throws IOException;
  328   
  329       /**
  330        * Reads up to <code>len</code> bytes of data from this file into an
  331        * array of bytes. This method blocks until at least one byte of input
  332        * is available.
  333        * <p>
  334        * Although <code>RandomAccessFile</code> is not a subclass of
  335        * <code>InputStream</code>, this method behaves in exactly the
  336        * same way as the {@link InputStream#read(byte[], int, int)} method of
  337        * <code>InputStream</code>.
  338        *
  339        * @param      b     the buffer into which the data is read.
  340        * @param      off   the start offset in array <code>b</code>
  341        *                   at which the data is written.
  342        * @param      len   the maximum number of bytes read.
  343        * @return     the total number of bytes read into the buffer, or
  344        *             <code>-1</code> if there is no more data because the end of
  345        *             the file has been reached.
  346        * @exception  IOException If the first byte cannot be read for any reason
  347        * other than end of file, or if the random access file has been closed, or if
  348        * some other I/O error occurs.
  349        * @exception  NullPointerException If <code>b</code> is <code>null</code>.
  350        * @exception  IndexOutOfBoundsException If <code>off</code> is negative,
  351        * <code>len</code> is negative, or <code>len</code> is greater than
  352        * <code>b.length - off</code>
  353        */
  354       public int read(byte b[], int off, int len) throws IOException {
  355           return readBytes(b, off, len);
  356       }
  357   
  358       /**
  359        * Reads up to <code>b.length</code> bytes of data from this file
  360        * into an array of bytes. This method blocks until at least one byte
  361        * of input is available.
  362        * <p>
  363        * Although <code>RandomAccessFile</code> is not a subclass of
  364        * <code>InputStream</code>, this method behaves in exactly the
  365        * same way as the {@link InputStream#read(byte[])} method of
  366        * <code>InputStream</code>.
  367        *
  368        * @param      b   the buffer into which the data is read.
  369        * @return     the total number of bytes read into the buffer, or
  370        *             <code>-1</code> if there is no more data because the end of
  371        *             this file has been reached.
  372        * @exception  IOException If the first byte cannot be read for any reason
  373        * other than end of file, or if the random access file has been closed, or if
  374        * some other I/O error occurs.
  375        * @exception  NullPointerException If <code>b</code> is <code>null</code>.
  376        */
  377       public int read(byte b[]) throws IOException {
  378           return readBytes(b, 0, b.length);
  379       }
  380   
  381       /**
  382        * Reads <code>b.length</code> bytes from this file into the byte
  383        * array, starting at the current file pointer. This method reads
  384        * repeatedly from the file until the requested number of bytes are
  385        * read. This method blocks until the requested number of bytes are
  386        * read, the end of the stream is detected, or an exception is thrown.
  387        *
  388        * @param      b   the buffer into which the data is read.
  389        * @exception  EOFException  if this file reaches the end before reading
  390        *               all the bytes.
  391        * @exception  IOException   if an I/O error occurs.
  392        */
  393       public final void readFully(byte b[]) throws IOException {
  394           readFully(b, 0, b.length);
  395       }
  396   
  397       /**
  398        * Reads exactly <code>len</code> bytes from this file into the byte
  399        * array, starting at the current file pointer. This method reads
  400        * repeatedly from the file until the requested number of bytes are
  401        * read. This method blocks until the requested number of bytes are
  402        * read, the end of the stream is detected, or an exception is thrown.
  403        *
  404        * @param      b     the buffer into which the data is read.
  405        * @param      off   the start offset of the data.
  406        * @param      len   the number of bytes to read.
  407        * @exception  EOFException  if this file reaches the end before reading
  408        *               all the bytes.
  409        * @exception  IOException   if an I/O error occurs.
  410        */
  411       public final void readFully(byte b[], int off, int len) throws IOException {
  412           int n = 0;
  413           do {
  414               int count = this.read(b, off + n, len - n);
  415               if (count < 0)
  416                   throw new EOFException();
  417               n += count;
  418           } while (n < len);
  419       }
  420   
  421       /**
  422        * Attempts to skip over <code>n</code> bytes of input discarding the
  423        * skipped bytes.
  424        * <p>
  425        *
  426        * This method may skip over some smaller number of bytes, possibly zero.
  427        * This may result from any of a number of conditions; reaching end of
  428        * file before <code>n</code> bytes have been skipped is only one
  429        * possibility. This method never throws an <code>EOFException</code>.
  430        * The actual number of bytes skipped is returned.  If <code>n</code>
  431        * is negative, no bytes are skipped.
  432        *
  433        * @param      n   the number of bytes to be skipped.
  434        * @return     the actual number of bytes skipped.
  435        * @exception  IOException  if an I/O error occurs.
  436        */
  437       public int skipBytes(int n) throws IOException {
  438           long pos;
  439           long len;
  440           long newpos;
  441   
  442           if (n <= 0) {
  443               return 0;
  444           }
  445           pos = getFilePointer();
  446           len = length();
  447           newpos = pos + n;
  448           if (newpos > len) {
  449               newpos = len;
  450           }
  451           seek(newpos);
  452   
  453           /* return the actual number of bytes skipped */
  454           return (int) (newpos - pos);
  455       }
  456   
  457       // 'Write' primitives
  458   
  459       /**
  460        * Writes the specified byte to this file. The write starts at
  461        * the current file pointer.
  462        *
  463        * @param      b   the <code>byte</code> to be written.
  464        * @exception  IOException  if an I/O error occurs.
  465        */
  466       public native void write(int b) throws IOException;
  467   
  468       /**
  469        * Writes a sub array as a sequence of bytes.
  470        * @param b the data to be written
  471   
  472        * @param off the start offset in the data
  473        * @param len the number of bytes that are written
  474        * @exception IOException If an I/O error has occurred.
  475        */
  476       private native void writeBytes(byte b[], int off, int len) throws IOException;
  477   
  478       /**
  479        * Writes <code>b.length</code> bytes from the specified byte array
  480        * to this file, starting at the current file pointer.
  481        *
  482        * @param      b   the data.
  483        * @exception  IOException  if an I/O error occurs.
  484        */
  485       public void write(byte b[]) throws IOException {
  486           writeBytes(b, 0, b.length);
  487       }
  488   
  489       /**
  490        * Writes <code>len</code> bytes from the specified byte array
  491        * starting at offset <code>off</code> to this file.
  492        *
  493        * @param      b     the data.
  494        * @param      off   the start offset in the data.
  495        * @param      len   the number of bytes to write.
  496        * @exception  IOException  if an I/O error occurs.
  497        */
  498       public void write(byte b[], int off, int len) throws IOException {
  499           writeBytes(b, off, len);
  500       }
  501   
  502       // 'Random access' stuff
  503   
  504       /**
  505        * Returns the current offset in this file.
  506        *
  507        * @return     the offset from the beginning of the file, in bytes,
  508        *             at which the next read or write occurs.
  509        * @exception  IOException  if an I/O error occurs.
  510        */
  511       public native long getFilePointer() throws IOException;
  512   
  513       /**
  514        * Sets the file-pointer offset, measured from the beginning of this
  515        * file, at which the next read or write occurs.  The offset may be
  516        * set beyond the end of the file. Setting the offset beyond the end
  517        * of the file does not change the file length.  The file length will
  518        * change only by writing after the offset has been set beyond the end
  519        * of the file.
  520        *
  521        * @param      pos   the offset position, measured in bytes from the
  522        *                   beginning of the file, at which to set the file
  523        *                   pointer.
  524        * @exception  IOException  if <code>pos</code> is less than
  525        *                          <code>0</code> or if an I/O error occurs.
  526        */
  527       public native void seek(long pos) throws IOException;
  528   
  529       /**
  530        * Returns the length of this file.
  531        *
  532        * @return     the length of this file, measured in bytes.
  533        * @exception  IOException  if an I/O error occurs.
  534        */
  535       public native long length() throws IOException;
  536   
  537       /**
  538        * Sets the length of this file.
  539        *
  540        * <p> If the present length of the file as returned by the
  541        * <code>length</code> method is greater than the <code>newLength</code>
  542        * argument then the file will be truncated.  In this case, if the file
  543        * offset as returned by the <code>getFilePointer</code> method is greater
  544        * than <code>newLength</code> then after this method returns the offset
  545        * will be equal to <code>newLength</code>.
  546        *
  547        * <p> If the present length of the file as returned by the
  548        * <code>length</code> method is smaller than the <code>newLength</code>
  549        * argument then the file will be extended.  In this case, the contents of
  550        * the extended portion of the file are not defined.
  551        *
  552        * @param      newLength    The desired length of the file
  553        * @exception  IOException  If an I/O error occurs
  554        * @since      1.2
  555        */
  556       public native void setLength(long newLength) throws IOException;
  557   
  558       /**
  559        * Closes this random access file stream and releases any system
  560        * resources associated with the stream. A closed random access
  561        * file cannot perform input or output operations and cannot be
  562        * reopened.
  563        *
  564        * <p> If this file has an associated channel then the channel is closed
  565        * as well.
  566        *
  567        * @exception  IOException  if an I/O error occurs.
  568        *
  569        * @revised 1.4
  570        * @spec JSR-51
  571        */
  572       public void close() throws IOException {
  573           synchronized (closeLock) {
  574               if (closed) {
  575                   return;
  576               }
  577               closed = true;
  578           }
  579           if (channel != null) {
  580               /*
  581                * Decrement FD use count associated with the channel. The FD use
  582                * count is incremented whenever a new channel is obtained from
  583                * this stream.
  584                */
  585               fd.decrementAndGetUseCount();
  586               channel.close();
  587           }
  588   
  589           /*
  590            * Decrement FD use count associated with this stream.
  591            * The count got incremented by FileDescriptor during its construction.
  592            */
  593           fd.decrementAndGetUseCount();
  594           close0();
  595       }
  596   
  597       //
  598       //  Some "reading/writing Java data types" methods stolen from
  599       //  DataInputStream and DataOutputStream.
  600       //
  601   
  602       /**
  603        * Reads a <code>boolean</code> from this file. This method reads a
  604        * single byte from the file, starting at the current file pointer.
  605        * A value of <code>0</code> represents
  606        * <code>false</code>. Any other value represents <code>true</code>.
  607        * This method blocks until the byte is read, the end of the stream
  608        * is detected, or an exception is thrown.
  609        *
  610        * @return     the <code>boolean</code> value read.
  611        * @exception  EOFException  if this file has reached the end.
  612        * @exception  IOException   if an I/O error occurs.
  613        */
  614       public final boolean readBoolean() throws IOException {
  615           int ch = this.read();
  616           if (ch < 0)
  617               throw new EOFException();
  618           return (ch != 0);
  619       }
  620   
  621       /**
  622        * Reads a signed eight-bit value from this file. This method reads a
  623        * byte from the file, starting from the current file pointer.
  624        * If the byte read is <code>b</code>, where
  625        * <code>0&nbsp;&lt;=&nbsp;b&nbsp;&lt;=&nbsp;255</code>,
  626        * then the result is:
  627        * <blockquote><pre>
  628        *     (byte)(b)
  629        * </pre></blockquote>
  630        * <p>
  631        * This method blocks until the byte is read, the end of the stream
  632        * is detected, or an exception is thrown.
  633        *
  634        * @return     the next byte of this file as a signed eight-bit
  635        *             <code>byte</code>.
  636        * @exception  EOFException  if this file has reached the end.
  637        * @exception  IOException   if an I/O error occurs.
  638        */
  639       public final byte readByte() throws IOException {
  640           int ch = this.read();
  641           if (ch < 0)
  642               throw new EOFException();
  643           return (byte)(ch);
  644       }
  645   
  646       /**
  647        * Reads an unsigned eight-bit number from this file. This method reads
  648        * a byte from this file, starting at the current file pointer,
  649        * and returns that byte.
  650        * <p>
  651        * This method blocks until the byte is read, the end of the stream
  652        * is detected, or an exception is thrown.
  653        *
  654        * @return     the next byte of this file, interpreted as an unsigned
  655        *             eight-bit number.
  656        * @exception  EOFException  if this file has reached the end.
  657        * @exception  IOException   if an I/O error occurs.
  658        */
  659       public final int readUnsignedByte() throws IOException {
  660           int ch = this.read();
  661           if (ch < 0)
  662               throw new EOFException();
  663           return ch;
  664       }
  665   
  666       /**
  667        * Reads a signed 16-bit number from this file. The method reads two
  668        * bytes from this file, starting at the current file pointer.
  669        * If the two bytes read, in order, are
  670        * <code>b1</code> and <code>b2</code>, where each of the two values is
  671        * between <code>0</code> and <code>255</code>, inclusive, then the
  672        * result is equal to:
  673        * <blockquote><pre>
  674        *     (short)((b1 &lt;&lt; 8) | b2)
  675        * </pre></blockquote>
  676        * <p>
  677        * This method blocks until the two bytes are read, the end of the
  678        * stream is detected, or an exception is thrown.
  679        *
  680        * @return     the next two bytes of this file, interpreted as a signed
  681        *             16-bit number.
  682        * @exception  EOFException  if this file reaches the end before reading
  683        *               two bytes.
  684        * @exception  IOException   if an I/O error occurs.
  685        */
  686       public final short readShort() throws IOException {
  687           int ch1 = this.read();
  688           int ch2 = this.read();
  689           if ((ch1 | ch2) < 0)
  690               throw new EOFException();
  691           return (short)((ch1 << 8) + (ch2 << 0));
  692       }
  693   
  694       /**
  695        * Reads an unsigned 16-bit number from this file. This method reads
  696        * two bytes from the file, starting at the current file pointer.
  697        * If the bytes read, in order, are
  698        * <code>b1</code> and <code>b2</code>, where
  699        * <code>0&nbsp;&lt;=&nbsp;b1, b2&nbsp;&lt;=&nbsp;255</code>,
  700        * then the result is equal to:
  701        * <blockquote><pre>
  702        *     (b1 &lt;&lt; 8) | b2
  703        * </pre></blockquote>
  704        * <p>
  705        * This method blocks until the two bytes are read, the end of the
  706        * stream is detected, or an exception is thrown.
  707        *
  708        * @return     the next two bytes of this file, interpreted as an unsigned
  709        *             16-bit integer.
  710        * @exception  EOFException  if this file reaches the end before reading
  711        *               two bytes.
  712        * @exception  IOException   if an I/O error occurs.
  713        */
  714       public final int readUnsignedShort() throws IOException {
  715           int ch1 = this.read();
  716           int ch2 = this.read();
  717           if ((ch1 | ch2) < 0)
  718               throw new EOFException();
  719           return (ch1 << 8) + (ch2 << 0);
  720       }
  721   
  722       /**
  723        * Reads a character from this file. This method reads two
  724        * bytes from the file, starting at the current file pointer.
  725        * If the bytes read, in order, are
  726        * <code>b1</code> and <code>b2</code>, where
  727        * <code>0&nbsp;&lt;=&nbsp;b1,&nbsp;b2&nbsp;&lt;=&nbsp;255</code>,
  728        * then the result is equal to:
  729        * <blockquote><pre>
  730        *     (char)((b1 &lt;&lt; 8) | b2)
  731        * </pre></blockquote>
  732        * <p>
  733        * This method blocks until the two bytes are read, the end of the
  734        * stream is detected, or an exception is thrown.
  735        *
  736        * @return     the next two bytes of this file, interpreted as a
  737        *                  <code>char</code>.
  738        * @exception  EOFException  if this file reaches the end before reading
  739        *               two bytes.
  740        * @exception  IOException   if an I/O error occurs.
  741        */
  742       public final char readChar() throws IOException {
  743           int ch1 = this.read();
  744           int ch2 = this.read();
  745           if ((ch1 | ch2) < 0)
  746               throw new EOFException();
  747           return (char)((ch1 << 8) + (ch2 << 0));
  748       }
  749   
  750       /**
  751        * Reads a signed 32-bit integer from this file. This method reads 4
  752        * bytes from the file, starting at the current file pointer.
  753        * If the bytes read, in order, are <code>b1</code>,
  754        * <code>b2</code>, <code>b3</code>, and <code>b4</code>, where
  755        * <code>0&nbsp;&lt;=&nbsp;b1, b2, b3, b4&nbsp;&lt;=&nbsp;255</code>,
  756        * then the result is equal to:
  757        * <blockquote><pre>
  758        *     (b1 &lt;&lt; 24) | (b2 &lt;&lt; 16) + (b3 &lt;&lt; 8) + b4
  759        * </pre></blockquote>
  760        * <p>
  761        * This method blocks until the four bytes are read, the end of the
  762        * stream is detected, or an exception is thrown.
  763        *
  764        * @return     the next four bytes of this file, interpreted as an
  765        *             <code>int</code>.
  766        * @exception  EOFException  if this file reaches the end before reading
  767        *               four bytes.
  768        * @exception  IOException   if an I/O error occurs.
  769        */
  770       public final int readInt() throws IOException {
  771           int ch1 = this.read();
  772           int ch2 = this.read();
  773           int ch3 = this.read();
  774           int ch4 = this.read();
  775           if ((ch1 | ch2 | ch3 | ch4) < 0)
  776               throw new EOFException();
  777           return ((ch1 << 24) + (ch2 << 16) + (ch3 << 8) + (ch4 << 0));
  778       }
  779   
  780       /**
  781        * Reads a signed 64-bit integer from this file. This method reads eight
  782        * bytes from the file, starting at the current file pointer.
  783        * If the bytes read, in order, are
  784        * <code>b1</code>, <code>b2</code>, <code>b3</code>,
  785        * <code>b4</code>, <code>b5</code>, <code>b6</code>,
  786        * <code>b7</code>, and <code>b8,</code> where:
  787        * <blockquote><pre>
  788        *     0 &lt;= b1, b2, b3, b4, b5, b6, b7, b8 &lt;=255,
  789        * </pre></blockquote>
  790        * <p>
  791        * then the result is equal to:
  792        * <p><blockquote><pre>
  793        *     ((long)b1 &lt;&lt; 56) + ((long)b2 &lt;&lt; 48)
  794        *     + ((long)b3 &lt;&lt; 40) + ((long)b4 &lt;&lt; 32)
  795        *     + ((long)b5 &lt;&lt; 24) + ((long)b6 &lt;&lt; 16)
  796        *     + ((long)b7 &lt;&lt; 8) + b8
  797        * </pre></blockquote>
  798        * <p>
  799        * This method blocks until the eight bytes are read, the end of the
  800        * stream is detected, or an exception is thrown.
  801        *
  802        * @return     the next eight bytes of this file, interpreted as a
  803        *             <code>long</code>.
  804        * @exception  EOFException  if this file reaches the end before reading
  805        *               eight bytes.
  806        * @exception  IOException   if an I/O error occurs.
  807        */
  808       public final long readLong() throws IOException {
  809           return ((long)(readInt()) << 32) + (readInt() & 0xFFFFFFFFL);
  810       }
  811   
  812       /**
  813        * Reads a <code>float</code> from this file. This method reads an
  814        * <code>int</code> value, starting at the current file pointer,
  815        * as if by the <code>readInt</code> method
  816        * and then converts that <code>int</code> to a <code>float</code>
  817        * using the <code>intBitsToFloat</code> method in class
  818        * <code>Float</code>.
  819        * <p>
  820        * This method blocks until the four bytes are read, the end of the
  821        * stream is detected, or an exception is thrown.
  822        *
  823        * @return     the next four bytes of this file, interpreted as a
  824        *             <code>float</code>.
  825        * @exception  EOFException  if this file reaches the end before reading
  826        *             four bytes.
  827        * @exception  IOException   if an I/O error occurs.
  828        * @see        java.io.RandomAccessFile#readInt()
  829        * @see        java.lang.Float#intBitsToFloat(int)
  830        */
  831       public final float readFloat() throws IOException {
  832           return Float.intBitsToFloat(readInt());
  833       }
  834   
  835       /**
  836        * Reads a <code>double</code> from this file. This method reads a
  837        * <code>long</code> value, starting at the current file pointer,
  838        * as if by the <code>readLong</code> method
  839        * and then converts that <code>long</code> to a <code>double</code>
  840        * using the <code>longBitsToDouble</code> method in
  841        * class <code>Double</code>.
  842        * <p>
  843        * This method blocks until the eight bytes are read, the end of the
  844        * stream is detected, or an exception is thrown.
  845        *
  846        * @return     the next eight bytes of this file, interpreted as a
  847        *             <code>double</code>.
  848        * @exception  EOFException  if this file reaches the end before reading
  849        *             eight bytes.
  850        * @exception  IOException   if an I/O error occurs.
  851        * @see        java.io.RandomAccessFile#readLong()
  852        * @see        java.lang.Double#longBitsToDouble(long)
  853        */
  854       public final double readDouble() throws IOException {
  855           return Double.longBitsToDouble(readLong());
  856       }
  857   
  858       /**
  859        * Reads the next line of text from this file.  This method successively
  860        * reads bytes from the file, starting at the current file pointer,
  861        * until it reaches a line terminator or the end
  862        * of the file.  Each byte is converted into a character by taking the
  863        * byte's value for the lower eight bits of the character and setting the
  864        * high eight bits of the character to zero.  This method does not,
  865        * therefore, support the full Unicode character set.
  866        *
  867        * <p> A line of text is terminated by a carriage-return character
  868        * (<code>'&#92;r'</code>), a newline character (<code>'&#92;n'</code>), a
  869        * carriage-return character immediately followed by a newline character,
  870        * or the end of the file.  Line-terminating characters are discarded and
  871        * are not included as part of the string returned.
  872        *
  873        * <p> This method blocks until a newline character is read, a carriage
  874        * return and the byte following it are read (to see if it is a newline),
  875        * the end of the file is reached, or an exception is thrown.
  876        *
  877        * @return     the next line of text from this file, or null if end
  878        *             of file is encountered before even one byte is read.
  879        * @exception  IOException  if an I/O error occurs.
  880        */
  881   
  882       public final String readLine() throws IOException {
  883           StringBuffer input = new StringBuffer();
  884           int c = -1;
  885           boolean eol = false;
  886   
  887           while (!eol) {
  888               switch (c = read()) {
  889               case -1:
  890               case '\n':
  891                   eol = true;
  892                   break;
  893               case '\r':
  894                   eol = true;
  895                   long cur = getFilePointer();
  896                   if ((read()) != '\n') {
  897                       seek(cur);
  898                   }
  899                   break;
  900               default:
  901                   input.append((char)c);
  902                   break;
  903               }
  904           }
  905   
  906           if ((c == -1) && (input.length() == 0)) {
  907               return null;
  908           }
  909           return input.toString();
  910       }
  911   
  912       /**
  913        * Reads in a string from this file. The string has been encoded
  914        * using a
  915        * <a href="DataInput.html#modified-utf-8">modified UTF-8</a>
  916        * format.
  917        * <p>
  918        * The first two bytes are read, starting from the current file
  919        * pointer, as if by
  920        * <code>readUnsignedShort</code>. This value gives the number of
  921        * following bytes that are in the encoded string, not
  922        * the length of the resulting string. The following bytes are then
  923        * interpreted as bytes encoding characters in the modified UTF-8 format
  924        * and are converted into characters.
  925        * <p>
  926        * This method blocks until all the bytes are read, the end of the
  927        * stream is detected, or an exception is thrown.
  928        *
  929        * @return     a Unicode string.
  930        * @exception  EOFException            if this file reaches the end before
  931        *               reading all the bytes.
  932        * @exception  IOException             if an I/O error occurs.
  933        * @exception  UTFDataFormatException  if the bytes do not represent
  934        *               valid modified UTF-8 encoding of a Unicode string.
  935        * @see        java.io.RandomAccessFile#readUnsignedShort()
  936        */
  937       public final String readUTF() throws IOException {
  938           return DataInputStream.readUTF(this);
  939       }
  940   
  941       /**
  942        * Writes a <code>boolean</code> to the file as a one-byte value. The
  943        * value <code>true</code> is written out as the value
  944        * <code>(byte)1</code>; the value <code>false</code> is written out
  945        * as the value <code>(byte)0</code>. The write starts at
  946        * the current position of the file pointer.
  947        *
  948        * @param      v   a <code>boolean</code> value to be written.
  949        * @exception  IOException  if an I/O error occurs.
  950        */
  951       public final void writeBoolean(boolean v) throws IOException {
  952           write(v ? 1 : 0);
  953           //written++;
  954       }
  955   
  956       /**
  957        * Writes a <code>byte</code> to the file as a one-byte value. The
  958        * write starts at the current position of the file pointer.
  959        *
  960        * @param      v   a <code>byte</code> value to be written.
  961        * @exception  IOException  if an I/O error occurs.
  962        */
  963       public final void writeByte(int v) throws IOException {
  964           write(v);
  965           //written++;
  966       }
  967   
  968       /**
  969        * Writes a <code>short</code> to the file as two bytes, high byte first.
  970        * The write starts at the current position of the file pointer.
  971        *
  972        * @param      v   a <code>short</code> to be written.
  973        * @exception  IOException  if an I/O error occurs.
  974        */
  975       public final void writeShort(int v) throws IOException {
  976           write((v >>> 8) & 0xFF);
  977           write((v >>> 0) & 0xFF);
  978           //written += 2;
  979       }
  980   
  981       /**
  982        * Writes a <code>char</code> to the file as a two-byte value, high
  983        * byte first. The write starts at the current position of the
  984        * file pointer.
  985        *
  986        * @param      v   a <code>char</code> value to be written.
  987        * @exception  IOException  if an I/O error occurs.
  988        */
  989       public final void writeChar(int v) throws IOException {
  990           write((v >>> 8) & 0xFF);
  991           write((v >>> 0) & 0xFF);
  992           //written += 2;
  993       }
  994   
  995       /**
  996        * Writes an <code>int</code> to the file as four bytes, high byte first.
  997        * The write starts at the current position of the file pointer.
  998        *
  999        * @param      v   an <code>int</code> to be written.
 1000        * @exception  IOException  if an I/O error occurs.
 1001        */
 1002       public final void writeInt(int v) throws IOException {
 1003           write((v >>> 24) & 0xFF);
 1004           write((v >>> 16) & 0xFF);
 1005           write((v >>>  8) & 0xFF);
 1006           write((v >>>  0) & 0xFF);
 1007           //written += 4;
 1008       }
 1009   
 1010       /**
 1011        * Writes a <code>long</code> to the file as eight bytes, high byte first.
 1012        * The write starts at the current position of the file pointer.
 1013        *
 1014        * @param      v   a <code>long</code> to be written.
 1015        * @exception  IOException  if an I/O error occurs.
 1016        */
 1017       public final void writeLong(long v) throws IOException {
 1018           write((int)(v >>> 56) & 0xFF);
 1019           write((int)(v >>> 48) & 0xFF);
 1020           write((int)(v >>> 40) & 0xFF);
 1021           write((int)(v >>> 32) & 0xFF);
 1022           write((int)(v >>> 24) & 0xFF);
 1023           write((int)(v >>> 16) & 0xFF);
 1024           write((int)(v >>>  8) & 0xFF);
 1025           write((int)(v >>>  0) & 0xFF);
 1026           //written += 8;
 1027       }
 1028   
 1029       /**
 1030        * Converts the float argument to an <code>int</code> using the
 1031        * <code>floatToIntBits</code> method in class <code>Float</code>,
 1032        * and then writes that <code>int</code> value to the file as a
 1033        * four-byte quantity, high byte first. The write starts at the
 1034        * current position of the file pointer.
 1035        *
 1036        * @param      v   a <code>float</code> value to be written.
 1037        * @exception  IOException  if an I/O error occurs.
 1038        * @see        java.lang.Float#floatToIntBits(float)
 1039        */
 1040       public final void writeFloat(float v) throws IOException {
 1041           writeInt(Float.floatToIntBits(v));
 1042       }
 1043   
 1044       /**
 1045        * Converts the double argument to a <code>long</code> using the
 1046        * <code>doubleToLongBits</code> method in class <code>Double</code>,
 1047        * and then writes that <code>long</code> value to the file as an
 1048        * eight-byte quantity, high byte first. The write starts at the current
 1049        * position of the file pointer.
 1050        *
 1051        * @param      v   a <code>double</code> value to be written.
 1052        * @exception  IOException  if an I/O error occurs.
 1053        * @see        java.lang.Double#doubleToLongBits(double)
 1054        */
 1055       public final void writeDouble(double v) throws IOException {
 1056           writeLong(Double.doubleToLongBits(v));
 1057       }
 1058   
 1059       /**
 1060        * Writes the string to the file as a sequence of bytes. Each
 1061        * character in the string is written out, in sequence, by discarding
 1062        * its high eight bits. The write starts at the current position of
 1063        * the file pointer.
 1064        *
 1065        * @param      s   a string of bytes to be written.
 1066        * @exception  IOException  if an I/O error occurs.
 1067        */
 1068       public final void writeBytes(String s) throws IOException {
 1069           int len = s.length();
 1070           byte[] b = new byte[len];
 1071           s.getBytes(0, len, b, 0);
 1072           writeBytes(b, 0, len);
 1073       }
 1074   
 1075       /**
 1076        * Writes a string to the file as a sequence of characters. Each
 1077        * character is written to the data output stream as if by the
 1078        * <code>writeChar</code> method. The write starts at the current
 1079        * position of the file pointer.
 1080        *
 1081        * @param      s   a <code>String</code> value to be written.
 1082        * @exception  IOException  if an I/O error occurs.
 1083        * @see        java.io.RandomAccessFile#writeChar(int)
 1084        */
 1085       public final void writeChars(String s) throws IOException {
 1086           int clen = s.length();
 1087           int blen = 2*clen;
 1088           byte[] b = new byte[blen];
 1089           char[] c = new char[clen];
 1090           s.getChars(0, clen, c, 0);
 1091           for (int i = 0, j = 0; i < clen; i++) {
 1092               b[j++] = (byte)(c[i] >>> 8);
 1093               b[j++] = (byte)(c[i] >>> 0);
 1094           }
 1095           writeBytes(b, 0, blen);
 1096       }
 1097   
 1098       /**
 1099        * Writes a string to the file using
 1100        * <a href="DataInput.html#modified-utf-8">modified UTF-8</a>
 1101        * encoding in a machine-independent manner.
 1102        * <p>
 1103        * First, two bytes are written to the file, starting at the
 1104        * current file pointer, as if by the
 1105        * <code>writeShort</code> method giving the number of bytes to
 1106        * follow. This value is the number of bytes actually written out,
 1107        * not the length of the string. Following the length, each character
 1108        * of the string is output, in sequence, using the modified UTF-8 encoding
 1109        * for each character.
 1110        *
 1111        * @param      str   a string to be written.
 1112        * @exception  IOException  if an I/O error occurs.
 1113        */
 1114       public final void writeUTF(String str) throws IOException {
 1115           DataOutputStream.writeUTF(str, this);
 1116       }
 1117   
 1118       private static native void initIDs();
 1119   
 1120       private native void close0() throws IOException;
 1121   
 1122       static {
 1123           initIDs();
 1124       }
 1125   }

Home » openjdk-7 » java » io » [javadoc | source]