KickJava   Java API By Example, From Geeks To Geeks.

Java > Open Source Codes > java > io > FileInputStream


1 /*
2  * @(#)FileInputStream.java 1.63 03/12/19
3  *
4  * Copyright 2004 Sun Microsystems, Inc. All rights reserved.
5  * SUN PROPRIETARY/CONFIDENTIAL. Use is subject to license terms.
6  */

7
8 package java.io;
9
10 import java.nio.channels.FileChannel JavaDoc;
11 import sun.nio.ch.FileChannelImpl;
12
13
14 /**
15  * A <code>FileInputStream</code> obtains input bytes
16  * from a file in a file system. What files
17  * are available depends on the host environment.
18  *
19  * <p><code>FileInputStream</code> is meant for reading streams of raw bytes
20  * such as image data. For reading streams of characters, consider using
21  * <code>FileReader</code>.
22  *
23  * @author Arthur van Hoff
24  * @version 1.63, 12/19/03
25  * @see java.io.File
26  * @see java.io.FileDescriptor
27  * @see java.io.FileOutputStream
28  * @since JDK1.0
29  */

30 public
31 class FileInputStream extends InputStream JavaDoc
32 {
33     /* File Descriptor - handle to the open file */
34     private FileDescriptor JavaDoc fd;
35
36     private FileChannel JavaDoc channel = null;
37
38     /**
39      * Creates a <code>FileInputStream</code> by
40      * opening a connection to an actual file,
41      * the file named by the path name <code>name</code>
42      * in the file system. A new <code>FileDescriptor</code>
43      * object is created to represent this file
44      * connection.
45      * <p>
46      * First, if there is a security
47      * manager, its <code>checkRead</code> method
48      * is called with the <code>name</code> argument
49      * as its argument.
50      * <p>
51      * If the named file does not exist, is a directory rather than a regular
52      * file, or for some other reason cannot be opened for reading then a
53      * <code>FileNotFoundException</code> is thrown.
54      *
55      * @param name the system-dependent file name.
56      * @exception FileNotFoundException if the file does not exist,
57      * is a directory rather than a regular file,
58      * or for some other reason cannot be opened for
59      * reading.
60      * @exception SecurityException if a security manager exists and its
61      * <code>checkRead</code> method denies read access
62      * to the file.
63      * @see java.lang.SecurityManager#checkRead(java.lang.String)
64      */

65     public FileInputStream(String JavaDoc name) throws FileNotFoundException JavaDoc {
66         this(name != null ? new File JavaDoc(name) : null);
67     }
68
69     /**
70      * Creates a <code>FileInputStream</code> by
71      * opening a connection to an actual file,
72      * the file named by the <code>File</code>
73      * object <code>file</code> in the file system.
74      * A new <code>FileDescriptor</code> object
75      * is created to represent this file connection.
76      * <p>
77      * First, if there is a security manager,
78      * its <code>checkRead</code> method is called
79      * with the path represented by the <code>file</code>
80      * argument as its argument.
81      * <p>
82      * If the named file does not exist, is a directory rather than a regular
83      * file, or for some other reason cannot be opened for reading then a
84      * <code>FileNotFoundException</code> is thrown.
85      *
86      * @param file the file to be opened for reading.
87      * @exception FileNotFoundException if the file does not exist,
88      * is a directory rather than a regular file,
89      * or for some other reason cannot be opened for
90      * reading.
91      * @exception SecurityException if a security manager exists and its
92      * <code>checkRead</code> method denies read access to the file.
93      * @see java.io.File#getPath()
94      * @see java.lang.SecurityManager#checkRead(java.lang.String)
95      */

96     public FileInputStream(File JavaDoc file) throws FileNotFoundException JavaDoc {
97     String JavaDoc name = (file != null ? file.getPath() : null);
98     SecurityManager JavaDoc security = System.getSecurityManager();
99     if (security != null) {
100         security.checkRead(name);
101     }
102         if (name == null) {
103             throw new NullPointerException JavaDoc();
104         }
105     fd = new FileDescriptor JavaDoc();
106     open(name);
107     }
108
109     /**
110      * Creates a <code>FileInputStream</code> by using the file descriptor
111      * <code>fdObj</code>, which represents an existing connection to an
112      * actual file in the file system.
113      * <p>
114      * If there is a security manager, its <code>checkRead</code> method is
115      * called with the file descriptor <code>fdObj</code> as its argument to
116      * see if it's ok to read the file descriptor. If read access is denied
117      * to the file descriptor a <code>SecurityException</code> is thrown.
118      * <p>
119      * If <code>fdObj</code> is null then a <code>NullPointerException</code>
120      * is thrown.
121      *
122      * @param fdObj the file descriptor to be opened for reading.
123      * @throws SecurityException if a security manager exists and its
124      * <code>checkRead</code> method denies read access to the
125      * file descriptor.
126      * @see SecurityManager#checkRead(java.io.FileDescriptor)
127      */

128     public FileInputStream(FileDescriptor JavaDoc fdObj) {
129     SecurityManager JavaDoc security = System.getSecurityManager();
130     if (fdObj == null) {
131         throw new NullPointerException JavaDoc();
132     }
133     if (security != null) {
134         security.checkRead(fdObj);
135     }
136     fd = fdObj;
137     }
138
139     /**
140      * Opens the specified file for reading.
141      * @param name the name of the file
142      */

143     private native void open(String JavaDoc name) throws FileNotFoundException JavaDoc;
144
145     /**
146      * Reads a byte of data from this input stream. This method blocks
147      * if no input is yet available.
148      *
149      * @return the next byte of data, or <code>-1</code> if the end of the
150      * file is reached.
151      * @exception IOException if an I/O error occurs.
152      */

153     public native int read() throws IOException JavaDoc;
154
155
156     /**
157      * Reads a subarray as a sequence of bytes.
158      * @param b the data to be written
159      * @param off the start offset in the data
160      * @param len the number of bytes that are written
161      * @exception IOException If an I/O error has occurred.
162      */

163     private native int readBytes(byte b[], int off, int len) throws IOException JavaDoc;
164
165     /**
166      * Reads up to <code>b.length</code> bytes of data from this input
167      * stream into an array of bytes. This method blocks until some input
168      * is available.
169      *
170      * @param b the buffer into which the data is read.
171      * @return the total number of bytes read into the buffer, or
172      * <code>-1</code> if there is no more data because the end of
173      * the file has been reached.
174      * @exception IOException if an I/O error occurs.
175      */

176     public int read(byte b[]) throws IOException JavaDoc {
177     return readBytes(b, 0, b.length);
178     }
179
180     /**
181      * Reads up to <code>len</code> bytes of data from this input stream
182      * into an array of bytes. This method blocks until some input is
183      * available.
184      *
185      * @param b the buffer into which the data is read.
186      * @param off the start offset of the data.
187      * @param len the maximum number of bytes read.
188      * @return the total number of bytes read into the buffer, or
189      * <code>-1</code> if there is no more data because the end of
190      * the file has been reached.
191      * @exception IOException if an I/O error occurs.
192      */

193     public int read(byte b[], int off, int len) throws IOException JavaDoc {
194     return readBytes(b, off, len);
195     }
196
197     /**
198      * Skips over and discards <code>n</code> bytes of data from the
199      * input stream.
200      *
201      * <p>The <code>skip</code> method may, for a variety of
202      * reasons, end up skipping over some smaller number of bytes,
203      * possibly <code>0</code>. If <code>n</code> is negative, an
204      * <code>IOException</code> is thrown, even though the <code>skip</code>
205      * method of the {@link InputStream} superclass does nothing in this case.
206      * The actual number of bytes skipped is returned.
207      *
208      * <p>This method may skip more bytes than are remaining in the backing
209      * file. This produces no exception and the number of bytes skipped
210      * may include some number of bytes that were beyond the EOF of the
211      * backing file. Attempting to read from the stream after skipping past
212      * the end will result in -1 indicating the end of the file.
213      *
214      * @param n the number of bytes to be skipped.
215      * @return the actual number of bytes skipped.
216      * @exception IOException if n is negative, or if an I/O error occurs.
217      */

218     public native long skip(long n) throws IOException JavaDoc;
219
220     /**
221      * Returns the number of bytes that can be read from this file input
222      * stream without blocking.
223      *
224      * @return the number of bytes that can be read from this file input
225      * stream without blocking.
226      * @exception IOException if an I/O error occurs.
227      */

228     public native int available() throws IOException JavaDoc;
229
230     /**
231      * Closes this file input stream and releases any system resources
232      * associated with the stream.
233      *
234      * <p> If this stream has an associated channel then the channel is closed
235      * as well.
236      *
237      * @exception IOException if an I/O error occurs.
238      *
239      * @revised 1.4
240      * @spec JSR-51
241      */

242     public void close() throws IOException JavaDoc {
243         if (channel != null)
244             channel.close();
245         close0();
246     }
247
248     /**
249      * Returns the <code>FileDescriptor</code>
250      * object that represents the connection to
251      * the actual file in the file system being
252      * used by this <code>FileInputStream</code>.
253      *
254      * @return the file descriptor object associated with this stream.
255      * @exception IOException if an I/O error occurs.
256      * @see java.io.FileDescriptor
257      */

258     public final FileDescriptor JavaDoc getFD() throws IOException JavaDoc {
259     if (fd != null) return fd;
260     throw new IOException JavaDoc();
261     }
262
263     /**
264      * Returns the unique {@link java.nio.channels.FileChannel FileChannel}
265      * object associated with this file input stream.
266      *
267      * <p> The initial {@link java.nio.channels.FileChannel#position()
268      * </code>position<code>} of the returned channel will be equal to the
269      * number of bytes read from the file so far. Reading bytes from this
270      * stream will increment the channel's position. Changing the channel's
271      * position, either explicitly or by reading, will change this stream's
272      * file position.
273      *
274      * @return the file channel associated with this file input stream
275      *
276      * @since 1.4
277      * @spec JSR-51
278      */

279     public FileChannel JavaDoc getChannel() {
280     synchronized (this) {
281         if (channel == null)
282         channel = FileChannelImpl.open(fd, true, false, this);
283         return channel;
284     }
285     }
286
287     private static native void initIDs();
288
289     private native void close0() throws IOException JavaDoc;
290
291     static {
292     initIDs();
293     }
294
295     /**
296      * Ensures that the <code>close</code> method of this file input stream is
297      * called when there are no more references to it.
298      *
299      * @exception IOException if an I/O error occurs.
300      * @see java.io.FileInputStream#close()
301      */

302     protected void finalize() throws IOException JavaDoc {
303     if (fd != null) {
304         if (fd != fd.in) {
305         close();
306         }
307     }
308     }
309 }
310
Popular Tags