KickJava   Java API By Example, From Geeks To Geeks.

Java > Open Source Codes > javax > jnlp > JNLPRandomAccessFile


1 /*
2  * @(#)JNLPRandomAccessFile.java 1.11 04/03/12
3  *
4  * Copyright 2004 Sun Microsystems, Inc. All rights reserved.
5  * SUN PROPRIETARY/CONFIDENTIAL. Use is subject to license terms.
6  */
7
8 package javax.jnlp;
9 import java.io.File;
10 import java.io.DataInput;
11 import java.io.DataOutput;
12 import java.io.IOException;
13
14 /**
15  * Instances of this class support both reading and writing to a
16  * random access file. A random access file behaves like a large
17  * array of bytes stored in the file system. There is a kind of cursor,
18  * or index into the implied array, called the <em>file pointer</em>;
19  * input operations read bytes starting at the file pointer and advance
20  * the file pointer past the bytes read. If the random access file is
21  * created in read/write mode, then output operations are also available;
22  * output operations write bytes starting at the file pointer and advance
23  * the file pointer past the bytes written. Output operations that write
24  * past the current end of the implied array cause the array to be
25  * extended. The file pointer can be read by the
26  * <code>getFilePointer</code> method and set by the <code>seek</code>
27  * method.
28  * <p>
29  * It is generally true of all the reading routines in this class that
30  * if end-of-file is reached before the desired number of bytes has been
31  * read, an <code>EOFException</code> (which is a kind of
32  * <code>IOException</code>) is thrown. If any byte cannot be read for
33  * any reason other than end-of-file, an <code>IOException</code> other
34  * than <code>EOFException</code> is thrown. In particular, an
35  * <code>IOException</code> may be thrown if the stream has been closed.
36  * <p>
37  * Implementations are encouraged to enforce a maximum amount of data
38  * that may be written to a file.
39  *
40  * @since 1.0
41  */
42
43 public interface JNLPRandomAccessFile extends DataInput, DataOutput {
44     
45     /**
46      * Closes this random access file stream and releases any system
47      * resources associated with the stream. A closed random access
48      * file cannot perform input or output operations and cannot be
49      * reopened.
50      *
51      * @exception IOException if an I/O error occurs.
52      */
53     public void close() throws IOException;
54     
55     /**
56      * Returns the length of this file.
57      *
58      * @return the length of this file, measured in bytes.
59      * @exception IOException if an I/O error occurs.
60      */
61     public long length() throws IOException;
62     
63     /**
64      * Returns the current offset in this file.
65      *
66      * @return the offset from the beginning of the file, in bytes,
67      * at which the next read or write occurs.
68      * @exception IOException if an I/O error occurs.
69      */
70     public long getFilePointer() throws IOException;
71     
72     /**
73      * Reads a byte of data from this file. The byte is returned as an
74      * integer in the range 0 to 255 (<code>0x00-0x0ff</code>). This
75      * method blocks if no input is yet available.
76      * <p>
77      * Although <code>JNLPRandomAccessFile</code> is not a subclass of
78      * <code>InputStream</code>, this method behaves in exactly the same
79      * way as the read method of
80      * <code>InputStream</code>.
81      *
82      * @return the next byte of data, or <code>-1</code> if the end of the
83      * file has been reached.
84      * @exception IOException if an I/O error occurs. Not thrown if
85      * end-of-file has been reached.
86      */
87     public int read() throws IOException;
88     
89     /**
90      * Reads up to <code>len</code> bytes of data from this file into an
91      * array of bytes. This method blocks until at least one byte of input
92      * is available.
93      * <p>
94      * Although <code>JNLPRandomAccessFile</code> is not a subclass of
95      * <code>InputStream</code>, this method behaves in the exactly the
96      * same way as the read(byte[], int, int) method of
97      * <code>InputStream</code>.
98      *
99      * @param b the buffer into which the data is read.
100      * @param off the start offset of the data.
101      * @param len the maximum number of bytes read.
102      * @return the total number of bytes read into the buffer, or
103      * <code>-1</code> if there is no more data because the end of
104      * the file has been reached.
105      * @exception IOException if an I/O error occurs.
106      */
107     public int read(byte [] b, int off, int len) throws IOException;
108     
109     /**
110      * Reads up to <code>b.length</code> bytes of data from this file
111      * into an array of bytes. This method blocks until at least one byte
112      * of input is available.
113      * <p>
114      * Although <code>JNLPRandomAccessFile</code> is not a subclass of
115      * <code>InputStream</code>, this method behaves in the exactly the
116      * same way as the read(byte[]) method of
117      * <code>InputStream</code>.
118      *
119      * @param b the buffer into which the data is read.
120      * @return the total number of bytes read into the buffer, or
121      * <code>-1</code> if there is no more data because the end of
122      * this file has been reached.
123      * @exception IOException if an I/O error occurs.
124      */
125     public int read(byte [] b) throws IOException;
126     
127     /**
128      * Reads <code>b.length</code> bytes from this file into the byte
129      * array, starting at the current file pointer. This method reads
130      * repeatedly from the file until the requested number of bytes are
131      * read. This method blocks until the requested number of bytes are
132      * read, the end of the stream is detected, or an exception is thrown.
133      *
134      * @param b the buffer into which the data is read.
135      * @exception EOFException if this file reaches the end before reading
136      * all the bytes.
137      * @exception IOException if an I/O error occurs.
138      */
139     public void readFully(byte [] b) throws IOException;
140     
141     /**
142      * Reads exactly <code>len</code> bytes from this file into the byte
143      * array, starting at the current file pointer. This method reads
144      * repeatedly from the file until the requested number of bytes are
145      * read. This method blocks until the requested number of bytes are
146      * read, the end of the stream is detected, or an exception is thrown.
147      *
148      * @param b the buffer into which the data is read.
149      * @param off the start offset of the data.
150      * @param len the number of bytes to read.
151      * @exception EOFException if this file reaches the end before reading
152      * all the bytes.
153      * @exception IOException if an I/O error occurs.
154      */
155     public void readFully(byte b[], int off, int len) throws IOException;
156     
157     /**
158      * Attempts to skip over <code>n</code> bytes of input discarding the
159      * skipped bytes.
160      * <p>
161      *
162      * This method may skip over some smaller number of bytes, possibly zero.
163      * This may result from any of a number of conditions; reaching end of
164      * file before <code>n</code> bytes have been skipped is only one
165      * possibility. This method never throws an <code>EOFException</code>.
166      * The actual number of bytes skipped is returned. If <code>n</code>
167      * is negative, no bytes are skipped.
168      *
169      * @param n the number of bytes to be skipped.
170      * @return the actual number of bytes skipped.
171      * @exception IOException if an I/O error occurs.
172      */
173     public int skipBytes(int n) throws IOException;
174     
175     /**
176      * Reads a <code>boolean</code> from this file. This method reads a
177      * single byte from the file, starting at the current file pointer.
178      * A value of <code>0</code> represents
179      * <code>false</code>. Any other value represents <code>true</code>.
180      * This method blocks until the byte is read, the end of the stream
181      * is detected, or an exception is thrown.
182      *
183      * @return the <code>boolean</code> value read.
184      * @exception EOFException if this file has reached the end.
185      * @exception IOException if an I/O error occurs.
186      */
187     public boolean readBoolean() throws IOException;
188     
189     /**
190      * Reads a signed eight-bit value from this file. This method reads a
191      * byte from the file, starting from the current file pointer.
192      * If the byte read is <code>b</code>, where
193      * <code>0&nbsp;&lt;=&nbsp;b&nbsp;&lt;=&nbsp;255</code>,
194      * then the result is:
195      * <blockquote><pre>
196      * (byte)(b)
197      * </pre></blockquote>
198      * <p>
199      * This method blocks until the byte is read, the end of the stream
200      * is detected, or an exception is thrown.
201      *
202      * @return the next byte of this file as a signed eight-bit
203      * <code>byte</code>.
204      * @exception EOFException if this file has reached the end.
205      * @exception IOException if an I/O error occurs.
206      */
207     public byte readByte() throws IOException;
208     
209     /**
210      * Reads an unsigned eight-bit number from this file. This method reads
211      * a byte from this file, starting at the current file pointer,
212      * and returns that byte.
213      * <p>
214      * This method blocks until the byte is read, the end of the stream
215      * is detected, or an exception is thrown.
216      *
217      * @return the next byte of this file, interpreted as an unsigned
218      * eight-bit number.
219      * @exception EOFException if this file has reached the end.
220      * @exception IOException if an I/O error occurs.
221      */
222     public int readUnsignedByte() throws IOException;
223     
224     /**
225      * Reads a signed 16-bit number from this file. The method reads two
226      * bytes from this file, starting at the current file pointer.
227      * If the two bytes read, in order, are
228      * <code>b1</code> and <code>b2</code>, where each of the two values is
229      * between <code>0</code> and <code>255</code>, inclusive, then the
230      * result is equal to:
231      * <blockquote><pre>
232      * (short)((b1 &lt;&lt; 8) | b2)
233      * </pre></blockquote>
234      * <p>
235      * This method blocks until the two bytes are read, the end of the
236      * stream is detected, or an exception is thrown.
237      *
238      * @return the next two bytes of this file, interpreted as a signed
239      * 16-bit number.
240      * @exception EOFException if this file reaches the end before reading
241      * two bytes.
242      * @exception IOException if an I/O error occurs.
243      */
244     public short readShort() throws IOException;
245     
246     /**
247      * Reads an unsigned 16-bit number from this file. This method reads
248      * two bytes from the file, starting at the current file pointer.
249      * If the bytes read, in order, are
250      * <code>b1</code> and <code>b2</code>, where
251      * <code>0&nbsp;&lt;=&nbsp;b1, b2&nbsp;&lt;=&nbsp;255</code>,
252      * then the result is equal to:
253      * <blockquote><pre>
254      * (b1 &lt;&lt; 8) | b2
255      * </pre></blockquote>
256      * <p>
257      * This method blocks until the two bytes are read, the end of the
258      * stream is detected, or an exception is thrown.
259      *
260      * @return the next two bytes of this file, interpreted as an unsigned
261      * 16-bit integer.
262      * @exception EOFException if this file reaches the end before reading
263      * two bytes.
264      * @exception IOException if an I/O error occurs.
265      */
266     public int readUnsignedShort() throws IOException;
267     
268     /**
269      * Reads a Unicode character from this file. This method reads two
270      * bytes from the file, starting at the current file pointer.
271      * If the bytes read, in order, are
272      * <code>b1</code> and <code>b2</code>, where
273      * <code>0&nbsp;&lt;=&nbsp;b1,&nbsp;b2&nbsp;&lt;=&nbsp;255</code>,
274      * then the result is equal to:
275      * <blockquote><pre>
276      * (char)((b1 &lt;&lt; 8) | b2)
277      * </pre></blockquote>
278      * <p>
279      * This method blocks until the two bytes are read, the end of the
280      * stream is detected, or an exception is thrown.
281      *
282      * @return the next two bytes of this file as a Unicode character.
283      * @exception EOFException if this file reaches the end before reading
284      * two bytes.
285      * @exception IOException if an I/O error occurs.
286      */
287     public char readChar() throws IOException;
288     
289     /**
290      * Reads a signed 32-bit integer from this file. This method reads 4
291      * bytes from the file, starting at the current file pointer.
292      * If the bytes read, in order, are <code>b1</code>,
293      * <code>b2</code>, <code>b3</code>, and <code>b4</code>, where
294      * <code>0&nbsp;&lt;=&nbsp;b1, b2, b3, b4&nbsp;&lt;=&nbsp;255</code>,
295      * then the result is equal to:
296      * <blockquote><pre>
297      * (b1 &lt;&lt; 24) | (b2 &lt;&lt; 16) + (b3 &lt;&lt; 8) + b4
298      * </pre></blockquote>
299      * <p>
300      * This method blocks until the four bytes are read, the end of the
301      * stream is detected, or an exception is thrown.
302      *
303      * @return the next four bytes of this file, interpreted as an
304      * <code>int</code>.
305      * @exception EOFException if this file reaches the end before reading
306      * four bytes.
307      * @exception IOException if an I/O error occurs.
308      */
309     public int readInt() throws IOException;
310     
311     /**
312      * Reads a signed 64-bit integer from this file. This method reads eight
313      * bytes from the file, starting at the current file pointer.
314      * If the bytes read, in order, are
315      * <code>b1</code>, <code>b2</code>, <code>b3</code>,
316      * <code>b4</code>, <code>b5</code>, <code>b6</code>,
317      * <code>b7</code>, and <code>b8,</code> where:
318      * <blockquote><pre>
319      * 0 &lt;= b1, b2, b3, b4, b5, b6, b7, b8 &lt;=255,
320      * </pre></blockquote>
321      * <p>
322      * then the result is equal to:
323      * <p><blockquote><pre>
324      * ((long)b1 &lt;&lt; 56) + ((long)b2 &lt;&lt; 48)
325      * + ((long)b3 &lt;&lt; 40) + ((long)b4 &lt;&lt; 32)
326      * + ((long)b5 &lt;&lt; 24) + ((long)b6 &lt;&lt; 16)
327      * + ((long)b7 &lt;&lt; 8) + b8
328      * </pre></blockquote>
329      * <p>
330      * This method blocks until the eight bytes are read, the end of the
331      * stream is detected, or an exception is thrown.
332      *
333      * @return the next eight bytes of this file, interpreted as a
334      * <code>long</code>.
335      * @exception EOFException if this file reaches the end before reading
336      * eight bytes.
337      * @exception IOException if an I/O error occurs.
338      */
339     public long readLong() throws IOException;
340     
341     /**
342      * Reads a <code>float</code> from this file. This method reads an
343      * <code>int</code> value, starting at the current file pointer,
344      * as if by the <code>readInt</code> method
345      * and then converts that <code>int</code> to a <code>float</code>
346      * using the <code>intBitsToFloat</code> method in class
347      * <code>Float</code>.
348      * <p>
349      * This method blocks until the four bytes are read, the end of the
350      * stream is detected, or an exception is thrown.
351      *
352      * @return the next four bytes of this file, interpreted as a
353      * <code>float</code>.
354      * @exception EOFException if this file reaches the end before reading
355      * four bytes.
356      * @exception IOException if an I/O error occurs.
357      * @see javax.jnlp.JNLPRandomAccessFile#readInt()
358      */
359     public float readFloat() throws IOException;
360     
361     /**
362      * Reads a <code>double</code> from this file. This method reads a
363      * <code>long</code> value, starting at the current file pointer,
364      * as if by the <code>readLong</code> method
365      * and then converts that <code>long</code> to a <code>double</code>
366      * using the <code>longBitsToDouble</code> method in
367      * class <code>Double</code>.
368      * <p>
369      * This method blocks until the eight bytes are read, the end of the
370      * stream is detected, or an exception is thrown.
371      *
372      * @return the next eight bytes of this file, interpreted as a
373      * <code>double</code>.
374      * @exception EOFException if this file reaches the end before reading
375      * eight bytes.
376      * @exception IOException if an I/O error occurs.
377      * @see javax.jnlp.JNLPRandomAccessFile#readLong()
378      */
379     public double readDouble() throws IOException;
380     
381     /**
382      * Reads the next line of text from this file. This method successively
383      * reads bytes from the file, starting at the current file pointer,
384      * until it reaches a line terminator or the end
385      * of the file. Each byte is converted into a character by taking the
386      * byte's value for the lower eight bits of the character and setting the
387      * high eight bits of the character to zero. This method does not,
388      * therefore, support the full Unicode character set.
389      *
390      * <p> A line of text is terminated by a carriage-return character
391      * (<code>'&#92;r'</code>), a newline character (<code>'&#92;n'</code>), a
392      * carriage-return character immediately followed by a newline character,
393      * or the end of the file. Line-terminating characters are discarded and
394      * are not included as part of the string returned.
395      *
396      * <p> This method blocks until a newline character is read, a carriage
397      * return and the byte following it are read (to see if it is a newline),
398      * the end of the file is reached, or an exception is thrown.
399      *
400      * @return the next line of text from this file, or null if end
401      * of file is encountered before even one byte is read.
402      * @exception IOException if an I/O error occurs.
403      */
404     public String readLine() throws IOException;
405     
406     /**
407      * Reads in a string from this file. The string has been encoded
408      * using a modified UTF-8 format.
409      * <p>
410      * The first two bytes are read, starting from the current file
411      * pointer, as if by
412      * <code>readUnsignedShort</code>. This value gives the number of
413      * following bytes that are in the encoded string, not
414      * the length of the resulting string. The following bytes are then
415      * interpreted as bytes encoding characters in the UTF-8 format
416      * and are converted into characters.
417      * <p>
418      * This method blocks until all the bytes are read, the end of the
419      * stream is detected, or an exception is thrown.
420      *
421      * @return a Unicode string.
422      * @exception EOFException if this file reaches the end before
423      * reading all the bytes.
424      * @exception IOException if an I/O error occurs.
425      * @exception UTFDataFormatException if the bytes do not represent
426      * valid UTF-8 encoding of a Unicode string.
427      * @see javax.jnlp.JNLPRandomAccessFile#readUnsignedShort()
428      */
429     public String readUTF() throws IOException;
430     
431     /**
432      * Sets the file-pointer offset, measured from the beginning of this
433      * file, at which the next read or write occurs. The offset may be
434      * set beyond the end of the file. Setting the offset beyond the end
435      * of the file does not change the file length. The file length will
436      * change only by writing after the offset has been set beyond the end
437      * of the file.
438      *
439      * @param pos the offset position, measured in bytes from the
440      * beginning of the file, at which to set the file
441      * pointer.
442      * @exception IOException if <code>pos</code> is less than
443      * <code>0</code> or if an I/O error occurs.
444      */
445     public void seek(long pos) throws IOException;
446     
447     /**
448      * Sets the length of this file.
449      *
450      * <p> If the present length of the file as returned by the
451      * <code>length</code> method is greater than the <code>newLength</code>
452      * argument then the file will be truncated. In this case, if the file
453      * offset as returned by the <code>getFilePointer</code> method is greater
454      * then <code>newLength</code> then after this method returns the offset
455      * will be equal to <code>newLength</code>.
456      *
457      * <p> If the present length of the file as returned by the
458      * <code>length</code> method is smaller than the <code>newLength</code>
459      * argument then the file will be extended. In this case, the contents of
460      * the extended portion of the file are not defined.
461      *
462      * @param newLength The desired length of the file
463      * @exception IOException If an I/O error occurs
464      */
465     public void setLength(long newLength) throws IOException;
466     
467     /**
468      * Writes the specified byte to this file. The write starts at
469      * the current file pointer.
470      *
471      * @param b the <code>byte</code> to be written.
472      * @exception IOException if an I/O error occurs.
473      */
474     public void write(int b) throws IOException;
475     
476     /**
477      * Writes <code>b.length</code> bytes from the specified byte array
478      * to this file, starting at the current file pointer.
479      *
480      * @param b the data.
481      * @exception IOException if an I/O error occurs.
482      */
483     public void write(byte b[]) throws IOException;
484     
485     /**
486      * Writes <code>len</code> bytes from the specified byte array
487      * starting at offset <code>off</code> to this file.
488      *
489      * @param b the data.
490      * @param off the start offset in the data.
491      * @param len the number of bytes to write.
492      * @exception IOException if an I/O error occurs.
493      */
494     public void write(byte b[], int off, int len) throws IOException;
495     
496     /**
497      * Writes a <code>boolean</code> to the file as a one-byte value. The
498      * value <code>true</code> is written out as the value
499      * <code>(byte)1</code>; the value <code>false</code> is written out
500      * as the value <code>(byte)0</code>. The write starts at
501      * the current position of the file pointer.
502      *
503      * @param v a <code>boolean</code> value to be written.
504      * @exception IOException if an I/O error occurs.
505      */
506     public void writeBoolean(boolean v) throws IOException;
507     
508     /**
509      * Writes a <code>byte</code> to the file as a one-byte value. The
510      * write starts at the current position of the file pointer.
511      *
512      * @param v a <code>byte</code> value to be written.
513      * @exception IOException if an I/O error occurs.
514      */
515     public void writeByte(int v) throws IOException;
516     
517     /**
518      * Writes a <code>short</code> to the file as two bytes, high byte first.
519      * The write starts at the current position of the file pointer.
520      *
521      * @param v a <code>short</code> to be written.
522      * @exception IOException if an I/O error occurs.
523      */
524     public void writeShort(int v) throws IOException;
525     
526     /**
527      * Writes a <code>char</code> to the file as a two-byte value, high
528      * byte first. The write starts at the current position of the
529      * file pointer.
530      *
531      * @param v a <code>char</code> value to be written.
532      * @exception IOException if an I/O error occurs.
533      */
534     public void writeChar(int v) throws IOException;
535     
536     /**
537      * Writes an <code>int</code> to the file as four bytes, high byte first.
538      * The write starts at the current position of the file pointer.
539      *
540      * @param v an <code>int</code> to be written.
541      * @exception IOException if an I/O error occurs.
542      */
543     public void writeInt(int v) throws IOException;
544     
545     /**
546      * Writes a <code>long</code> to the file as eight bytes, high byte first.
547      * The write starts at the current position of the file pointer.
548      *
549      * @param v a <code>long</code> to be written.
550      * @exception IOException if an I/O error occurs.
551      */
552     public void writeLong(long v) throws IOException;
553     
554     /**
555      * Converts the float argument to an <code>int</code> using the
556      * <code>floatToIntBits</code> method in class <code>Float</code>,
557      * and then writes that <code>int</code> value to the file as a
558      * four-byte quantity, high byte first. The write starts at the
559      * current position of the file pointer.
560      *
561      * @param v a <code>float</code> value to be written.
562      * @exception IOException if an I/O error occurs.
563      */
564     public void writeFloat(float v) throws IOException;
565     
566     /**
567      * Converts the double argument to a <code>long</code> using the
568      * <code>doubleToLongBits</code> method in class <code>Double</code>,
569      * and then writes that <code>long</code> value to the file as an
570      * eight-byte quantity, high byte first. The write starts at the current
571      * position of the file pointer.
572      *
573      * @param v a <code>double</code> value to be written.
574      * @exception IOException if an I/O error occurs.
575      */
576     public void writeDouble(double v) throws IOException;
577     
578     /**
579      * Writes the string to the file as a sequence of bytes. Each
580      * character in the string is written out, in sequence, by discarding
581      * its high eight bits. The write starts at the current position of
582      * the file pointer.
583      *
584      * @param s a string of bytes to be written.
585      * @exception IOException if an I/O error occurs.
586      */
587     public void writeBytes(String s) throws IOException;
588     
589     /**
590      * Writes a string to the file as a sequence of characters. Each
591      * character is written to the data output stream as if by the
592      * <code>writeChar</code> method. The write starts at the current
593      * position of the file pointer.
594      *
595      * @param s a <code>String</code> value to be written.
596      * @exception IOException if an I/O error occurs.
597      * @see javax.jnlp.JNLPRandomAccessFile#writeChar(int)
598      */
599     public void writeChars(String s) throws IOException;
600     
601     /**
602      * Writes a string to the file using UTF-8 encoding in a
603      * machine-independent manner.
604      * <p>
605      * First, two bytes are written to the file, starting at the
606      * current file pointer, as if by the
607      * <code>writeShort</code> method giving the number of bytes to
608      * follow. This value is the number of bytes actually written out,
609      * not the length of the string. Following the length, each character
610      * of the string is output, in sequence, using the UTF-8 encoding
611      * for each character.
612      *
613      * @param str a string to be written.
614      * @exception IOException if an I/O error occurs.
615      */
616     public void writeUTF(String str) throws IOException;
617     
618 }
619
620
621
Popular Tags