libjava/java/io/RandomAccessFile.java

   1 /* RandomAccessFile.java -- Class supporting random file I/O
   2    Copyright (C) 1998, 1999, 2001, 2002, 2003, 2004, 2005  Free Software Foundation, Inc.
   3
   4 This file is part of GNU Classpath.
   5
   6 GNU Classpath is free software; you can redistribute it and/or modify
   7 it under the terms of the GNU General Public License as published by
   8 the Free Software Foundation; either version 2, or (at your option)
   9 any later version.
  10
  11 GNU Classpath is distributed in the hope that it will be useful, but
  12 WITHOUT ANY WARRANTY; without even the implied warranty of
  13 MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
  14 General Public License for more details.
  15
  16 You should have received a copy of the GNU General Public License
  17 along with GNU Classpath; see the file COPYING.  If not, write to the
  18 Free Software Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA
  19 02111-1307 USA.
  20
  21 Linking this library statically or dynamically with other modules is
  22 making a combined work based on this library.  Thus, the terms and
  23 conditions of the GNU General Public License cover the whole
  24 combination.
  25
  26 As a special exception, the copyright holders of this library give you
  27 permission to link this library with independent modules to produce an
  28 executable, regardless of the license terms of these independent
  29 modules, and to copy and distribute the resulting executable under
  30 terms of your choice, provided that you also meet, for each linked
  31 independent module, the terms and conditions of the license of that
  32 module.  An independent module is a module which is not derived from
  33 or based on this library.  If you modify this library, you may extend
  34 this exception to your version of the library, but you are not
  35 obligated to do so.  If you do not wish to do so, delete this
  36 exception statement from your version. */
  37
  38
  39 package java.io;
  40
  41 import gnu.java.nio.channels.FileChannelImpl;
  42
  43 import java.nio.channels.FileChannel;
  44
  45 /* Written using "Java Class Libraries", 2nd edition, ISBN 0-201-31002-3
  46  * "The Java Language Specification", ISBN 0-201-63451-1
  47  * Status: Believe complete and correct to 1.1.
  48  */
  49
  50 /**
  51  * This class allows reading and writing of files at random locations.
  52  * Most Java I/O classes are either pure sequential input or output.  This
  53  * class fulfills the need to be able to read the bytes of a file in an
  54  * arbitrary order.  In addition, this class implements the
  55  * <code>DataInput</code> and <code>DataOutput</code> interfaces to allow
  56  * the reading and writing of Java primitives.
  57  *
  58  * @author Aaron M. Renn (arenn@urbanophile.com)
  59  * @author Tom Tromey (tromey@cygnus.com)
  60  */
  61 public class RandomAccessFile implements DataOutput, DataInput
  62 {
  63
  64   // The underlying file.
  65   private FileChannelImpl ch;
  66   private FileDescriptor fd;
  67   // The corresponding input and output streams.
  68   private DataOutputStream out;
  69   private DataInputStream in;
  70
  71
  72   /**
  73    * This method initializes a new instance of <code>RandomAccessFile</code>
  74    * to read from the specified <code>File</code> object with the specified
  75    * access mode.   The access mode is either "r" for read only access or "rw"
  76    * for read-write access.
  77    * <p>
  78    * Note that a <code>SecurityManager</code> check is made prior to
  79    * opening the file to determine whether or not this file is allowed to
  80    * be read or written.
  81    *
  82    * @param file The <code>File</code> object to read and/or write.
  83    * @param mode "r" for read only or "rw" for read-write access to the file
  84    *
  85    * @exception IllegalArgumentException If <code>mode</code> has an
  86    * illegal value
  87    * @exception SecurityException If the requested access to the file
  88    * is not allowed
  89    * @exception IOException If any other error occurs
  90    */
  91   public RandomAccessFile (File file, String mode)
  92     throws FileNotFoundException
  93   {
  94     this (file.getPath(), mode);
  95   }
  96
  97   /**
  98    * This method initializes a new instance of <code>RandomAccessFile</code>
  99    * to read from the specified file name with the specified access mode.
 100    * The access mode is either "r" for read only access, "rw" for read
 101    * write access, "rws" for synchronized read/write access of both
 102    * content and metadata, or "rwd" for read/write access
 103    * where only content is required to be synchronous.
 104    * <p>
 105    * Note that a <code>SecurityManager</code> check is made prior to
 106    * opening the file to determine whether or not this file is allowed to
 107    * be read or written.
 108    *
 109    * @param fileName The name of the file to read and/or write
 110    * @param mode "r", "rw", "rws", or "rwd"
 111    *
 112    * @exception IllegalArgumentException If <code>mode</code> has an
 113    * illegal value
 114    * @exception SecurityException If the requested access to the file
 115    * is not allowed
 116    * @exception FileNotFoundException If any other error occurs
 117    */
 118   public RandomAccessFile (String fileName, String mode)
 119     throws FileNotFoundException
 120   {
 121     int fdmode;
 122     if (mode.equals("r"))
 123       fdmode = FileChannelImpl.READ;
 124     else if (mode.equals("rw"))
 125       fdmode = FileChannelImpl.READ | FileChannelImpl.WRITE;
 126     else if (mode.equals("rws"))
 127       {
 128         fdmode = (FileChannelImpl.READ | FileChannelImpl.WRITE
 129                   | FileChannelImpl.SYNC);
 130       }
 131     else if (mode.equals("rwd"))
 132       {
 133         fdmode = (FileChannelImpl.READ | FileChannelImpl.WRITE
 134                   | FileChannelImpl.DSYNC);
 135       }
 136     else
 137       throw new IllegalArgumentException ("invalid mode: " + mode);
 138
 139     // The obligatory SecurityManager stuff
 140     SecurityManager s = System.getSecurityManager();
 141     if (s != null)
 142       {
 143         s.checkRead(fileName);
 144
 145         if ((fdmode & FileChannelImpl.WRITE) != 0)
 146           s.checkWrite(fileName);
 147       }
 148
 149     ch = new FileChannelImpl (fileName, fdmode);
 150     fd = new FileDescriptor(ch);
 151     out = new DataOutputStream (new FileOutputStream (fd));
 152     in = new DataInputStream (new FileInputStream (fd));
 153   }
 154
 155   /**
 156    * This method closes the file and frees up all file related system
 157    * resources.  Since most operating systems put a limit on how many files
 158    * may be opened at any given time, it is a good idea to close all files
 159    * when no longer needed to avoid hitting this limit
 160    */
 161   public void close () throws IOException
 162   {
 163     ch.close();
 164   }
 165
 166   /**
 167    * This method returns a <code>FileDescriptor</code> object that
 168    * represents the native file handle for this file.
 169    *
 170    * @return The <code>FileDescriptor</code> object for this file
 171    *
 172    * @exception IOException If an error occurs
 173    */
 174   public final FileDescriptor getFD () throws IOException
 175   {
 176     synchronized (this)
 177       {
 178         if (fd == null)
 179           fd = new FileDescriptor (ch);
 180         return fd;
 181       }
 182   }
 183
 184   /**
 185    * This method returns the current offset in the file at which the next
 186    * read or write will occur
 187    *
 188    * @return The current file position
 189    *
 190    * @exception IOException If an error occurs
 191    */
 192   public long getFilePointer () throws IOException
 193   {
 194     return ch.position();
 195   }
 196
 197   /**
 198    * This method sets the length of the file to the specified length.
 199    * If the currently length of the file is longer than the specified
 200    * length, then the file is truncated to the specified length (the
 201    * file position is set to the end of file in this case).  If the
 202    * current length of the file is shorter than the specified length,
 203    * the file is extended with bytes of an undefined value (the file
 204    * position is unchanged in this case).
 205    * <p>
 206    * The file must be open for write access for this operation to succeed.
 207    *
 208    * @param newLen The new length of the file
 209    *
 210    * @exception IOException If an error occurs
 211    */
 212   public void setLength (long newLen) throws IOException
 213   {
 214     // FIXME: Extending a file should probably be done by one method call.
 215
 216     // FileChannel.truncate() can only shrink a file.
 217     // To expand it we need to seek forward and write at least one byte.
 218     if (newLen < length())
 219       ch.truncate (newLen);
 220     else if (newLen > length())
 221       {
 222         long pos = getFilePointer();
 223         seek(newLen - 1);
 224         write(0);
 225         seek(pos);
 226       }
 227   }
 228
 229   /**
 230    * This method returns the length of the file in bytes
 231    *
 232    * @return The length of the file
 233    *
 234    * @exception IOException If an error occurs
 235    */
 236   public long length () throws IOException
 237   {
 238     return ch.size();
 239   }
 240
 241   /**
 242    * This method reads a single byte of data from the file and returns it
 243    * as an integer.
 244    *
 245    * @return The byte read as an int, or -1 if the end of the file was reached.
 246    *
 247    * @exception IOException If an error occurs
 248    */
 249   public int read () throws IOException
 250   {
 251     return in.read();
 252   }
 253
 254   /**
 255    * This method reads bytes from the file into the specified array.  The
 256    * bytes are stored starting at the beginning of the array and up to
 257    * <code>buf.length</code> bytes can be read.
 258    *
 259    * @param buffer The buffer to read bytes from the file into
 260    *
 261    * @return The actual number of bytes read or -1 if end of file
 262    *
 263    * @exception IOException If an error occurs
 264    */
 265   public int read (byte[] buffer) throws IOException
 266   {
 267     return in.read (buffer);
 268   }
 269
 270   /**
 271    * This methods reads up to <code>len</code> bytes from the file into the
 272    * specified array starting at position <code>offset</code> into the array.
 273    *
 274    * @param buffer The array to read the bytes into
 275    * @param offset The index into the array to start storing bytes
 276    * @param len The requested number of bytes to read
 277    *
 278    * @return The actual number of bytes read, or -1 if end of file
 279    *
 280    * @exception IOException If an error occurs
 281    */
 282   public int read (byte[] buffer, int offset, int len) throws IOException
 283   {
 284     return in.read (buffer, offset, len);
 285   }
 286
 287   /**
 288    * This method reads a Java boolean value from an input stream.  It does
 289    * so by reading a single byte of data.  If that byte is zero, then the
 290    * value returned is <code>false</code>  If the byte is non-zero, then
 291    * the value returned is <code>true</code>
 292    * <p>
 293    * This method can read a <code>boolean</code> written by an object
 294    * implementing the
 295    * <code>writeBoolean()</code> method in the <code>DataOutput</code>
 296    * interface.
 297    *
 298    * @return The <code>boolean</code> value read
 299    *
 300    * @exception EOFException If end of file is reached before reading the
 301    * boolean
 302    * @exception IOException If any other error occurs
 303    */
 304   public final boolean readBoolean () throws IOException
 305   {
 306     return in.readBoolean ();
 307   }
 308
 309   /**
 310    * This method reads a Java byte value from an input stream.  The value
 311    * is in the range of -128 to 127.
 312    * <p>
 313    * This method can read a <code>byte</code> written by an object
 314    * implementing the
 315    * <code>writeByte()</code> method in the <code>DataOutput</code> interface.
 316    *
 317    * @return The <code>byte</code> value read
 318    *
 319    * @exception EOFException If end of file is reached before reading the byte
 320    * @exception IOException If any other error occurs
 321    *
 322    * @see DataOutput
 323    */
 324   public final byte readByte () throws IOException
 325   {
 326     return in.readByte ();
 327   }
 328
 329   /**
 330    * This method reads a Java <code>char</code> value from an input stream.
 331    * It operates by reading two bytes from the stream and converting them to
 332    * a single 16-bit Java <code>char</code>  The two bytes are stored most
 333    * significant byte first (i.e., "big endian") regardless of the native
 334    * host byte ordering.
 335    * <p>
 336    * As an example, if <code>byte1</code> and <code>byte2</code> represent
 337    * the first
 338    * and second byte read from the stream respectively, they will be
 339    * transformed to a <code>char</code> in the following manner:
 340    * <p>
 341    * <code>(char)(((byte1 &amp; 0xFF) &lt;&lt; 8) | (byte2 &amp; 0xFF)</code>
 342    * <p>
 343    * This method can read a <code>char</code> written by an object
 344    * implementing the
 345    * <code>writeChar()</code> method in the <code>DataOutput</code> interface.
 346    *
 347    * @return The <code>char</code> value read
 348    *
 349    * @exception EOFException If end of file is reached before reading the char
 350    * @exception IOException If any other error occurs
 351    *
 352    * @see DataOutput
 353    */
 354   public final char readChar () throws IOException
 355   {
 356     return in.readChar();
 357   }
 358
 359   /**
 360    * This method reads a Java double value from an input stream.  It operates
 361    * by first reading a <code>logn</code> value from the stream by calling the
 362    * <code>readLong()</code> method in this interface, then
 363    * converts that <code>long</code>
 364    * to a <code>double</code> using the <code>longBitsToDouble</code>
 365    * method in the class <code>java.lang.Double</code>
 366    * <p>
 367    * This method can read a <code>double</code> written by an object
 368    * implementing the
 369    * <code>writeDouble()</code> method in the <code>DataOutput</code>
 370    * interface.
 371    *
 372    * @return The <code>double</code> value read
 373    *
 374    * @exception EOFException If end of file is reached before reading
 375    * the double
 376    * @exception IOException If any other error occurs
 377    *
 378    * @see java.lang.Double
 379    * @see DataOutput
 380    */
 381   public final double readDouble () throws IOException
 382   {
 383     return in.readDouble ();
 384   }
 385
 386   /**
 387    * This method reads a Java float value from an input stream.  It operates
 388    * by first reading an <code>int</code> value from the stream by calling the
 389    * <code>readInt()</code> method in this interface, then converts
 390    * that <code>int</code>
 391    * to a <code>float</code> using the <code>intBitsToFloat</code> method in
 392    * the class <code>java.lang.Float</code>
 393    * <p>
 394    * This method can read a <code>float</code> written by an object
 395    * implementing the
 396    * <code>writeFloat()</code> method in the <code>DataOutput</code> interface.
 397    *
 398    * @return The <code>float</code> value read
 399    *
 400    * @exception EOFException If end of file is reached before reading the float
 401    * @exception IOException If any other error occurs
 402    *
 403    * @see java.lang.Float
 404    * @see DataOutput
 405    */
 406   public final float readFloat () throws IOException
 407   {
 408     return in.readFloat();
 409   }
 410
 411   /**
 412    * This method reads raw bytes into the passed array until the array is
 413    * full.  Note that this method blocks until the data is available and
 414    * throws an exception if there is not enough data left in the stream to
 415    * fill the buffer
 416    *
 417    * @param buffer The buffer into which to read the data
 418    *
 419    * @exception EOFException If end of file is reached before filling the
 420    * buffer
 421    * @exception IOException If any other error occurs
 422    */
 423   public final void readFully (byte[] buffer) throws IOException
 424   {
 425     in.readFully(buffer);
 426   }
 427
 428   /**
 429    * This method reads raw bytes into the passed array <code>buf</code>
 430    * starting
 431    * <code>offset</code> bytes into the buffer.  The number of bytes read
 432    * will be
 433    * exactly <code>len</code>  Note that this method blocks until the data is
 434    * available and throws an exception if there is not enough data left in
 435    * the stream to read <code>len</code> bytes.
 436    *
 437    * @param buffer The buffer into which to read the data
 438    * @param offset The offset into the buffer to start storing data
 439    * @param count The number of bytes to read into the buffer
 440    *
 441    * @exception EOFException If end of file is reached before filling
 442    * the buffer
 443    * @exception IOException If any other error occurs
 444    */
 445   public final void readFully (byte[] buffer, int offset, int count)
 446     throws IOException
 447   {
 448     in.readFully (buffer, offset, count);
 449   }
 450
 451   /**
 452    * This method reads a Java <code>int</code> value from an input stream
 453    * It operates by reading four bytes from the stream and converting them to
 454    * a single Java <code>int</code>  The bytes are stored most
 455    * significant byte first (i.e., "big endian") regardless of the native
 456    * host byte ordering.
 457    * <p>
 458    * As an example, if <code>byte1</code> through <code>byte4</code>
 459    * represent the first
 460    * four bytes read from the stream, they will be
 461    * transformed to an <code>int</code> in the following manner:
 462    * <p>
 463    * <code>(int)(((byte1 &amp; 0xFF) &lt;&lt; 24) + ((byte2 &amp; 0xFF) &lt;&lt; 16) +
 464    * ((byte3 &amp; 0xFF) &lt;&lt; 8) + (byte4 &amp; 0xFF)))</code>
 465    * <p>
 466    * The value returned is in the range of 0 to 65535.
 467    * <p>
 468    * This method can read an <code>int</code> written by an object
 469    * implementing the
 470    * <code>writeInt()</code> method in the <code>DataOutput</code> interface.
 471    *
 472    * @return The <code>int</code> value read
 473    *
 474    * @exception EOFException If end of file is reached before reading the int
 475    * @exception IOException If any other error occurs
 476    *
 477    * @see DataOutput
 478    */
 479   public final int readInt () throws IOException
 480   {
 481     return in.readInt();
 482   }
 483
 484   /**
 485    * This method reads the next line of text data from an input stream.
 486    * It operates by reading bytes and converting those bytes to
 487    * <code>char</code>
 488    * values by treating the byte read as the low eight bits of the
 489    * <code>char</code>
 490    * and using <code>0</code> as the high eight bits.  Because of this, it does
 491    * not support the full 16-bit Unicode character set.
 492    * <p>
 493    * The reading of bytes ends when either the end of file or a line terminator
 494    * is encountered.  The bytes read are then returned as a <code>String</code>
 495    * A line terminator is a byte sequence consisting of either
 496    * <code>\r</code> <code>\n</code> or <code>\r\n</code>  These
 497    * termination charaters are
 498    * discarded and are not returned as part of the string.
 499    * <p>
 500    * This method can read data that was written by an object implementing the
 501    * <code>writeLine()</code> method in <code>DataOutput</code>
 502    *
 503    * @return The line read as a <code>String</code>
 504    *
 505    * @exception IOException If an error occurs
 506    *
 507    * @see DataOutput
 508    */
 509   public final String readLine () throws IOException
 510   {
 511     return in.readLine ();
 512   }
 513
 514   /**
 515    * This method reads a Java long value from an input stream
 516    * It operates by reading eight bytes from the stream and converting them to
 517    * a single Java <code>long</code>  The bytes are stored most
 518    * significant byte first (i.e., "big endian") regardless of the native
 519    * host byte ordering.
 520    * <p>
 521    * As an example, if <code>byte1</code> through <code>byte8</code>
 522    * represent the first
 523    * eight bytes read from the stream, they will be
 524    * transformed to an <code>long</code> in the following manner:
 525    * <p>
 526    * <code>
 527    * (long)((((long)byte1 &amp; 0xFF) &lt;&lt; 56) + (((long)byte2 &amp; 0xFF) &lt;&lt; 48) +
 528    * (((long)byte3 &amp; 0xFF) &lt;&lt; 40) + (((long)byte4 &amp; 0xFF) &lt;&lt; 32) +
 529    * (((long)byte5 &amp; 0xFF) &lt;&lt; 24) + (((long)byte6 &amp; 0xFF) &lt;&lt; 16) +
 530    * (((long)byte7 &amp; 0xFF) &lt;&lt; 8) + ((long)byte9 &amp; 0xFF)))</code>
 531    * <p>
 532    * The value returned is in the range of 0 to 65535.
 533    * <p>
 534    * This method can read an <code>long</code> written by an object
 535    * implementing the
 536    * <code>writeLong()</code> method in the <code>DataOutput</code> interface.
 537    *
 538    * @return The <code>long</code> value read
 539    *
 540    * @exception EOFException If end of file is reached before reading the long
 541    * @exception IOException If any other error occurs
 542    *
 543    * @see DataOutput
 544    */
 545   public final long readLong () throws IOException
 546   {
 547     return in.readLong();
 548   }
 549
 550   /**
 551    * This method reads a signed 16-bit value into a Java in from the stream.
 552    * It operates by reading two bytes from the stream and converting them to
 553    * a single 16-bit Java <code>short</code>  The two bytes are stored most
 554    * significant byte first (i.e., "big endian") regardless of the native
 555    * host byte ordering.
 556    * <p>
 557    * As an example, if <code>byte1</code> and <code>byte2</code>
 558    * represent the first
 559    * and second byte read from the stream respectively, they will be
 560    * transformed to a <code>short</code> in the following manner:
 561    * <p>
 562    * <code>(short)(((byte1 &amp; 0xFF) &lt;&lt; 8) | (byte2 &amp; 0xFF)</code>
 563    * <p>
 564    * The value returned is in the range of -32768 to 32767.
 565    * <p>
 566    * This method can read a <code>short</code> written by an object
 567    * implementing the
 568    * <code>writeShort()</code> method in the <code>DataOutput</code> interface.
 569    *
 570    * @return The <code>short</code> value read
 571    *
 572    * @exception EOFException If end of file is reached before reading the value
 573    * @exception IOException If any other error occurs
 574    *
 575    * @see DataOutput
 576    */
 577   public final short readShort () throws IOException
 578   {
 579     return in.readShort();
 580   }
 581
 582   /**
 583    * This method reads 8 unsigned bits into a Java <code>int</code> value
 584    * from the
 585    * stream. The value returned is in the range of 0 to 255.
 586    * <p>
 587    * This method can read an unsigned byte written by an object implementing
 588    * the <code>writeUnsignedByte()</code> method in the
 589    * <code>DataOutput</code> interface.
 590    *
 591    * @return The unsigned bytes value read as a Java <code>int</code>
 592    *
 593    * @exception EOFException If end of file is reached before reading the value
 594    * @exception IOException If any other error occurs
 595    *
 596    * @see DataOutput
 597    */
 598   public final int readUnsignedByte () throws IOException
 599   {
 600     return in.readUnsignedByte();
 601   }
 602
 603   /**
 604    * This method reads 16 unsigned bits into a Java int value from the stream.
 605    * It operates by reading two bytes from the stream and converting them to
 606    * a single Java <code>int</code>  The two bytes are stored most
 607    * significant byte first (i.e., "big endian") regardless of the native
 608    * host byte ordering.
 609    * <p>
 610    * As an example, if <code>byte1</code> and <code>byte2</code>
 611    * represent the first
 612    * and second byte read from the stream respectively, they will be
 613    * transformed to an <code>int</code> in the following manner:
 614    * <p>
 615    * <code>(int)(((byte1 &amp; 0xFF) &lt;&lt; 8) + (byte2 &amp; 0xFF))</code>
 616    * <p>
 617    * The value returned is in the range of 0 to 65535.
 618    * <p>
 619    * This method can read an unsigned short written by an object implementing
 620    * the <code>writeUnsignedShort()</code> method in the
 621    * <code>DataOutput</code> interface.
 622    *
 623    * @return The unsigned short value read as a Java <code>int</code>
 624    *
 625    * @exception EOFException If end of file is reached before reading the value
 626    * @exception IOException If any other error occurs
 627    */
 628   public final int readUnsignedShort () throws IOException
 629   {
 630     return in.readUnsignedShort();
 631   }
 632
 633   /**
 634    * This method reads a <code>String</code> from an input stream that
 635    * is encoded in
 636    * a modified UTF-8 format.  This format has a leading two byte sequence
 637    * that contains the remaining number of bytes to read.  This two byte
 638    * sequence is read using the <code>readUnsignedShort()</code> method of this
 639    * interface.
 640    * <p>
 641    * After the number of remaining bytes have been determined, these bytes
 642    * are read an transformed into <code>char</code> values.
 643    * These <code>char</code> values
 644    * are encoded in the stream using either a one, two, or three byte format.
 645    * The particular format in use can be determined by examining the first
 646    * byte read.
 647    * <p>
 648    * If the first byte has a high order bit of 0 then
 649    * that character consists on only one byte.  This character value consists
 650    * of seven bits that are at positions 0 through 6 of the byte.  As an
 651    * example, if <code>byte1</code> is the byte read from the stream, it would
 652    * be converted to a <code>char</code> like so:
 653    * <p>
 654    * <code>(char)byte1</code>
 655    * <p>
 656    * If the first byte has <code>110</code> as its high order bits, then the
 657    * character consists of two bytes.  The bits that make up the character
 658    * value are in positions 0 through 4 of the first byte and bit positions
 659    * 0 through 5 of the second byte.  (The second byte should have
 660    * 10 as its high order bits).  These values are in most significant
 661    * byte first (i.e., "big endian") order.
 662    * <p>
 663    * As an example, if <code>byte1</code> and <code>byte2</code>
 664    * are the first two bytes
 665    * read respectively, and the high order bits of them match the patterns
 666    * which indicate a two byte character encoding, then they would be
 667    * converted to a Java <code>char</code> like so:
 668    * <p>
 669    * <code>(char)(((byte1 & 0x1F) << 6) | (byte2 & 0x3F))</code>
 670    * <p>
 671    * If the first byte has a <code>1110</code> as its high order bits, then the
 672    * character consists of three bytes.  The bits that make up the character
 673    * value are in positions 0 through 3 of the first byte and bit positions
 674    * 0 through 5 of the other two bytes.  (The second and third bytes should
 675    * have <code>10</code> as their high order bits).  These values are in most
 676    * significant byte first (i.e., "big endian") order.
 677    * <p>
 678    * As an example, if <code>byte1</code> <code>byte2</code>
 679    * and <code>byte3</code> are the
 680    * three bytes read, and the high order bits of them match the patterns
 681    * which indicate a three byte character encoding, then they would be
 682    * converted to a Java <code>char</code> like so:
 683    * <p>
 684    * <code>(char)(((byte1 & 0x0F) << 12) | ((byte2 & 0x3F) << 6) |
 685    * (byte3 & 0x3F))</code>
 686    * <p>
 687    * Note that all characters are encoded in the method that requires the
 688    * fewest number of bytes with the exception of the character with the
 689    * value of <code>&#92;u0000</code> which is encoded as two bytes.  This is
 690    * a  modification of the UTF standard used to prevent C language style
 691    * <code>NUL</code> values from appearing in the byte stream.
 692    * <p>
 693    * This method can read data that was written by an object implementing the
 694    * <code>writeUTF()</code> method in <code>DataOutput</code>
 695    *
 696    * @return The <code>String</code> read
 697    *
 698    * @exception EOFException If end of file is reached before reading the
 699    * String
 700    * @exception UTFDataFormatException If the data is not in UTF-8 format
 701    * @exception IOException If any other error occurs
 702    *
 703    * @see DataOutput
 704    */
 705   public final String readUTF () throws IOException
 706   {
 707     return in.readUTF();
 708   }
 709
 710   /**
 711    * This method sets the current file position to the specified offset
 712    * from the beginning of the file.  Note that some operating systems will
 713    * allow the file pointer to be set past the current end of the file.
 714    *
 715    * @param pos The offset from the beginning of the file at which to set
 716    * the file pointer
 717    *
 718    * @exception IOException If an error occurs
 719    */
 720   public void seek (long pos) throws IOException
 721   {
 722     ch.position(pos);
 723   }
 724
 725   /**
 726    * This method attempts to skip and discard the specified number of bytes
 727    * in the input stream.  It may actually skip fewer bytes than requested.
 728    * The actual number of bytes skipped is returned.  This method will not
 729    * skip any bytes if passed a negative number of bytes to skip.
 730    *
 731    * @param numBytes The requested number of bytes to skip.
 732    *
 733    * @return The number of bytes actually skipped.
 734    *
 735    * @exception IOException If an error occurs.
 736    */
 737   public int skipBytes (int numBytes) throws IOException
 738   {
 739     if (numBytes < 0)
 740       throw new IllegalArgumentException ("Can't skip negative bytes: " +
 741                                           numBytes);
 742
 743     if (numBytes == 0)
 744       return 0;
 745
 746     long oldPos = ch.position();
 747     long newPos = oldPos + numBytes;
 748     long size = ch.size();
 749     if (newPos > size)
 750       newPos = size;
 751     ch.position(newPos);
 752     return (int) (ch.position() - oldPos);
 753   }
 754
 755   /**
 756    * This method writes a single byte of data to the file. The file must
 757    * be open for read-write in order for this operation to succeed.
 758    *
 759    * @param oneByte The byte of data to write, passed as an int.
 760    *
 761    * @exception IOException If an error occurs
 762    */
 763   public void write (int oneByte) throws IOException
 764   {
 765     out.write(oneByte);
 766   }
 767
 768   /**
 769    * This method writes all the bytes in the specified array to the file.
 770    * The file must be open read-write in order for this operation to succeed.
 771    *
 772    * @param buffer The array of bytes to write to the file
 773    */
 774   public void write (byte[] buffer) throws IOException
 775   {
 776     out.write(buffer);
 777   }
 778
 779   /**
 780    * This method writes <code>len</code> bytes to the file from the specified
 781    * array starting at index <code>offset</code> into the array.
 782    *
 783    * @param buffer The array of bytes to write to the file
 784    * @param offset The index into the array to start writing file
 785    * @param len The number of bytes to write
 786    *
 787    * @exception IOException If an error occurs
 788    */
 789   public void write (byte[] buffer, int offset, int len) throws IOException
 790   {
 791     out.write (buffer, offset, len);
 792   }
 793
 794   /**
 795    * This method writes a Java <code>boolean</code> to the underlying output
 796    * stream. For a value of <code>true</code>, 1 is written to the stream.
 797    * For a value of <code>false</code>, 0 is written.
 798    *
 799    * @param val The <code>boolean</code> value to write to the stream
 800    *
 801    * @exception IOException If an error occurs
 802    */
 803   public final void writeBoolean (boolean val) throws IOException
 804   {
 805     out.writeBoolean(val);
 806   }
 807
 808   /**
 809    * This method writes a Java <code>byte</code> value to the underlying
 810    * output stream.
 811    *
 812    * @param val The <code>byte</code> to write to the stream, passed
 813    * as an <code>int</code>.
 814    *
 815    * @exception IOException If an error occurs
 816    */
 817   public final void writeByte (int val) throws IOException
 818   {
 819     out.writeByte(val);
 820   }
 821
 822   /**
 823    * This method writes a Java <code>short</code> to the stream, high byte
 824    * first.  This method requires two bytes to encode the value.
 825    *
 826    * @param val The <code>short</code> value to write to the stream,
 827    * passed as an <code>int</code>.
 828    *
 829    * @exception IOException If an error occurs
 830    */
 831   public final void writeShort (int val) throws IOException
 832   {
 833     out.writeShort(val);
 834   }
 835
 836   /**
 837    * This method writes a single <code>char</code> value to the stream,
 838    * high byte first.
 839    *
 840    * @param val The <code>char</code> value to write, passed as
 841    * an <code>int</code>.
 842    *
 843    * @exception IOException If an error occurs
 844    */
 845   public final void writeChar (int val) throws IOException
 846   {
 847     out.writeChar(val);
 848   }
 849
 850   /**
 851    * This method writes a Java <code>int</code> to the stream, high bytes
 852    * first.  This method requires four bytes to encode the value.
 853    *
 854    * @param val The <code>int</code> value to write to the stream.
 855    *
 856    * @exception IOException If an error occurs
 857    */
 858   public final void writeInt (int val) throws IOException
 859   {
 860     out.writeInt(val);
 861   }
 862
 863   /**
 864    * This method writes a Java <code>long</code> to the stream, high bytes
 865    * first.  This method requires eight bytes to encode the value.
 866    *
 867    * @param val The <code>long</code> value to write to the stream.
 868    *
 869    * @exception IOException If an error occurs
 870    */
 871   public final void writeLong (long val) throws IOException
 872   {
 873     out.writeLong(val);
 874   }
 875
 876   /**
 877    * This method writes a Java <code>float</code> value to the stream.  This
 878    * value is written by first calling the method
 879    * <code>Float.floatToIntBits</code>
 880    * to retrieve an <code>int</code> representing the floating point number,
 881    * then writing this <code>int</code> value to the stream exactly the same
 882    * as the <code>writeInt()</code> method does.
 883    *
 884    * @param val The floating point number to write to the stream.
 885    *
 886    * @exception IOException If an error occurs
 887    *
 888    * @see #writeInt(int)
 889    */
 890   public final void writeFloat (float val) throws IOException
 891   {
 892     out.writeFloat(val);
 893   }
 894
 895   /**
 896    * This method writes a Java <code>double</code> value to the stream.  This
 897    * value is written by first calling the method
 898    * <code>Double.doubleToLongBits</code>
 899    * to retrieve an <code>long</code> representing the floating point number,
 900    * then writing this <code>long</code> value to the stream exactly the same
 901    * as the <code>writeLong()</code> method does.
 902    *
 903    * @param val The double precision floating point number to write to the
 904    * stream.
 905    *
 906    * @exception IOException If an error occurs
 907    *
 908    * @see #writeLong(long)
 909    */
 910   public final void writeDouble (double val) throws IOException
 911   {
 912     out.writeDouble(val);
 913   }
 914
 915   /**
 916    * This method writes all the bytes in a <code>String</code> out to the
 917    * stream.  One byte is written for each character in the <code>String</code>.
 918    * The high eight bits of each character are discarded.
 919    *
 920    * @param val The <code>String</code> to write to the stream
 921    *
 922    * @exception IOException If an error occurs
 923    */
 924   public final void writeBytes (String val) throws IOException
 925   {
 926     out.writeBytes(val);
 927   }
 928
 929   /**
 930    * This method writes all the characters in a <code>String</code> to the
 931    * stream.  There will be two bytes for each character value.  The high
 932    * byte of the character will be written first.
 933    *
 934    * @param val The <code>String</code> to write to the stream.
 935    *
 936    * @exception IOException If an error occurs
 937    */
 938   public final void writeChars (String val) throws IOException
 939   {
 940     out.writeChars(val);
 941   }
 942
 943   /**
 944    * This method writes a Java <code>String</code> to the stream in a modified
 945    * UTF-8 format.  First, two bytes are written to the stream indicating the
 946    * number of bytes to follow.  Note that this is the number of bytes in the
 947    * encoded <code>String</code> not the <code>String</code> length.  Next
 948    * come the encoded characters.  Each character in the <code>String</code>
 949    * is encoded as either one, two or three bytes.  For characters in the
 950    * range of <code>&#92;u0001</code> to <code>&#92;u007F</code>,
 951    * one byte is used.  The character
 952    * value goes into bits 0-7 and bit eight is 0.  For characters in the range
 953    * of <code>&#92;u0080</code> to <code>&#92;u007FF</code>, two
 954    * bytes are used.  Bits
 955    * 6-10 of the character value are encoded bits 0-4 of the first byte, with
 956    * the high bytes having a value of "110".  Bits 0-5 of the character value
 957    * are stored in bits 0-5 of the second byte, with the high bits set to
 958    * "10".  This type of encoding is also done for the null character
 959    * <code>&#92;u0000</code>.  This eliminates any C style NUL character values
 960    * in the output.  All remaining characters are stored as three bytes.
 961    * Bits 12-15 of the character value are stored in bits 0-3 of the first
 962    * byte.  The high bits of the first bytes are set to "1110".  Bits 6-11
 963    * of the character value are stored in bits 0-5 of the second byte.  The
 964    * high bits of the second byte are set to "10".  And bits 0-5 of the
 965    * character value are stored in bits 0-5 of byte three, with the high bits
 966    * of that byte set to "10".
 967    *
 968    * @param val The <code>String</code> to write to the output in UTF format
 969    *
 970    * @exception IOException If an error occurs
 971    */
 972   public final void writeUTF (String val) throws IOException
 973   {
 974     out.writeUTF(val);
 975   }
 976
 977   /**
 978    * This method creates a java.nio.channels.FileChannel.
 979    * Nio does not allow one to create a file channel directly.
 980    * A file channel must be created by first creating an instance of
 981    * Input/Output/RandomAccessFile and invoking the getChannel() method on it.
 982    */
 983   public final synchronized FileChannel getChannel ()
 984   {
 985     return ch;
 986   }
 987 }