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 & 0xFF) << 8) | (byte2 & 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 & 0xFF) << 24) + ((byte2 & 0xFF) << 16) +
471 * ((byte3 & 0xFF) << 8) + (byte4 & 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 & 0xFF) << 56) + (((long)byte2 & 0xFF) << 48) +
535 * (((long)byte3 & 0xFF) << 40) + (((long)byte4 & 0xFF) << 32) +
536 * (((long)byte5 & 0xFF) << 24) + (((long)byte6 & 0xFF) << 16) +
537 * (((long)byte7 & 0xFF) << 8) + ((long)byte9 & 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 & 0xFF) << 8) | (byte2 & 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 & 0xFF) << 8) + (byte2 & 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>\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>\u0001</code> to <code>\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>\u0080</code> to <code>\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>\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 }