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  ;
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  
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   fd;
43  
44      private FileChannel   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   name) throws FileNotFoundException   {
70      this(name != null ? new File  (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   name, boolean append)
100         throws FileNotFoundException  
101     {
102         this(name != null ? new File  (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   file) throws FileNotFoundException   {
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   file, boolean append)
164         throws FileNotFoundException  
165     {
166         String   name = (file != null ? file.getPath() : null);
167     SecurityManager   security = System.getSecurityManager();
168     if (security != null) {
169         security.checkWrite(name);
170     }
171         if (name == null) {
172             throw new NullPointerException  ();
173         }
174     fd = new FileDescriptor  ();
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   fdObj) {
199     SecurityManager   security = System.getSecurityManager();
200     if (fdObj == null) {
201         throw new NullPointerException  ();
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   name) throws FileNotFoundException  ;
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   name) throws FileNotFoundException  ;
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  ;
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  ;
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   {
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   {
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   {
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   getFD()  throws IOException   {
293     if (fd != null) return fd;
294     throw new IOException  ();
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   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   {
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  ;
341 
342     private static native void initIDs();
343     
344     static {
345     initIDs();
346     }
347 
348 }
349
A to Z: JavaDoc & Examples Daily Java News & Articles Open Source Projects Open Source Codes Free Computer Books Remove Frame
Popular Tags