/[classpath]/classpath/java/io/RandomAccessFile.java
ViewVC logotype

Diff of /classpath/java/io/RandomAccessFile.java

Parent Directory Parent Directory | Revision Log Revision Log | View Patch Patch

revision 1.13 by daryllee, Fri Dec 27 18:40:09 2002 UTC revision 1.14 by arenn, Sun Mar 2 01:24:34 2003 UTC
# Line 1  Line 1 
1  /* RandomAccessFile.java -- Class supporting random file I/O  /* RandomAccessFile.java -- Class supporting random file I/O
2     Copyright (C) 1998 Free Software Foundation, Inc.     Copyright (C) 1998, 2003 Free Software Foundation, Inc.
3    
4  This file is part of GNU Classpath.  This file is part of GNU Classpath.
5    
# Line 50  import gnu.java.nio.FileChannelImpl; Line 50  import gnu.java.nio.FileChannelImpl;
50    * <code>DataInput</code> and <code>DataOutput</code> interfaces to allow    * <code>DataInput</code> and <code>DataOutput</code> interfaces to allow
51    * the reading and writing of Java primitives.    * the reading and writing of Java primitives.
52    *    *
   * @version 0.0  
   *  
53    * @author Aaron M. Renn (arenn@urbanophile.com)    * @author Aaron M. Renn (arenn@urbanophile.com)
54    */    */
55  public class RandomAccessFile implements DataOutput, DataInput  public class RandomAccessFile implements DataOutput, DataInput
# Line 64  public class RandomAccessFile implements Line 62  public class RandomAccessFile implements
62          System.loadLibrary ("javaio");          System.loadLibrary ("javaio");
63        }        }
64    }    }
65      
66  /*************************************************************************/    /*************************************************************************/
67      
68  /*    /*
69   * Instance Variables     * Instance Variables
70   */     */
71      
72  /**    /**
73    * The native file descriptor for this file      * The native file descriptor for this file
74    */      */
75  private int native_fd;    private int native_fd;
76      
77  /**    /**
78    * Whether or not this file is open in read only mode      * Whether or not this file is open in read only mode
79    */      */
80  private boolean read_only;    private boolean read_only;
81      
82  /*************************************************************************/    // Used for DataOutput methods writing values to the underlying file
83      private byte[] buf = new byte[8];
84  /*    
85   * Constructors    /*************************************************************************/
86   */    
87      /*
88  /**     * Constructors
89    * This method initializes a new instance of <code>RandomAccessFile</code>     */
90    * to read from the specified file name with the specified access mode.    
91    * The access mode is either "r" for read only access or "rw" for read    /**
92    * write access.      * This method initializes a new instance of <code>RandomAccessFile</code>
93    * <p>      * to read from the specified file name with the specified access mode.
94    * Note that a <code>SecurityManager</code> check is made prior to      * The access mode is either "r" for read only access or "rw" for read
95    * opening the file to determine whether or not this file is allowed to      * write access.
96    * be read or written.      * <p>
97    *      * Note that a <code>SecurityManager</code> check is made prior to
98    * @param name The name of the file to read and/or write      * opening the file to determine whether or not this file is allowed to
99    * @param mode "r" for read only or "rw" for read-write access to the file      * be read or written.
100    *      *
101    * @exception IllegalArgumentException If <code>mode</code> has an illegal value      * @param name The name of the file to read and/or write
102    * @exception SecurityException If the requested access to the file is not allowed      * @param mode "r" for read only or "rw" for read-write access to the file
103    * @exception IOException If any other error occurs      *
104    */      * @exception IllegalArgumentException If <code>mode</code> has an
105  public      * illegal value
106  RandomAccessFile(String name, String mode) throws IllegalArgumentException,      * @exception SecurityException If the requested access to the file
107                                                    SecurityException,      * is not allowed
108                                                    IOException      * @exception IOException If any other error occurs
109  {      */
110    this(new File(name), mode);    public
111  }    RandomAccessFile(String name, String mode) throws IllegalArgumentException,
112                                                        SecurityException,
113  /*************************************************************************/                                                      IOException
114      {
115  /**      this(new File(name), mode);
116    * This method initializes a new instance of <code>RandomAccessFile</code>    }
117    * to read from the specified <code>File</code> object with the specified    
118    * access mode.   The access mode is either "r" for read only access or "rw"    /*************************************************************************/
119    * for read-write access.    
120    * <p>    /**
121    * Note that a <code>SecurityManager</code> check is made prior to      * This method initializes a new instance of <code>RandomAccessFile</code>
122    * opening the file to determine whether or not this file is allowed to      * to read from the specified <code>File</code> object with the specified
123    * be read or written.      * access mode.   The access mode is either "r" for read only access or "rw"
124    *      * for read-write access.
125    * @param file The <code>File</code> object to read and/or write.      * <p>
126    * @param mode "r" for read only or "rw" for read-write access to the file      * Note that a <code>SecurityManager</code> check is made prior to
127    *      * opening the file to determine whether or not this file is allowed to
128    * @exception IllegalArgumentException If <code>mode</code> has an illegal value      * be read or written.
129    * @exception SecurityException If the requested access to the file is not allowed      *
130    * @exception IOException If any other error occurs      * @param file The <code>File</code> object to read and/or write.
131    */      * @param mode "r" for read only or "rw" for read-write access to the file
132  public      *
133  RandomAccessFile(File file, String mode) throws IllegalArgumentException,      * @exception IllegalArgumentException If <code>mode</code> has an
134                                                    SecurityException,      * illegal value
135                                                    IOException      * @exception SecurityException If the requested access to the file
136  {      * is not allowed
137    // Check the mode      * @exception IOException If any other error occurs
138    if (!mode.equals("r") && !mode.equals("rw"))      */
139      throw new IllegalArgumentException("Bad mode value: " + mode);    public RandomAccessFile(File file, String mode)
140         throws IllegalArgumentException, SecurityException, IOException
141    // The obligatory SecurityManager stuff    {
142    SecurityManager sm = System.getSecurityManager();      // Check the mode
143    if (sm != null)      if (!mode.equals("r") && !mode.equals("rw"))
144      {        throw new IllegalArgumentException("Bad mode value: " + mode);
145        if (mode.equals("r"))    
146          sm.checkRead(file.getPath());      // The obligatory SecurityManager stuff
147        else if (mode.equals("rw"))      SecurityManager sm = System.getSecurityManager();
148          sm.checkWrite(file.getPath());      if (sm != null)
149      }        {
150            if (mode.equals("r"))
151    if (mode.equals("r"))            sm.checkRead(file.getPath());
152      read_only = true;          else if (mode.equals("rw"))
153              sm.checkWrite(file.getPath());
154    if (read_only)        }
155      native_fd = open(file.getPath(), true);    
156    else      if (mode.equals("r"))
157      native_fd = open(file.getPath(), false);        read_only = true;
158  }    
159        if (read_only)
160  /*************************************************************************/        native_fd = open(file.getPath(), true);
161        else
162  /*        native_fd = open(file.getPath(), false);
163   * Instance Methods    }
164   */    
165      /*************************************************************************/
166  /**    
167    * This native method opens the file with the desired access mode    /*
168    */     * Instance Methods
169  private native int     */
170  open(String name, boolean read_only) throws IOException;    
171      /**
172  /*************************************************************************/      * This native method opens the file with the desired access mode
173        */
174  /**    private native int open(String name, boolean read_only) throws IOException;
175    * This method closes the file and frees up all file related system    
176    * resources.  Since most operating systems put a limit on how many files    /*************************************************************************/
177    * may be opened at any given time, it is a good idea to close all files    
178    * when no longer needed to avoid hitting this limit    /**
179    */      * This method closes the file and frees up all file related system
180  public void      * resources.  Since most operating systems put a limit on how many files
181  close() throws IOException      * may be opened at any given time, it is a good idea to close all files
182  {      * when no longer needed to avoid hitting this limit
183    if (native_fd != -1)      */
184      closeInternal(native_fd);    public void close() throws IOException
185      {
186    native_fd = -1;      if (native_fd != -1)
187  }        closeInternal(native_fd);
188      
189  /*************************************************************************/      native_fd = -1;
190      }
191  /**    
192    * Native methods that actually closes the file    /*************************************************************************/
193    */    
194  private native void    /**
195  closeInternal(int native_fd) throws IOException;      * Native methods that actually closes the file
196        */
197  /*************************************************************************/    private native void closeInternal(int native_fd) throws IOException;
198      
199  /**    /*************************************************************************/
200    * This method returns a <code>FileDescriptor</code> object that    
201    * represents the native file handle for this file.    /**
202    *      * This method returns a <code>FileDescriptor</code> object that
203    * @return The <code>FileDescriptor</code> object for this file      * represents the native file handle for this file.
204    *      *
205    * @exception IOException If an error occurs      * @return The <code>FileDescriptor</code> object for this file
206    */      *
207  public final FileDescriptor      * @exception IOException If an error occurs
208  getFD() throws IOException      */
209  {    public final FileDescriptor getFD() throws IOException
210    return(new FileDescriptor(native_fd));    {
211  }      return(new FileDescriptor(native_fd));
212      }
213  /*************************************************************************/    
214      /*************************************************************************/
215  /**    
216    * This method returns the current offset in the file at which the next    /**
217    * read or write will occur      * This method returns the current offset in the file at which the next
218    *      * read or write will occur
219    * @return The current file position      *
220    *      * @return The current file position
221    * @exception IOException If an error occurs      *
222    */      * @exception IOException If an error occurs
223  public long      */
224  getFilePointer() throws IOException    public long getFilePointer() throws IOException
225  {    {
226    return(getFilePointerInternal(native_fd));      return(getFilePointerInternal(native_fd));
227  }    }
228      
229  /*************************************************************************/    /*************************************************************************/
230      
231  /**    /**
232    * This native method actually retrieves the file pointer      * This native method actually retrieves the file pointer
233    */      */
234  private native long    private native long getFilePointerInternal(int native_fd) throws IOException;
235  getFilePointerInternal(int native_fd) throws IOException;    
236      /*************************************************************************/
237  /*************************************************************************/    
238      /**
239  /**      * This method returns the length of the file in bytes
240    * This method returns the length of the file in bytes      *
241    *      * @return The length of the file
242    * @return The length of the file      *
243    *      * @exception IOException If an error occurs
244    * @exception IOException If an error occurs      */
245    */    public long length() throws IOException
246  public long    {
247  length() throws IOException      return(lengthInternal(native_fd));
248  {    }
249    return(lengthInternal(native_fd));    
250  }    /*************************************************************************/
251      
252  /*************************************************************************/    /**
253        * This native method determines the actual file length
254  /**      */
255    * This native method determines the actual file length    private native long lengthInternal(int native_fd) throws IOException;
256    */    
257  private native long    /*************************************************************************/
258  lengthInternal(int native_fd) throws IOException;    
259      /**
260  /*************************************************************************/      * This method sets the current file position to the specified offset
261        * from the beginning of the file.  Note that some operating systems will
262  /**      * allow the file pointer to be set past the current end of the file.
263    * This method sets the current file position to the specified offset      *
264    * from the beginning of the file.  Note that some operating systems will      * @param pos The offset from the beginning of the file at which to set
265    * allow the file pointer to be set past the current end of the file.      * the file pointer
266    *      *
267    * @param pos The offset from the beginning of the file at which to set the file pointer      * @exception IOException If an error occurs
268    *      */
269    * @exception IOException If an error occurs    public void seek(long pos) throws IOException
270    */    {
271  public void      seekInternal(native_fd, pos);
272  seek(long pos) throws IOException    }
273  {    
274    seekInternal(native_fd, pos);    /*************************************************************************/
275  }    
276      /**
277  /*************************************************************************/      * This native method does the actual file offset seeking
278        */
279  /**    private native void seekInternal(int native_fd, long pos) throws IOException;
280    * This native method does the actual file offset seeking    
281    */    /*************************************************************************/
282  private native void    
283  seekInternal(int native_fd, long pos) throws IOException;    /**
284        * This method sets the length of the file to the specified length.  If
285  /*************************************************************************/      * the currently length of the file is longer than the specified length,
286        * then the file is truncated to the specified length.  If the current
287  /**      * length of the file is shorter than the specified length, the file
288    * This method sets the length of the file to the specified length.  If      * is extended with bytes of an undefined value.
289    * the currently length of the file is longer than the specified length,      *  <p>
290    * then the file is truncated to the specified length.  If the current      * The file must be open for write access for this operation to succeed.
291    * length of the file is shorter than the specified length, the file      *
292    * is extended with bytes of an undefined value.      * @param newlen The new length of the file
293    *  <p>      *
294    * The file must be open for write access for this operation to succeed.      * @exception IOException If an error occurs
295    *      */
296    * @param newlen The new length of the file    public void setLength(long newlen) throws IOException
297    *    {
298    * @exception IOException If an error occurs      if (read_only)
299    */        throw new IOException("File is open read only");
300  public void    
301  setLength(long newlen) throws IOException      setLengthInternal(native_fd, newlen);
302  {    }
303    if (read_only)    
304      throw new IOException("File is open read only");    /*************************************************************************/
305      
306    setLengthInternal(native_fd, newlen);    /**
307  }      * This native method does the actual work of setting the file length
308        */
309  /*************************************************************************/    private native void setLengthInternal(int native_fd, long newlen)
310        throws IOException;
311  /**    
312    * This native method does the actual work of setting the file length    /*************************************************************************/
313    */    
314  private native void    /**
315  setLengthInternal(int native_fd, long newlen) throws IOException;      * This method reads a single byte of data from the file and returns it
316        * as an integer.
317  /*************************************************************************/      *
318        * @return The byte read as an int, or -1 if the end of the file was reached.
319  /**      *
320    * This method reads a single byte of data from the file and returns it      * @exception IOException If an error occurs
321    * as an integer.      */
322    *    public synchronized int read() throws IOException
323    * @return The byte read as an int, or -1 if the end of the file was reached.    {
324    *      int rc = readInternal(native_fd, buf, 0, 1);
325    * @exception IOException If an error occurs      if (rc == 0)
326    */        return(-1);
327  public int    
328  read() throws IOException      return(buf[0] & 0xFF);
329  {    }
330    byte[] buf = new byte[1];    
331      /*************************************************************************/
332    int rc = readInternal(native_fd, buf, 0, buf.length);    
333    if (rc == 0)    /**
334      return(-1);      * This method reads bytes from the file into the specified array.  The
335        * bytes are stored starting at the beginning of the array and up to
336    return(buf[0] & 0xFF);      * <code>buf.length</code> bytes can be read.
337  }      *
338        * @param buf The buffer to read bytes from the file into
339  /*************************************************************************/      *
340        * @return The actual number of bytes read or -1 if end of file
341  /**      *
342    * This method reads bytes from the file into the specified array.  The      * @exception IOException If an error occurs
343    * bytes are stored starting at the beginning of the array and up to      */
344    * <code>buf.length</code> bytes can be read.    public int read(byte[] buf) throws IOException
345    *    {
346    * @param buf The buffer to read bytes from the file into      int rc = readInternal(native_fd, buf, 0, buf.length);
347    *      if (rc == 0)
348    * @return The actual number of bytes read or -1 if end of file        return(-1);
349    *      else
350    * @exception IOException If an error occurs        return(rc);
351    */    }
352  public int    
353  read(byte[] buf) throws IOException    /*************************************************************************/
354  {    
355    int rc = readInternal(native_fd, buf, 0, buf.length);    /**
356    if (rc == 0)      * This methods reads up to <code>len</code> bytes from the file into the s
357      return(-1);      * pecified array starting at position <code>offset</code> into the array.
358    else      *
359      return(rc);      * @param buf The array to read the bytes into
360  }      * @param offset The index into the array to start storing bytes
361        * @param len The requested number of bytes to read
362  /*************************************************************************/      *
363        * @param len The actual number of bytes read, or -1 if end of file
364  /**      *
365    * This methods reads up to <code>len</code> bytes from the file into the s      * @exception IOException If an error occurs
366    * pecified array starting at position <code>offset</code> into the array.      */
367    *    public int read(byte[] buf, int offset, int len) throws IOException
368    * @param buf The array to read the bytes into    {
369    * @param offset The index into the array to start storing bytes      int rc = readInternal(native_fd, buf, offset, len);
370    * @param len The requested number of bytes to read      if (rc == 0)
371    *        return(-1);
372    * @param len The actual number of bytes read, or -1 if end of file      else
373    *        return(rc);
374    * @exception IOException If an error occurs    }
375    */    
376  public int    /*************************************************************************/
377  read(byte[] buf, int offset, int len) throws IOException    
378  {    /**
379    int rc = readInternal(native_fd, buf, offset, len);      * This native method actually reads the bytes from the file
380    if (rc == 0)      */
381      return(-1);    private native int readInternal(int native_fd, byte[] buf,
382    else                                    int offset, int len);
383      return(rc);    
384  }    /*************************************************************************/
385      
386  /*************************************************************************/    /**
387        * This method reads a Java boolean value from an input stream.  It does
388  /**      * so by reading a single byte of data.  If that byte is zero, then the
389    * This native method actually reads the bytes from the file      * value returned is <code>false</code>  If the byte is non-zero, then
390    */      * the value returned is <code>true</code>
391  private native int      * <p>
392  readInternal(int native_fd, byte[] buf, int offset, int len);      * This method can read a <code>boolean</code> written by an object
393        * implementing the
394  /*************************************************************************/      * <code>writeBoolean()</code> method in the <code>DataOutput</code>
395        * interface.
396  /**      *
397    * This method reads a Java boolean value from an input stream.  It does      * @return The <code>boolean</code> value read
398    * so by reading a single byte of data.  If that byte is zero, then the      *
399    * value returned is <code>false</code>  If the byte is non-zero, then      * @exception EOFException If end of file is reached before reading the
400    * the value returned is <code>true</code>      * boolean
401    * <p>      * @exception IOException If any other error occurs
402    * This method can read a <code>boolean</code> written by an object implementing the      */
403    * <code>writeBoolean()</code> method in the <code>DataOutput</code> interface.    public final boolean readBoolean() throws EOFException, IOException
404    *    {
405    * @return The <code>boolean</code> value read      int byte_read = read();
406    *    
407    * @exception EOFException If end of file is reached before reading the boolean      if (byte_read == -1)
408    * @exception IOException If any other error occurs        throw new EOFException("Unexpected end of stream");
409    */    
410  public final boolean      return(byte_read != 0);
411  readBoolean() throws EOFException, IOException    }
412  {    
413    int byte_read = read();    /*************************************************************************/
414      
415    if (byte_read == -1)    /**
416      throw new EOFException("Unexpected end of stream");      * This method reads a Java byte value from an input stream.  The value
417        * is in the range of -128 to 127.
418    return(DataInputStream.convertToBoolean(byte_read));      * <p>
419  }      * This method can read a <code>byte</code> written by an object
420        * implementing the
421  /*************************************************************************/      * <code>writeByte()</code> method in the <code>DataOutput</code> interface.
422        *
423  /**      * @return The <code>byte</code> value read
424    * This method reads a Java byte value from an input stream.  The value      *
425    * is in the range of -128 to 127.      * @exception EOFException If end of file is reached before reading the byte
426    * <p>      * @exception IOException If any other error occurs
427    * This method can read a <code>byte</code> written by an object implementing the      *
428    * <code>writeByte()</code> method in the <code>DataOutput</code> interface.      * @see DataOutput
429    *      */
430    * @return The <code>byte</code> value read    public final byte readByte() throws EOFException, IOException
431    *    {
432    * @exception EOFException If end of file is reached before reading the byte      int byte_read = read();
433    * @exception IOException If any other error occurs    
434    *      if (byte_read == -1)
435    * @see DataOutput        throw new EOFException("Unexpected end of stream");
436    */    
437  public final byte      return (byte)byte_read;
438  readByte() throws EOFException, IOException    }
439  {    
440    int byte_read = read();    /*************************************************************************/
441      
442    if (byte_read == -1)    /**
443      throw new EOFException("Unexpected end of stream");      * This method reads 8 unsigned bits into a Java <code>int</code> value
444        * from the
445    return(DataInputStream.convertToByte(byte_read));      * stream. The value returned is in the range of 0 to 255.
446  }      * <p>
447        * This method can read an unsigned byte written by an object implementing
448  /*************************************************************************/      * the <code>writeUnsignedByte()</code> method in the
449        * <code>DataOutput</code> interface.
450  /**      *
451    * This method reads 8 unsigned bits into a Java <code>int</code> value from the      * @return The unsigned bytes value read as a Java <code>int</code>
452    * stream. The value returned is in the range of 0 to 255.      *
453    * <p>      * @exception EOFException If end of file is reached before reading the value
454    * This method can read an unsigned byte written by an object implementing the      * @exception IOException If any other error occurs
455    * <code>writeUnsignedByte()</code> method in the <code>DataOutput</code> interface.      *
456    *      * @see DataOutput
457    * @return The unsigned bytes value read as a Java <code>int</code>      */
458    *    public final int readUnsignedByte() throws EOFException, IOException
459    * @exception EOFException If end of file is reached before reading the value    {
460    * @exception IOException If any other error occurs      int byte_read = read();
461    *    
462    * @see DataOutput      if (byte_read == -1)
463    */        throw new EOFException("Unexpected end of stream");
464  public final int    
465  readUnsignedByte() throws EOFException, IOException      return(byte_read & 0xFF);
466  {    }
467    int byte_read = read();    
468      /*************************************************************************/
469    if (byte_read == -1)    
470      throw new EOFException("Unexpected end of stream");    /**
471        * This method reads a Java <code>char</code> value from an input stream.  
472    return(DataInputStream.convertToUnsignedByte(byte_read));      * It operates by reading two bytes from the stream and converting them to
473  }      * a single 16-bit Java <code>char</code>  The two bytes are stored most
474        * significant byte first (i.e., "big endian") regardless of the native
475  /*************************************************************************/      * host byte ordering.
476        * <p>
477  /**      * As an example, if <code>byte1</code> and code{byte2</code> represent
478    * This method reads a Java <code>char</code> value from an input stream.        * the first
479    * It operates by reading two bytes from the stream and converting them to      * and second byte read from the stream respectively, they will be
480    * a single 16-bit Java <code>char</code>  The two bytes are stored most      * transformed to a <code>char</code> in the following manner:
481    * significant byte first (i.e., "big endian") regardless of the native      * <p>
482    * host byte ordering.      * <code>(char)(((byte1 & 0xFF) << 8) | (byte2 & 0xFF)</code>
483    * <p>      * <p>
484    * As an example, if <code>byte1</code> and code{byte2</code> represent the first      * This method can read a <code>char</code> written by an object
485    * and second byte read from the stream respectively, they will be      * implementing the
486    * transformed to a <code>char</code> in the following manner:      * <code>writeChar()</code> method in the <code>DataOutput</code> interface.
487    * <p>      *
488    * <code>(char)(((byte1 & 0xFF) << 8) | (byte2 & 0xFF)</code>      * @return The <code>char</code> value read
489    * <p>      *
490    * This method can read a <code>char</code> written by an object implementing the      * @exception EOFException If end of file is reached before reading the char
491    * <code>writeChar()</code> method in the <code>DataOutput</code> interface.      * @exception IOException If any other error occurs
492    *      *
493    * @return The <code>char</code> value read      * @see DataOutput
494    *      */
495    * @exception EOFException If end of file is reached before reading the char    public final synchronized char readChar() throws EOFException, IOException
496    * @exception IOException If any other error occurs    {
497    *      readFully(buf, 0, 2);
498    * @see DataOutput    
499    */      return (char) ((buf[0] << 8) | (buf[1] & 0xff));
500  public final char    }
501  readChar() throws EOFException, IOException    
502  {    /*************************************************************************/
503    byte[] buf = new byte[2];    
504      /**
505    readFully(buf);      * This method reads a signed 16-bit value into a Java in from the stream.
506        * It operates by reading two bytes from the stream and converting them to
507    return(DataInputStream.convertToChar(buf));      * a single 16-bit Java <code>short</code>  The two bytes are stored most
508  }      * significant byte first (i.e., "big endian") regardless of the native
509        * host byte ordering.
510  /*************************************************************************/      * <p>
511        * As an example, if <code>byte1</code> and code{byte2</code>
512  /**      * represent the first
513    * This method reads a signed 16-bit value into a Java in from the stream.      * and second byte read from the stream respectively, they will be
514    * It operates by reading two bytes from the stream and converting them to      * transformed to a <code>short</code> in the following manner:
515    * a single 16-bit Java <code>short</code>  The two bytes are stored most      * <p>
516    * significant byte first (i.e., "big endian") regardless of the native      * <code>(short)(((byte1 & 0xFF) << 8) | (byte2 & 0xFF)</code>
517    * host byte ordering.      * <p>
518    * <p>      * The value returned is in the range of -32768 to 32767.
519    * As an example, if <code>byte1</code> and code{byte2</code> represent the first      * <p>
520    * and second byte read from the stream respectively, they will be      * This method can read a <code>short</code> written by an object
521    * transformed to a <code>short</code> in the following manner:      * implementing the
522    * <p>      * <code>writeShort()</code> method in the <code>DataOutput</code> interface.
523    * <code>(short)(((byte1 & 0xFF) << 8) | (byte2 & 0xFF)</code>      *
524    * <p>      * @return The <code>short</code> value read
525    * The value returned is in the range of -32768 to 32767.      *
526    * <p>      * @exception EOFException If end of file is reached before reading the value
527    * This method can read a <code>short</code> written by an object implementing the      * @exception IOException If any other error occurs
528    * <code>writeShort()</code> method in the <code>DataOutput</code> interface.      *
529    *      * @see DataOutput
530    * @return The <code>short</code> value read      */
531    *    public final synchronized short readShort() throws EOFException, IOException
532    * @exception EOFException If end of file is reached before reading the value    {
533    * @exception IOException If any other error occurs      readFully(buf, 0, 2);
534    *      return (short) ((buf[0] << 8) | (buf[1] & 0xff));
535    * @see DataOutput    }
536    */    
537  public final short    /*************************************************************************/
538  readShort() throws EOFException, IOException    
539  {    /**
540    byte[] buf = new byte[2];      * This method reads 16 unsigned bits into a Java int value from the stream.
541        * It operates by reading two bytes from the stream and converting them to
542    readFully(buf);      * a single Java <code>int</code>  The two bytes are stored most
543        * significant byte first (i.e., "big endian") regardless of the native
544    return(DataInputStream.convertToShort(buf));      * host byte ordering.
545  }      * <p>
546        * As an example, if <code>byte1</code> and <code>byte2</code>
547  /*************************************************************************/      * represent the first
548        * and second byte read from the stream respectively, they will be
549  /**      * transformed to an <code>int</code> in the following manner:
550    * This method reads 16 unsigned bits into a Java int value from the stream.      * <p>
551    * It operates by reading two bytes from the stream and converting them to      * <code>(int)(((byte1 & 0xFF) << 8) + (byte2 & 0xFF))</code>
552    * a single Java <code>int</code>  The two bytes are stored most      * <p>
553    * significant byte first (i.e., "big endian") regardless of the native      * The value returned is in the range of 0 to 65535.
554    * host byte ordering.      * <p>
555    * <p>      * This method can read an unsigned short written by an object implementing
556    * As an example, if <code>byte1</code> and code{byte2</code> represent the first      * the <code>writeUnsignedShort()</code> method in the
557    * and second byte read from the stream respectively, they will be      * <code>DataOutput</code> interface.
558    * transformed to an <code>int</code> in the following manner:      *
559    * <p>      * @return The unsigned short value read as a Java <code>int</code>
560    * <code>(int)(((byte1 & 0xFF) << 8) + (byte2 & 0xFF))</code>      *
561    * <p>      * @exception EOFException If end of file is reached before reading the value
562    * The value returned is in the range of 0 to 65535.      * @exception IOException If any other error occurs
563    * <p>      */
564    * This method can read an unsigned short written by an object implementing    public final synchronized int readUnsignedShort()
565    * the <code>writeUnsignedShort()</code> method in the <code>DataOutput</code> interface.      throws EOFException, IOException
566    *    {
567    * @return The unsigned short value read as a Java <code>int</code>      readFully(buf, 0, 2);
568    *      return (((buf[0] & 0xff) << 8) | (buf[1] & 0xff));
569    * @exception EOFException If end of file is reached before reading the value    }
570    * @exception IOException If any other error occurs    
571    */    /*************************************************************************/
572  public final int    
573  readUnsignedShort() throws EOFException, IOException    /**
574  {      * This method reads a Java <code>int</code> value from an input stream
575    byte[] buf = new byte[2];      * It operates by reading four bytes from the stream and converting them to
576        * a single Java <code>int</code>  The bytes are stored most
577    readFully(buf);      * significant byte first (i.e., "big endian") regardless of the native
578        * host byte ordering.
579    return(DataInputStream.convertToUnsignedShort(buf));      * <p>
580  }      * As an example, if <code>byte1</code> through <code>byte4</code>
581        * represent the first
582  /*************************************************************************/      * four bytes read from the stream, they will be
583        * transformed to an <code>int</code> in the following manner:
584  /**      * <p>
585    * This method reads a Java <code>int</code> value from an input stream      * <code>(int)(((byte1 & 0xFF) << 24) + ((byte2 & 0xFF) << 16) +
586    * It operates by reading four bytes from the stream and converting them to      * ((byte3 & 0xFF) << 8) + (byte4 & 0xFF)))</code>
587    * a single Java <code>int</code>  The bytes are stored most      * <p>
588    * significant byte first (i.e., "big endian") regardless of the native      * The value returned is in the range of 0 to 65535.
589    * host byte ordering.      * <p>
590    * <p>      * This method can read an <code>int</code> written by an object
591    * As an example, if <code>byte1</code> through <code>byte4</code> represent the first      * implementing the
592    * four bytes read from the stream, they will be      * <code>writeInt()</code> method in the <code>DataOutput</code> interface.
593    * transformed to an <code>int</code> in the following manner:      *
594    * <p>      * @return The <code>int</code> value read
595    * <code>(int)(((byte1 & 0xFF) << 24) + ((byte2 & 0xFF) << 16) +      *
596    * ((byte3 & 0xFF) << 8) + (byte4 & 0xFF)))</code>      * @exception EOFException If end of file is reached before reading the int
597    * <p>      * @exception IOException If any other error occurs
598    * The value returned is in the range of 0 to 65535.      *
599    * <p>      * @see DataOutput
600    * This method can read an <code>int</code> written by an object implementing the      */
601    * <code>writeInt()</code> method in the <code>DataOutput</code> interface.    public final synchronized int readInt() throws EOFException, IOException
602    *    {
603    * @return The <code>int</code> value read      readFully(buf, 0, 4);
604    *    
605    * @exception EOFException If end of file is reached before reading the int      return (((buf[0] & 0xff) << 24) | ((buf[1] & 0xff) << 16) |
606    * @exception IOException If any other error occurs              ((buf[2] & 0xff) << 8) | (buf[3] & 0xff));
607    *    }
608    * @see DataOutput    
609    */    /*************************************************************************/
610  public final int    
611  readInt() throws EOFException, IOException    /**
612  {      * This method reads a Java long value from an input stream
613    byte[] buf = new byte[4];      * It operates by reading eight bytes from the stream and converting them to
614        * a single Java <code>long</code>  The bytes are stored most
615    readFully(buf);      * significant byte first (i.e., "big endian") regardless of the native
616        * host byte ordering.
617    return(DataInputStream.convertToInt(buf));      * <p>
618  }      * As an example, if <code>byte1</code> through <code>byte8</code>
619        * represent the first
620  /*************************************************************************/      * eight bytes read from the stream, they will be
621        * transformed to an <code>long</code> in the following manner:
622  /**      * <p>
623    * This method reads a Java long value from an input stream      * <code>
624    * It operates by reading eight bytes from the stream and converting them to      * (long)((((long)byte1 & 0xFF) << 56) + (((long)byte2 & 0xFF) << 48) +
625    * a single Java <code>long</code>  The bytes are stored most      * (((long)byte3 & 0xFF) << 40) + (((long)byte4 & 0xFF) << 32) +
626    * significant byte first (i.e., "big endian") regardless of the native      * (((long)byte5 & 0xFF) << 24) + (((long)byte6 & 0xFF) << 16) +
627    * host byte ordering.      * (((long)byte7 & 0xFF) << 8) + ((long)byte9 & 0xFF)))</code>
628    * <p>      * <p>
629    * As an example, if <code>byte1</code> through <code>byte8</code> represent the first      * The value returned is in the range of 0 to 65535.
630    * eight bytes read from the stream, they will be      * <p>
631    * transformed to an <code>long</code> in the following manner:      * This method can read an <code>long</code> written by an object
632    * <p>      * implementing the
633    * <code>(long)((((long)byte1 & 0xFF) << 56) + (((long)byte2 & 0xFF) << 48) +      * <code>writeLong()</code> method in the <code>DataOutput</code> interface.
634    * (((long)byte3 & 0xFF) << 40) + (((long)byte4 & 0xFF) << 32) +      *
635    * (((long)byte5 & 0xFF) << 24) + (((long)byte6 & 0xFF) << 16) +      * @return The <code>long</code> value read
636    * (((long)byte7 & 0xFF) << 8) + ((long)byte9 & 0xFF)))</code>      *
637    * <p>      * @exception EOFException If end of file is reached before reading the long
638    * The value returned is in the range of 0 to 65535.      * @exception IOException If any other error occurs
639    * <p>      *
640    * This method can read an <code>long</code> written by an object implementing the      * @see DataOutput
641    * <code>writeLong()</code> method in the <code>DataOutput</code> interface.      */
642    *    public final synchronized long readLong() throws EOFException, IOException
643    * @return The <code>long</code> value read    {
644    *      readFully(buf, 0, 8);
645    * @exception EOFException If end of file is reached before reading the long    
646    * @exception IOException If any other error occurs      return (((long)(buf[0] & 0xff) << 56) |
647    *              ((long)(buf[1] & 0xff) << 48) |
648    * @see DataOutput              ((long)(buf[2] & 0xff) << 40) |
649    */              ((long)(buf[3] & 0xff) << 32) |
650  public final long              ((long)(buf[4] & 0xff) << 24) |
651  readLong() throws EOFException, IOException              ((long)(buf[5] & 0xff) << 16) |
652  {              ((long)(buf[6] & 0xff) <<  8) |
653    byte[] buf = new byte[8];              ((long)(buf[7] & 0xff)));
654      }
655    readFully(buf);    
656      /*************************************************************************/
657    return(DataInputStream.convertToLong(buf));    
658  }    /**
659        * This method reads a Java float value from an input stream.  It operates
660  /*************************************************************************/      * by first reading an <code>int</code> value from the stream by calling the
661        * <code>readInt()</code> method in this interface, then converts
662  /**      * that <code>int</code>
663    * This method reads a Java float value from an input stream.  It operates      * to a <code>float</code> using the <code>intBitsToFloat</code> method in
664    * by first reading an <code>int</code> value from the stream by calling the      * the class <code>java.lang.Float</code>
665    * <code>readInt()</code> method in this interface, then converts that <code>int</code>      * <p>
666    * to a <code>float</code> using the <code>intBitsToFloat</code> method in      * This method can read a <code>float</code> written by an object
667    * the class <code>java.lang.Float</code>      * implementing the
668    * <p>      * <code>writeFloat()</code> method in the <code>DataOutput</code> interface.
669    * This method can read a <code>float</code> written by an object implementing the      *
670    * <code>writeFloat()</code> method in the <code>DataOutput</code> interface.      * @return The <code>float</code> value read
671    *      *
672    * @return The <code>float</code> value read      * @exception EOFException If end of file is reached before reading the float
673    *      * @exception IOException If any other error occurs
674    * @exception EOFException If end of file is reached before reading the float      *
675    * @exception IOException If any other error occurs      * @see java.lang.Float
676    *      * @see DataOutput
677    * @see java.lang.Float      */
678    * @see DataOutput    public final float readFloat() throws EOFException, IOException
679    */    {
680  public final float      int val = readInt();
681  readFloat() throws EOFException, IOException    
682  {      return(Float.intBitsToFloat(val));
683    int val = readInt();    }
684      
685    return(Float.intBitsToFloat(val));    /*************************************************************************/
686  }    
687      /**
688  /*************************************************************************/      * This method reads a Java double value from an input stream.  It operates
689        * by first reading a <code>logn</code> value from the stream by calling the
690  /**      * <code>readLong()</code> method in this interface, then
691    * This method reads a Java double value from an input stream.  It operates      * converts that <code>long</code>
692    * by first reading a <code>logn</code> value from the stream by calling the      * to a <code>double</code> using the <code>longBitsToDouble</code>
693    * <code>readLong()</code> method in this interface, then converts that <code>long</code>      * method in the class <code>java.lang.Double</code>
694    * to a <code>double</code> using the <code>longBitsToDouble</code> method in      * <p>
695    * the class <code>java.lang.Double</code>      * This method can read a <code>double</code> written by an object
696    * <p>      * implementing the
697    * This method can read a <code>double</code> written by an object implementing the      * <code>writeDouble()</code> method in the <code>DataOutput</code>
698    * <code>writeDouble()</code> method in the <code>DataOutput</code> interface.      * interface.
699    *      *
700    * @return The <code>double</code> value read      * @return The <code>double</code> value read
701    *      *
702    * @exception EOFException If end of file is reached before reading the double      * @exception EOFException If end of file is reached before reading
703    * @exception IOException If any other error occurs      * the double
704    *      * @exception IOException If any other error occurs
705    * @see java.lang.Double      *
706    * @see DataOutput      * @see java.lang.Double
707    */      * @see DataOutput
708  public final double      */
709  readDouble() throws EOFException, IOException    public final double readDouble() throws EOFException, IOException
710  {    {
711    long val = readLong();      long val = readLong();
712      
713    return(Double.longBitsToDouble(val));      return(Double.longBitsToDouble(val));
714  }    }
715      
716  /*************************************************************************/    /*************************************************************************/
717      
718  /**    /**
719    * This method reads the next line of text data from an input stream.      * This method reads the next line of text data from an input stream.
720    * It operates by reading bytes and converting those bytes to <code>char</code>      * It operates by reading bytes and converting those bytes to
721    * values by treating the byte read as the low eight bits of the <code>char</code>      * <code>char</code>
722    * and using <code>0</code> as the high eight bits.  Because of this, it does      * values by treating the byte read as the low eight bits of the
723    * not support the full 16-bit Unicode character set.      * <code>char</code>
724    * <p>      * and using <code>0</code> as the high eight bits.  Because of this, it does
725    * The reading of bytes ends when either the end of file or a line terminator      * not support the full 16-bit Unicode character set.
726    * is encountered.  The bytes read are then returned as a <code>String</code>      * <p>
727    * A line terminator is a byte sequence consisting of either      * The reading of bytes ends when either the end of file or a line terminator
728    * <code>\r</code> <code>\n</code> or <code>\r\n</code>  These termination charaters are      * is encountered.  The bytes read are then returned as a <code>String</code>
729    * discarded and are not returned as part of the string.      * A line terminator is a byte sequence consisting of either
730    * <p>      * <code>\r</code> <code>\n</code> or <code>\r\n</code>  These
731    * This method can read data that was written by an object implementing the      * termination charaters are
732    * <code>writeLine()</code> method in <code>DataOutput</code>      * discarded and are not returned as part of the string.
733    *      * <p>
734    * @return The line read as a <code>String</code>      * This method can read data that was written by an object implementing the
735    *      * <code>writeLine()</code> method in <code>DataOutput</code>
736    * @exception IOException If an error occurs      *
737    *      * @return The line read as a <code>String</code>
738    * @see DataOutput      *
739    *      * @exception IOException If an error occurs
740    * @deprecated      *
741    */      * @see DataOutput
742  public synchronized final String      *
743  readLine() throws IOException      * @deprecated
744  {      */
745    StringBuffer sb = new StringBuffer("");    public synchronized final String readLine() throws IOException
746      {
747    for (;;)      StringBuffer sb = new StringBuffer("");
748      {    
749        int byte_read = read();      for (;;)
750          {
751        if (byte_read == -1)          int byte_read = read();
752          return(sb.toString());    
753            if (byte_read == -1)
       char c = (char)byte_read;  
   
       if (c == '\r')  
         {  
           byte_read = read();  
           if (((char)byte_read) != '\n')  
             seek(getFilePointer() - 1);  
   
754            return(sb.toString());            return(sb.toString());
         }  
   
       if (c == '\n')  
         return(sb.toString());  
   
       sb.append(c);  
     }  
 }  
   
 /*************************************************************************/  
   
 /**  
   * This method reads a <code>String</code> from an input stream that is encoded in  
   * a modified UTF-8 format.  This format has a leading two byte sequence  
   * that contains the remaining number of bytes to read.  This two byte  
   * sequence is read using the <code>readUnsignedShort()</code> method of this  
   * interface.  
   * <p>  
   * After the number of remaining bytes have been determined, these bytes  
   * are read an transformed into <code>char</code> values.  These <code>char</code> values  
   * are encoded in the stream using either a one, two, or three byte format.  
   * The particular format in use can be determined by examining the first  
   * byte read.    
   * <p>  
   * If the first byte has a high order bit of 0 then  
   * that character consists on only one byte.  This character value consists  
   * of seven bits that are at positions 0 through 6 of the byte.  As an  
   * example, if <code>byte1</code> is the byte read from the stream, it would  
   * be converted to a <code>char</code> like so:  
   * <p>  
   * <code>(char)byte1</code>  
   * <p>  
   * If the first byte has <code>110</code> as its high order bits, then the  
   * character consists of two bytes.  The bits that make up the character  
   * value are in positions 0 through 4 of the first byte and bit positions  
   * 0 through 5 of the second byte.  (The second byte should have  
   * 10 as its high order bits).  These values are in most significant  
   * byte first (i.e., "big endian") order.  
   * <p>  
   * As an example, if <code>byte1</code> and <code>byte2</code> are the first two bytes  
   * read respectively, and the high order bits of them match the patterns  
   * which indicate a two byte character encoding, then they would be  
   * converted to a Java <code>char</code> like so:  
   * <p>  
   * <code>(char)(((byte1 & 0x1F) << 6) | (byte2 & 0x3F))</code>  
   * <p>  
   * If the first byte has a <code>1110</code> as its high order bits, then the  
   * character consists of three bytes.  The bits that make up the character  
   * value are in positions 0 through 3 of the first byte and bit positions  
   * 0 through 5 of the other two bytes.  (The second and third bytes should  
   * have <code>10</code> as their high order bits).  These values are in most  
   * significant byte first (i.e., "big endian") order.  
   * <p>  
   * As an example, if <code>byte1</code> <code>byte2</code> and <code>byte3</code> are the  
   * three bytes read, and the high order bits of them match the patterns  
   * which indicate a three byte character encoding, then they would be  
   * converted to a Java <code>char</code> like so:  
   * <p>  
   * <code>(char)(((byte1 & 0x0F) << 12) | ((byte2 & 0x3F) << 6) | (byte3 & 0x3F))</code>  
   * <p>  
   * Note that all characters are encoded in the method that requires the  
   * fewest number of bytes with the exception of the character with the  
   * value of <code>&#92;u0000</code> which is encoded as two bytes.  This is a  
   * modification of the UTF standard used to prevent C language style  
   * <code>NUL</code> values from appearing in the byte stream.  
   * <p>  
   * This method can read data that was written by an object implementing the  
   * <code>writeUTF()</code> method in <code>DataOutput</code>  
   *  
   * @return The <code>String</code> read  
   *  
   * @exception EOFException If end of file is reached before reading the String  
   * @exception UTFDataFormatException If the data is not in UTF-8 format  
   * @exception IOException If any other error occurs  
   *  
   * @see DataOutput  
   */  
 public synchronized final String  
 readUTF() throws EOFException, UTFDataFormatException, IOException  
 {  
   StringBuffer sb = new StringBuffer("");  
   
   int num_bytes = readUnsignedShort();  
   byte[] buf = new byte[num_bytes];  
   readFully(buf);  
   
   return(DataInputStream.convertFromUTF(buf));  
 }  
   
 /*************************************************************************/  
   
 /**  
   * This method reads raw bytes into the passed array until the array is  
   * full.  Note that this method blocks until the data is available and  
   * throws an exception if there is not enough data left in the stream to  
   * fill the buffer  
   *  
   * @param buf The buffer into which to read the data  
   *  
   * @exception EOFException If end of file is reached before filling the buffer  
   * @exception IOException If any other error occurs  
   */  
 public final void  
 readFully(byte[] buf) throws EOFException, IOException  
 {  
   readFully(buf, 0, buf.length);  
 }  
   
 /*************************************************************************/  
   
 /**  
   * This method reads raw bytes into the passed array <code>buf</code> starting  
   * <code>offset</code> bytes into the buffer.  The number of bytes read will be  
   * exactly <code>len</code>  Note that this method blocks until the data is  
   * available and * throws an exception if there is not enough data left in  
   * the stream to read <code>len</code> bytes.  
   *  
   * @param buf The buffer into which to read the data  
   * @param offset The offset into the buffer to start storing data  
   * @param len The number of bytes to read into the buffer  
   *  
   * @exception EOFException If end of file is reached before filling the buffer  
   * @exception IOException If any other error occurs  
   */  
 public synchronized final void  
 readFully(byte[] buf, int offset, int len) throws EOFException, IOException  
 {  
   int total_read = 0;  
   
   while (total_read < len)  
     {  
       int bytes_read = read(buf, offset + total_read, len - total_read);  
       if (bytes_read == -1)  
         throw new EOFException("Unexpected end of stream");  
   
       total_read += bytes_read;  
     }  
 }  
   
 /*************************************************************************/  
   
 /**  
   * This method attempts to skip and discard the specified number of bytes  
   * in the input stream.  It may actually skip fewer bytes than requested.  
   * The actual number of bytes skipped is returned.  This method will not  
   * skip any bytes if passed a negative number of bytes to skip.  
   *  
   * @param num_bytes The requested number of bytes to skip.  
   *  
   * @return The number of bytes actually skipped.  
   *  
   * @exception IOException If an error occurs.  
   */  
 public int  
 skipBytes(int n) throws EOFException, IOException  
 {  
   if (n <= 0)  
     return(0);  
   
   long file_length = this.length();  
   long file_position = this.getFilePointer();  
   int skip_length = (int) Math.min(n, file_length - file_position);  
   long total_skipped = skipInternal(native_fd, skip_length);  
   
   return((int)total_skipped);  
 }  
   
 /*************************************************************************/  
   
 /*  
  * Native method that does the actual byte skipping.  
  */  
 private native int  
 skipInternal(int native_fd, int n);  
   
 /*************************************************************************/  
   
 /**  
   * This method writes a single byte of data to the file. The file must  
   * be open for read-write in order for this operation to succeed.  
   *  
   * @param The byte of data to write, passed as an int.  
   *  
   * @exception IOException If an error occurs  
   */  
 public void  
 write(int b) throws IOException  
 {  
   if (read_only)  
     throw new IOException("File is open read only");  
   
   byte[] buf = new byte[1];  
   buf[0] = (byte)b;  
755        
756    writeInternal(native_fd, buf, 0, buf.length);          char c = (char)byte_read;
 }  
   
 /*************************************************************************/  
   
 /**  
   * This method writes all the bytes in the specified array to the file.  
   * The file must be open read-write in order for this operation to succeed.  
   *  
   * @param buf The array of bytes to write to the file  
   */  
 public void  
 write(byte[] buf) throws IOException  
 {  
   if (read_only)  
     throw new IOException("File is open read only");  
   
   writeInternal(native_fd, buf, 0, buf.length);  
 }  
757        
758  /*************************************************************************/          if (c == '\r')
759              {
760  /**              byte_read = read();
761    * This method writes <code>len</code> bytes to the file from the specified              if (((char)byte_read) != '\n')
762    * array starting at index <code>offset</code> into the array.                seek(getFilePointer() - 1);
763    *    
764    * @param buf The array of bytes to write to the file              return(sb.toString());
765    * @param offset The index into the array to start writing file            }
766    * @param len The number of bytes to write    
767    *          if (c == '\n')
768    * @exception IOException If an error occurs            return(sb.toString());
769    */    
770  public void          sb.append(c);
771  write(byte[] buf, int offset, int len) throws IOException        }
772  {    }
773    if (read_only)    
774      throw new IOException("File is open read only");    /*************************************************************************/
775      
776    writeInternal(native_fd, buf, offset, len);    /**
777  }      * This method reads a <code>String</code> from an input stream that
778        * is encoded in
779  /*************************************************************************/      * a modified UTF-8 format.  This format has a leading two byte sequence
780        * that contains the remaining number of bytes to read.  This two byte
781  /**      * sequence is read using the <code>readUnsignedShort()</code> method of this
782    * This native method does the actual writing of the bytes      * interface.
783    */      * <p>
784  private native void      * After the number of remaining bytes have been determined, these bytes
785  writeInternal(int native_fd, byte[] buf, int offset, int len);      * are read an transformed into <code>char</code> values.  
786        * These <code>char</code> values
787  /*************************************************************************/      * are encoded in the stream using either a one, two, or three byte format.
788        * The particular format in use can be determined by examining the first
789  /**      * byte read.  
790    * This method writes a Java <code>boolean</code> to the underlying output      * <p>
791    * stream. For a value of <code>true</code>, 1 is written to the stream.      * If the first byte has a high order bit of 0 then
792    * For a value of <code>false</code>, 0 is written.      * that character consists on only one byte.  This character value consists
793    *      * of seven bits that are at positions 0 through 6 of the byte.  As an
794    * @param b The <code>boolean</code> value to write to the stream      * example, if <code>byte1</code> is the byte read from the stream, it would
795    *      * be converted to a <code>char</code> like so:
796    * @exception IOException If an error occurs      * <p>
797    */      * <code>(char)byte1</code>
798  public final void      * <p>
799  writeBoolean(boolean b) throws IOException      * If the first byte has <code>110</code> as its high order bits, then the
800  {      * character consists of two bytes.  The bits that make up the character
801    int bool = DataOutputStream.convertFromBoolean(b);      * value are in positions 0 through 4 of the first byte and bit positions
802    write(bool);      * 0 through 5 of the second byte.  (The second byte should have
803  }      * 10 as its high order bits).  These values are in most significant
804        * byte first (i.e., "big endian") order.
805  /*************************************************************************/      * <p>
806        * As an example, if <code>byte1</code> and <code>byte2</code>
807  /**      * are the first two bytes
808    * This method writes a Java <code>byte</code> value to the underlying      * read respectively, and the high order bits of them match the patterns
809    * output stream.      * which indicate a two byte character encoding, then they would be
810    *      * converted to a Java <code>char</code> like so:
811    * @param b The <code>byte</code> to write to the stream, passed as an <code>int</code>.      * <p>
812    *      * <code>(char)(((byte1 & 0x1F) << 6) | (byte2 & 0x3F))</code>
813    * @exception IOException If an error occurs      * <p>
814    */      * If the first byte has a <code>1110</code> as its high order bits, then the
815  public final void      * character consists of three bytes.  The bits that make up the character
816  writeByte(int b) throws IOException      * value are in positions 0 through 3 of the first byte and bit positions
817  {      * 0 through 5 of the other two bytes.  (The second and third bytes should
818    write(b);      * have <code>10</code> as their high order bits).  These values are in most
819  }      * significant byte first (i.e., "big endian") order.
820        * <p>
821  /*************************************************************************/      * As an example, if <code>byte1</code> <code>byte2</code>
822        * and <code>byte3</code> are the
823  /**      * three bytes read, and the high order bits of them match the patterns
824    * This method writes all the bytes in a <code>String</code> out to the      * which indicate a three byte character encoding, then they would be
825    * stream.  One byte is written for each character in the <code>String</code>.      * converted to a Java <code>char</code> like so:
826    * The high eight bits of each character are discarded.      * <p>
827    *      * <code>(char)(((byte1 & 0x0F) << 12) | ((byte2 & 0x3F) << 6) |
828    * @param s The <code>String</code> to write to the stream      * (byte3 & 0x3F))</code>
829    *      * <p>
830    * @exception IOException If an error occurs      * Note that all characters are encoded in the method that requires the
831    */      * fewest number of bytes with the exception of the character with the
832  public synchronized final void      * value of <code>&#92;u0000</code> which is encoded as two bytes.  This is
833  writeBytes(String s) throws IOException      * a  modification of the UTF standard used to prevent C language style
834  {      * <code>NUL</code> values from appearing in the byte stream.
835    if (s.length() == 0)      * <p>
836      return;      * This method can read data that was written by an object implementing the
837        * <code>writeUTF()</code> method in <code>DataOutput</code>
838    byte[] buf = new byte[s.length()];      *
839        * @return The <code>String</code> read
840    for (int i = 0; i < s.length(); i++)      *
841      buf[i] = (byte)(s.charAt(i) & 0xFF);      * @exception EOFException If end of file is reached before reading the
842        * String
843    write(buf);      * @exception UTFDataFormatException If the data is not in UTF-8 format
844  }      * @exception IOException If any other error occurs
845        *
846  /*************************************************************************/      * @see DataOutput
847        */
848  /**    public synchronized final String readUTF()
849    * This method writes a single <code>char</code> value to the stream,      throws EOFException, UTFDataFormatException, IOException
850    * high byte first.    {
851    *      StringBuffer sb = new StringBuffer("");
852    * @param c The <code>char</code> value to write, passed as an <code>int</code>.    
853    *      int num_bytes = readUnsignedShort();
854    * @exception IOException If an error occurs      byte[] buf = new byte[num_bytes];
855    */      readFully(buf);
856  public final void    
857  writeChar(int c) throws IOException      // FIXME: Look to migrate to new String(buf, "UTF-8") if performance ok
858  {      return(DataInputStream.convertFromUTF(buf));
859    write(DataOutputStream.convertFromChar(c));    }
860  }    
861      /*************************************************************************/
862  /*************************************************************************/    
863      /**
864  /**      * This method reads raw bytes into the passed array until the array is
865    * This method writes all the characters in a <code>String</code> to the      * full.  Note that this method blocks until the data is available and
866    * stream.  There will be two bytes for each character value.  The high      * throws an exception if there is not enough data left in the stream to
867    * byte of the character will be written first.      * fill the buffer
868    *      *
869    * @param s The <code>String</code> to write to the stream.      * @param buf The buffer into which to read the data
870    *      *
871    * @exception IOException If an error occurs      * @exception EOFException If end of file is reached before filling the
872    */      * buffer
873  public final void      * @exception IOException If any other error occurs
874  writeChars(String s) throws IOException      */
875  {    public final void readFully(byte[] buf) throws EOFException, IOException
876    if (s.length() == 0)    {
877      return;      readFully(buf, 0, buf.length);
878      }
879    byte[] buf = DataOutputStream.getConvertedStringChars(s);    
880    write(buf);    /*************************************************************************/
881  }    
882      /**
883  /*************************************************************************/      * This method reads raw bytes into the passed array <code>buf</code>
884        * starting
885  /**      * <code>offset</code> bytes into the buffer.  The number of bytes read
886    * This method writes a Java <code>short</code> to the stream, high byte      * will be
887    * first.  This method requires two bytes to encode the value.      * exactly <code>len</code>  Note that this method blocks until the data is
888    *      * available and throws an exception if there is not enough data left in
889    * @param s The <code>short</code> value to write to the stream, passed as an <code>int</code>.      * the stream to read <code>len</code> bytes.
890    *      *
891    * @exception IOException If an error occurs      * @param buf The buffer into which to read the data
892    */      * @param offset The offset into the buffer to start storing data
893  public final void      * @param len The number of bytes to read into the buffer
894  writeShort(int s) throws IOException      *
895  {      * @exception EOFException If end of file is reached before filling
896    write(DataOutputStream.convertFromShort(s));      * the buffer
897  }      * @exception IOException If any other error occurs
898        */
899  /*************************************************************************/    public synchronized final void readFully(byte[] buf, int offset, int len)
900        throws EOFException, IOException
901  /**    {
902    * This method writes a Java <code>int</code> to the stream, high bytes      int total_read = 0;
903    * first.  This method requires four bytes to encode the value.    
904    *      while (total_read < len)
905    * @param i The <code>int</code> value to write to the stream.        {
906    *          int bytes_read = read(buf, offset + total_read, len - total_read);
907    * @exception IOException If an error occurs          if (bytes_read == -1)
908    */            throw new EOFException("Unexpected end of stream");
909  public final void    
910  writeInt(int i) throws IOException          total_read += bytes_read;
911  {        }
912    write(DataOutputStream.convertFromInt(i));    }
913  }    
914      /*************************************************************************/
915  /*************************************************************************/    
916      /**
917  /**      * This method attempts to skip and discard the specified number of bytes
918    * This method writes a Java <code>long</code> to the stream, high bytes      * in the input stream.  It may actually skip fewer bytes than requested.
919    * first.  This method requires eight bytes to encode the value.      * The actual number of bytes skipped is returned.  This method will not
920    *      * skip any bytes if passed a negative number of bytes to skip.
921    * @param l The <code>long</code> value to write to the stream.      *
922    *      * @param num_bytes The requested number of bytes to skip.
923    * @exception IOException If an error occurs      *
924    */      * @return The number of bytes actually skipped.
925  public final void      *
926  writeLong(long l) throws IOException      * @exception IOException If an error occurs.
927  {      */
928    write(DataOutputStream.convertFromLong(l));    public int skipBytes(int n) throws EOFException, IOException
929  }    {
930        if (n <= 0)
931  /*************************************************************************/        return(0);
932      
933  /**      long file_length = this.length();
934    * This method writes a Java <code>float</code> value to the stream.  This      long file_position = this.getFilePointer();
935    * value is written by first calling the method <code>Float.floatToIntBits</code>      int skip_length = (int) Math.min(n, file_length - file_position);
936    * to retrieve an <code>int</code> representing the floating point number,      long total_skipped = skipInternal(native_fd, skip_length);
937    * then writing this <code>int</code> value to the stream exactly the same    
938    * as the <code>writeInt()</code> method does.      return((int)total_skipped);
939    *    }
940    * @param f The floating point number to write to the stream.    
941    *    /*************************************************************************/
942    * @exception IOException If an error occurs    
943    *    /*
944    * @see writeInt     * Native method that does the actual byte skipping.
945    */     */
946  public final void    private native int skipInternal(int native_fd, int n);
947  writeFloat(float f) throws IOException    
948  {    /*************************************************************************/
949    int i = Float.floatToIntBits(f);    
950    writeInt(i);    /**
951  }      * This method writes a single byte of data to the file. The file must
952        * be open for read-write in order for this operation to succeed.
953  /*************************************************************************/      *
954        * @param The byte of data to write, passed as an int.
955  /**      *
956    * This method writes a Java <code>double</code> value to the stream.  This      * @exception IOException If an error occurs
957    * value is written by first calling the method <code>Double.doubleToLongBits</code>      */
958    * to retrieve an <code>long</code> representing the floating point number,    public synchronized void write(int b) throws IOException
959    * then writing this <code>long</code> value to the stream exactly the same    {
960    * as the <code>writeLong()</code> method does.      if (read_only)
961    *        throw new IOException("File is open read only");
962    * @param d The double precision floating point number to write to the stream.    
963    *      buf[0] = (byte)b;
964    * @exception IOException If an error occurs      
965    *      writeInternal(native_fd, buf, 0, 1);
966    * @see writeLong    }
967    */    
968  public final void    /*************************************************************************/
969  writeDouble(double d) throws IOException    
970  {    /**
971    long l = Double.doubleToLongBits(d);      * This method writes all the bytes in the specified array to the file.
972    writeLong(l);      * The file must be open read-write in order for this operation to succeed.
973  }      *
974        * @param buf The array of bytes to write to the file
975  /*************************************************************************/      */
976      public void write(byte[] buf) throws IOException
977  /**    {
978    * This method writes a Java <code>String</code> to the stream in a modified      if (read_only)
979    * UTF-8 format.  First, two bytes are written to the stream indicating the        throw new IOException("File is open read only");
980    * number of bytes to follow.  Note that this is the number of bytes in the    
981    * encoded <code>String</code> not the <code>String</code> length.  Next      writeInternal(native_fd, buf, 0, buf.length);
982    * come the encoded characters.  Each character in the <code>String</code>    }
983    * is encoded as either one, two or three bytes.  For characters in the      
984    * range of <code>&#92;u0001</code> to <code>&#92;u007F</code>, one byte is used.  The character    /*************************************************************************/
985    * value goes into bits 0-7 and bit eight is 0.  For characters in the range    
986    * of <code>&#92;u0080</code> to <code>&#92;u007FF</code>, two bytes are used.  Bits    /**
987    * 6-10 of the character value are encoded bits 0-4 of the first byte, with      * This method writes <code>len</code> bytes to the file from the specified
988    * the high bytes having a value of "110".  Bits 0-5 of the character value      * array starting at index <code>offset</code> into the array.
989    * are stored in bits 0-5 of the second byte, with the high bits set to      *
990    * "10".  This type of encoding is also done for the null character      * @param buf The array of bytes to write to the file
991    * <code>&#92;u0000</code>.  This eliminates any C style NUL character values      * @param offset The index into the array to start writing file
992    * in the output.  All remaining characters are stored as three bytes.      * @param len The number of bytes to write
993    * Bits 12-15 of the character value are stored in bits 0-3 of the first      *
994    * byte.  The high bits of the first bytes are set to "1110".  Bits 6-11      * @exception IOException If an error occurs
995    * of the character value are stored in bits 0-5 of the second byte.  The      */
996    * high bits of the second byte are set to "10".  And bits 0-5 of the    public void write(byte[] buf, int offset, int len) throws IOException
997    * character value are stored in bits 0-5 of byte three, with the high bits    {
998    * of that byte set to "10".      if (read_only)
999    *        throw new IOException("File is open read only");
1000    * @param s The <code>String</code> to write to the output in UTF format    
1001    *      writeInternal(native_fd, buf, offset, len);
1002    * @exception IOException If an error occurs    }
1003    */    
1004  public synchronized final void    /*************************************************************************/
1005  writeUTF(String s) throws IOException    
1006  {    /**
1007    byte[] buf = DataOutputStream.convertToUTF(s);      * This native method does the actual writing of the bytes
1008        */
1009    writeShort(buf.length);    private native void writeInternal(int native_fd, byte[] buf,
1010    write(buf);                                      int offset, int len);
1011  }    
1012      /*************************************************************************/
1013  /*************************************************************************/    
1014      /**
1015  /**      * This method writes a Java <code>boolean</code> to the underlying output
1016   *  This method creates a java.nio.channels.FileChannel.      * stream. For a value of <code>true</code>, 1 is written to the stream.
1017   * Nio does not allow one to create a file channel directly.      * For a value of <code>false</code>, 0 is written.
1018   * A file channel must be created by first creating an instance of      *
1019   * Input/Output/RandomAccessFile and invoking the getChannel() method on it.      * @param b The <code>boolean</code> value to write to the stream
1020   */      *
1021        * @exception IOException If an error occurs
1022  private FileChannel ch; /* cached associated file-channel */      */
1023      public final void writeBoolean(boolean b) throws IOException
1024  public FileChannel    {
1025  getChannel()      if (b)
1026  {        write(1);
1027      synchronized (this)      else
1028          {        write(0);
1029              if (ch == null)    }
1030                  ch = new gnu.java.nio.FileChannelImpl(native_fd,    
1031                                                        this);    /*************************************************************************/
1032          }    
1033      return ch;    /**
1034  }      * This method writes a Java <code>byte</code> value to the underlying
1035        * output stream.
1036        *
1037        * @param b The <code>byte</code> to write to the stream, passed
1038        * as an <code>int</code>.
1039        *
1040        * @exception IOException If an error occurs
1041        */
1042      public final void writeByte(int b) throws IOException
1043      {
1044        write(b & 0xFF);
1045      }
1046      
1047      /*************************************************************************/
1048      
1049      /**
1050        * This method writes all the bytes in a <code>String</code> out to the
1051        * stream.  One byte is written for each character in the <code>String</code>.
1052        * The high eight bits of each character are discarded.
1053        *
1054        * @param s The <code>String</code> to write to the stream
1055        *
1056        * @exception IOException If an error occurs
1057        */
1058      public final void writeBytes(String s) throws IOException
1059      {
1060        if (s.length() == 0)
1061          return;
1062      
1063        byte[] buf = new byte[s.length()];
1064      
1065        for (int i = 0; i < s.length(); i++)
1066          buf[i] = (byte)(s.charAt(i) & 0xFF);
1067      
1068        write(buf);
1069      }
1070      
1071      /*************************************************************************/
1072      
1073      /**
1074        * This method writes a single <code>char</code> value to the stream,
1075        * high byte first.
1076        *
1077        * @param c The <code>char</code> value to write, passed as
1078        * an <code>int</code>.
1079        *
1080        * @exception IOException If an error occurs
1081        */
1082      public final synchronized void writeChar(int c) throws IOException
1083      {
1084        buf[0] = (byte)((c & 0xFF00) >> 8);
1085        buf[1] = (byte)((int)c & 0x00FF);
1086      
1087        write(buf, 0, 2);
1088      }
1089      
1090      /*************************************************************************/
1091      
1092      /**
1093        * This method writes all the characters in a <code>String</code> to the
1094        * stream.  There will be two bytes for each character value.  The high
1095        * byte of the character will be written first.
1096        *
1097        * @param s The <code>String</code> to write to the stream.
1098        *
1099        * @exception IOException If an error occurs
1100        */
1101      public final void writeChars(String s) throws IOException
1102      {
1103        int len = s.length();
1104        if (len == 0)
1105          return;
1106      
1107        byte[] buf = new byte[len * 2];
1108      
1109        for (int i = 0; i < len; i++)
1110          {
1111            buf[i * 2] = (byte)((s.charAt(i) & 0xFF00) >> 8);
1112            buf[(i * 2) + 1] = (byte)(s.charAt(i) & 0x00FF);
1113          }
1114      
1115        write(buf, 0, buf.length);
1116      }
1117      
1118      /*************************************************************************/
1119      
1120      /**
1121        * This method writes a Java <code>short</code> to the stream, high byte
1122        * first.  This method requires two bytes to encode the value.
1123        *
1124        * @param s The <code>short</code> value to write to the stream,
1125        * passed as an <code>int</code>.
1126        *
1127        * @exception IOException If an error occurs
1128        */
1129      public final synchronized void writeShort(int s) throws IOException
1130      {
1131        buf[0] = (byte)((s & 0xFF00) >> 8);
1132        buf[1] = (byte)(s & 0x00FF);
1133      
1134        write(buf, 0, 2);
1135      }
1136      
1137      /*************************************************************************/
1138      
1139      /**
1140        * This method writes a Java <code>int</code> to the stream, high bytes
1141        * first.  This method requires four bytes to encode the value.
1142        *
1143        * @param i The <code>int</code> value to write to the stream.
1144        *
1145        * @exception IOException If an error occurs
1146        */
1147      public final synchronized void writeInt(int i) throws IOException
1148      {
1149        buf[0] = (byte)((i & 0xFF000000) >> 24);
1150        buf[1] = (byte)((i & 0x00FF0000) >> 16);
1151        buf[2] = (byte)((i & 0x0000FF00) >> 8);
1152        buf[3] = (byte)(i & 0x000000FF);
1153      
1154        write(buf, 0, 4);
1155      }
1156      
1157      /*************************************************************************/
1158      
1159      /**
1160        * This method writes a Java <code>long</code> to the stream, high bytes
1161        * first.  This method requires eight bytes to encode the value.
1162        *
1163        * @param l The <code>long</code> value to write to the stream.
1164        *
1165        * @exception IOException If an error occurs
1166        */
1167      public final synchronized void writeLong(long l) throws IOException
1168      {
1169        buf[0] = (byte)((l & 0xFF00000000000000L) >> 56);
1170        buf[1] = (byte)((l & 0x00FF000000000000L) >> 48);
1171        buf[2] = (byte)((l & 0x0000FF0000000000L) >> 40);
1172        buf[3] = (byte)((l & 0x000000FF00000000L) >> 32);
1173        buf[4] = (byte)((l & 0x00000000FF000000L) >> 24);
1174        buf[5] = (byte)((l & 0x0000000000FF0000L) >> 16);
1175        buf[6] = (byte)((l & 0x000000000000FF00L) >> 8);
1176        buf[7] = (byte)(l & 0x00000000000000FFL);
1177      
1178        write(buf, 0, 8);
1179      }
1180      
1181      /*************************************************************************/
1182      
1183      /**
1184        * This method writes a Java <code>float</code> value to the stream.  This
1185        * value is written by first calling the method
1186        * <code>Float.floatToIntBits</code>
1187        * to retrieve an <code>int</code> representing the floating point number,
1188        * then writing this <code>int</code> value to the stream exactly the same
1189        * as the <code>writeInt()</code> method does.
1190        *
1191        * @param f The floating point number to write to the stream.
1192        *
1193        * @exception IOException If an error occurs
1194        *
1195        * @see writeInt
1196        */
1197      public final void writeFloat(float f) throws IOException
1198      {
1199        int i = Float.floatToIntBits(f);
1200        writeInt(i);
1201      }
1202      
1203      /*************************************************************************/
1204      
1205      /**
1206        * This method writes a Java <code>double</code> value to the stream.  This
1207        * value is written by first calling the method
1208        * <code>Double.doubleToLongBits</code>
1209        * to retrieve an <code>long</code> representing the floating point number,
1210        * then writing this <code>long</code> value to the stream exactly the same
1211        * as the <code>writeLong()</code> method does.
1212        *
1213        * @param d The double precision floating point number to write to the
1214        * stream.
1215        *
1216        * @exception IOException If an error occurs
1217        *
1218        * @see writeLong
1219        */
1220      public final void writeDouble(double d) throws IOException
1221      {
1222        long l = Double.doubleToLongBits(d);
1223        writeLong(l);
1224      }
1225      
1226      /*************************************************************************/
1227      
1228      /**
1229        * This method writes a Java <code>String</code> to the stream in a modified
1230        * UTF-8 format.  First, two bytes are written to the stream indicating the
1231        * number of bytes to follow.  Note that this is the number of bytes in the
1232        * encoded <code>String</code> not the <code>String</code> length.  Next
1233        * come the encoded characters.  Each character in the <code>String</code>
1234        * is encoded as either one, two or three bytes.  For characters in the
1235        * range of <code>&#92;u0001</code> to <code>&#92;u007F</code>,
1236        * one byte is used.  The character
1237        * value goes into bits 0-7 and bit eight is 0.  For characters in the range
1238        * of <code>&#92;u0080</code> to <code>&#92;u007FF</code>, two
1239        * bytes are used.  Bits
1240        * 6-10 of the character value are encoded bits 0-4 of the first byte, with
1241        * the high bytes having a value of "110".  Bits 0-5 of the character value
1242        * are stored in bits 0-5 of the second byte, with the high bits set to
1243        * "10".  This type of encoding is also done for the null character
1244        * <code>&#92;u0000</code>.  This eliminates any C style NUL character values
1245        * in the output.  All remaining characters are stored as three bytes.
1246        * Bits 12-15 of the character value are stored in bits 0-3 of the first
1247        * byte.  The high bits of the first bytes are set to "1110".  Bits 6-11
1248        * of the character value are stored in bits 0-5 of the second byte.  The
1249        * high bits of the second byte are set to "10".  And bits 0-5 of the
1250        * character value are stored in bits 0-5 of byte three, with the high bits
1251        * of that byte set to "10".
1252        *
1253        * @param s The <code>String</code> to write to the output in UTF format
1254        *
1255        * @exception IOException If an error occurs
1256        */
1257      public final void writeUTF(String s) throws IOException
1258      {
1259        // FIXME:  Look to migrate to s.getBytes("UTF-8") if performance ok
1260        byte[] buf = DataOutputStream.convertToUTF(s);
1261      
1262        writeShort(buf.length);
1263        write(buf);
1264      }
1265      
1266      /*************************************************************************/
1267      
1268      /**
1269       * This method creates a java.nio.channels.FileChannel.
1270       * Nio does not allow one to create a file channel directly.
1271       * A file channel must be created by first creating an instance of
1272       * Input/Output/RandomAccessFile and invoking the getChannel() method on it.
1273       */
1274      
1275      private FileChannel ch; /* cached associated file-channel */
1276      
1277      public FileChannel getChannel()
1278      {
1279          synchronized (this)
1280            {
1281                if (ch == null)
1282                    ch = new gnu.java.nio.FileChannelImpl(native_fd,
1283                                                          this);
1284            }
1285          return ch;
1286      }
1287    
1288  } // class RandomAccessFile  } // class RandomAccessFile
1289    

Legend:
Removed from v.1.13  
changed lines
  Added in v.1.14

savannah-hackers-public@gnu.org
ViewVC Help
Powered by ViewVC 1.1.26