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