KickJava   Java API By Example, From Geeks To Geeks.

Java > Open Source Codes > java > io > FileOutputStream


1 /*
2  * @(#)FileOutputStream.java 1.57 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 file output stream is an output stream for writing data to a
16  * <code>File</code> or to a <code>FileDescriptor</code>. Whether or not
17  * a file is available or may be created depends upon the underlying
18  * platform. Some platforms, in particular, allow a file to be opened
19  * for writing by only one <tt>FileOutputStream</tt> (or other
20  * file-writing object) at a time. In such situations the constructors in
21  * this class will fail if the file involved is already open.
22  *
23  * <p><code>FileOutputStream</code> is meant for writing streams of raw bytes
24  * such as image data. For writing streams of characters, consider using
25  * <code>FileWriter</code>.
26  *
27  * @author Arthur van Hoff
28  * @version 1.57, 12/19/03
29  * @see java.io.File
30  * @see java.io.FileDescriptor
31  * @see java.io.FileInputStream
32  * @since JDK1.0
33  */

34 public
35 class FileOutputStream extends OutputStream JavaDoc
36 {
37     /**
38      * The system dependent file descriptor. The value is
39      * 1 more than actual file descriptor. This means that
40      * the default value 0 indicates that the file is not open.
41      */

42     private FileDescriptor JavaDoc fd;
43
44     private FileChannel JavaDoc channel= null;
45
46     private boolean append = false;
47
48     /**
49      * Creates an output file stream to write to the file with the
50      * specified name. A new <code>FileDescriptor</code> object is
51      * created to represent this file connection.
52      * <p>
53      * First, if there is a security manager, its <code>checkWrite</code>
54      * method is called with <code>name</code> as its argument.
55      * <p>
56      * If the file exists but is a directory rather than a regular file, does
57      * not exist but cannot be created, or cannot be opened for any other
58      * reason then a <code>FileNotFoundException</code> is thrown.
59      *
60      * @param name the system-dependent filename
61      * @exception FileNotFoundException if the file exists but is a directory
62      * rather than a regular file, does not exist but cannot
63      * be created, or cannot be opened for any other reason
64      * @exception SecurityException if a security manager exists and its
65      * <code>checkWrite</code> method denies write access
66      * to the file.
67      * @see java.lang.SecurityManager#checkWrite(java.lang.String)
68      */

69     public FileOutputStream(String JavaDoc name) throws FileNotFoundException JavaDoc {
70     this(name != null ? new File JavaDoc(name) : null, false);
71     }
72
73     /**
74      * Creates an output file stream to write to the file with the specified
75      * <code>name</code>. If the second argument is <code>true</code>, then
76      * bytes will be written to the end of the file rather than the beginning.
77      * A new <code>FileDescriptor</code> object is created to represent this
78      * file connection.
79      * <p>
80      * First, if there is a security manager, its <code>checkWrite</code>
81      * method is called with <code>name</code> as its argument.
82      * <p>
83      * If the file exists but is a directory rather than a regular file, does
84      * not exist but cannot be created, or cannot be opened for any other
85      * reason then a <code>FileNotFoundException</code> is thrown.
86      *
87      * @param name the system-dependent file name
88      * @param append if <code>true</code>, then bytes will be written
89      * to the end of the file rather than the beginning
90      * @exception FileNotFoundException if the file exists but is a directory
91      * rather than a regular file, does not exist but cannot
92      * be created, or cannot be opened for any other reason.
93      * @exception SecurityException if a security manager exists and its
94      * <code>checkWrite</code> method denies write access
95      * to the file.
96      * @see java.lang.SecurityManager#checkWrite(java.lang.String)
97      * @since JDK1.1
98      */

99     public FileOutputStream(String JavaDoc name, boolean append)
100         throws FileNotFoundException JavaDoc
101     {
102         this(name != null ? new File JavaDoc(name) : null, append);
103     }
104
105     /**
106      * Creates a file output stream to write to the file represented by
107      * the specified <code>File</code> object. A new
108      * <code>FileDescriptor</code> object is created to represent this
109      * file connection.
110      * <p>
111      * First, if there is a security manager, its <code>checkWrite</code>
112      * method is called with the path represented by the <code>file</code>
113      * argument as its argument.
114      * <p>
115      * If the file exists but is a directory rather than a regular file, does
116      * not exist but cannot be created, or cannot be opened for any other
117      * reason then a <code>FileNotFoundException</code> is thrown.
118      *
119      * @param file the file to be opened for writing.
120      * @exception FileNotFoundException if the file exists but is a directory
121      * rather than a regular file, does not exist but cannot
122      * be created, or cannot be opened for any other reason
123      * @exception SecurityException if a security manager exists and its
124      * <code>checkWrite</code> method denies write access
125      * to the file.
126      * @see java.io.File#getPath()
127      * @see java.lang.SecurityException
128      * @see java.lang.SecurityManager#checkWrite(java.lang.String)
129      */

130     public FileOutputStream(File JavaDoc file) throws FileNotFoundException JavaDoc {
131     this(file, false);
132     }
133
134     /**
135      * Creates a file output stream to write to the file represented by
136      * the specified <code>File</code> object. If the second argument is
137      * <code>true</code>, then bytes will be written to the end of the file
138      * rather than the beginning. A new <code>FileDescriptor</code> object is
139      * created to represent this file connection.
140      * <p>
141      * First, if there is a security manager, its <code>checkWrite</code>
142      * method is called with the path represented by the <code>file</code>
143      * argument as its argument.
144      * <p>
145      * If the file exists but is a directory rather than a regular file, does
146      * not exist but cannot be created, or cannot be opened for any other
147      * reason then a <code>FileNotFoundException</code> is thrown.
148      *
149      * @param file the file to be opened for writing.
150      * @param append if <code>true</code>, then bytes will be written
151      * to the end of the file rather than the beginning
152      * @exception FileNotFoundException if the file exists but is a directory
153      * rather than a regular file, does not exist but cannot
154      * be created, or cannot be opened for any other reason
155      * @exception SecurityException if a security manager exists and its
156      * <code>checkWrite</code> method denies write access
157      * to the file.
158      * @see java.io.File#getPath()
159      * @see java.lang.SecurityException
160      * @see java.lang.SecurityManager#checkWrite(java.lang.String)
161      * @since 1.4
162      */

163     public FileOutputStream(File JavaDoc file, boolean append)
164         throws FileNotFoundException JavaDoc
165     {
166         String JavaDoc name = (file != null ? file.getPath() : null);
167     SecurityManager JavaDoc security = System.getSecurityManager();
168     if (security != null) {
169         security.checkWrite(name);
170     }
171         if (name == null) {
172             throw new NullPointerException JavaDoc();
173         }
174     fd = new FileDescriptor JavaDoc();
175         this.append = append;
176     if (append) {
177         openAppend(name);
178     } else {
179         open(name);
180     }
181     }
182
183     /**
184      * Creates an output file stream to write to the specified file
185      * descriptor, which represents an existing connection to an actual
186      * file in the file system.
187      * <p>
188      * First, if there is a security manager, its <code>checkWrite</code>
189      * method is called with the file descriptor <code>fdObj</code>
190      * argument as its argument.
191      *
192      * @param fdObj the file descriptor to be opened for writing
193      * @exception SecurityException if a security manager exists and its
194      * <code>checkWrite</code> method denies
195      * write access to the file descriptor
196      * @see java.lang.SecurityManager#checkWrite(java.io.FileDescriptor)
197      */

198     public FileOutputStream(FileDescriptor JavaDoc fdObj) {
199     SecurityManager JavaDoc security = System.getSecurityManager();
200     if (fdObj == null) {
201         throw new NullPointerException JavaDoc();
202     }
203     if (security != null) {
204         security.checkWrite(fdObj);
205     }
206     fd = fdObj;
207     }
208
209     /**
210      * Opens a file, with the specified name, for writing.
211      * @param name name of file to be opened
212      */

213     private native void open(String JavaDoc name) throws FileNotFoundException JavaDoc;
214
215     /**
216      * Opens a file, with the specified name, for appending.
217      * @param name name of file to be opened
218      */

219     private native void openAppend(String JavaDoc name) throws FileNotFoundException JavaDoc;
220
221     /**
222      * Writes the specified byte to this file output stream. Implements
223      * the <code>write</code> method of <code>OutputStream</code>.
224      *
225      * @param b the byte to be written.
226      * @exception IOException if an I/O error occurs.
227      */

228     public native void write(int b) throws IOException JavaDoc;
229
230     /**
231      * Writes a sub array as a sequence of bytes.
232      * @param b the data to be written
233      * @param off the start offset in the data
234      * @param len the number of bytes that are written
235      * @exception IOException If an I/O error has occurred.
236      */

237     private native void writeBytes(byte b[], int off, int len) throws IOException JavaDoc;
238
239     /**
240      * Writes <code>b.length</code> bytes from the specified byte array
241      * to this file output stream.
242      *
243      * @param b the data.
244      * @exception IOException if an I/O error occurs.
245      */

246     public void write(byte b[]) throws IOException JavaDoc {
247     writeBytes(b, 0, b.length);
248     }
249
250     /**
251      * Writes <code>len</code> bytes from the specified byte array
252      * starting at offset <code>off</code> to this file output stream.
253      *
254      * @param b the data.
255      * @param off the start offset in the data.
256      * @param len the number of bytes to write.
257      * @exception IOException if an I/O error occurs.
258      */

259     public void write(byte b[], int off, int len) throws IOException JavaDoc {
260     writeBytes(b, off, len);
261     }
262
263     /**
264      * Closes this file output stream and releases any system resources
265      * associated with this stream. This file output stream may no longer
266      * be used for writing bytes.
267      *
268      * <p> If this stream has an associated channel then the channel is closed
269      * as well.
270      *
271      * @exception IOException if an I/O error occurs.
272      *
273      * @revised 1.4
274      * @spec JSR-51
275      */

276     public void close() throws IOException JavaDoc {
277         if (channel != null)
278             channel.close();
279         close0();
280     }
281
282     /**
283      * Returns the file descriptor associated with this stream.
284      *
285      * @return the <code>FileDescriptor</code> object that represents
286      * the connection to the file in the file system being used
287      * by this <code>FileOutputStream</code> object.
288      *
289      * @exception IOException if an I/O error occurs.
290      * @see java.io.FileDescriptor
291      */

292      public final FileDescriptor JavaDoc getFD() throws IOException JavaDoc {
293     if (fd != null) return fd;
294     throw new IOException JavaDoc();
295      }
296     
297     /**
298      * Returns the unique {@link java.nio.channels.FileChannel FileChannel}
299      * object associated with this file output stream. </p>
300      *
301      * <p> The initial {@link java.nio.channels.FileChannel#position()
302      * </code>position<code>} of the returned channel will be equal to the
303      * number of bytes written to the file so far unless this stream is in
304      * append mode, in which case it will be equal to the size of the file.
305      * Writing bytes to this stream will increment the channel's position
306      * accordingly. Changing the channel's position, either explicitly or by
307      * writing, will change this stream's file position.
308      *
309      * @return the file channel associated with this file output stream
310      *
311      * @since 1.4
312      * @spec JSR-51
313      */

314     public FileChannel JavaDoc getChannel() {
315     synchronized (this) {
316         if (channel == null)
317         channel = FileChannelImpl.open(fd, false, true, this, append);
318         return channel;
319     }
320     }
321
322     /**
323      * Cleans up the connection to the file, and ensures that the
324      * <code>close</code> method of this file output stream is
325      * called when there are no more references to this stream.
326      *
327      * @exception IOException if an I/O error occurs.
328      * @see java.io.FileInputStream#close()
329      */

330     protected void finalize() throws IOException JavaDoc {
331     if (fd != null) {
332         if (fd == fd.out || fd == fd.err) {
333         flush();
334         } else {
335         close();
336         }
337     }
338     }
339
340     private native void close0() throws IOException JavaDoc;
341
342     private static native void initIDs();
343     
344     static {
345     initIDs();
346     }
347
348 }
349
Popular Tags