31 import sun.nio.ch.FileChannelImpl; |
31 import sun.nio.ch.FileChannelImpl; |
32 |
32 |
33 |
33 |
34 /** |
34 /** |
35 * A file output stream is an output stream for writing data to a |
35 * A file output stream is an output stream for writing data to a |
36 * <code>File</code> or to a <code>FileDescriptor</code>. Whether or not |
36 * {@code File} or to a {@code FileDescriptor}. Whether or not |
37 * a file is available or may be created depends upon the underlying |
37 * a file is available or may be created depends upon the underlying |
38 * platform. Some platforms, in particular, allow a file to be opened |
38 * platform. Some platforms, in particular, allow a file to be opened |
39 * for writing by only one {@code FileOutputStream} (or other |
39 * for writing by only one {@code FileOutputStream} (or other |
40 * file-writing object) at a time. In such situations the constructors in |
40 * file-writing object) at a time. In such situations the constructors in |
41 * this class will fail if the file involved is already open. |
41 * this class will fail if the file involved is already open. |
42 * |
42 * |
43 * <p><code>FileOutputStream</code> is meant for writing streams of raw bytes |
43 * <p>{@code FileOutputStream} is meant for writing streams of raw bytes |
44 * such as image data. For writing streams of characters, consider using |
44 * such as image data. For writing streams of characters, consider using |
45 * <code>FileWriter</code>. |
45 * {@code FileWriter}. |
46 * |
46 * |
47 * @apiNote |
47 * @apiNote |
48 * To release resources used by this stream {@link #close} should be called |
48 * To release resources used by this stream {@link #close} should be called |
49 * directly or by try-with-resources. Subclasses are responsible for the cleanup |
49 * directly or by try-with-resources. Subclasses are responsible for the cleanup |
50 * of resources acquired by the subclass. |
50 * of resources acquired by the subclass. |
95 |
95 |
96 private volatile boolean closed; |
96 private volatile boolean closed; |
97 |
97 |
98 /** |
98 /** |
99 * Creates a file output stream to write to the file with the |
99 * Creates a file output stream to write to the file with the |
100 * specified name. A new <code>FileDescriptor</code> object is |
100 * specified name. A new {@code FileDescriptor} object is |
101 * created to represent this file connection. |
101 * created to represent this file connection. |
102 * <p> |
102 * <p> |
103 * First, if there is a security manager, its <code>checkWrite</code> |
103 * First, if there is a security manager, its {@code checkWrite} |
104 * method is called with <code>name</code> as its argument. |
104 * method is called with {@code name} as its argument. |
105 * <p> |
105 * <p> |
106 * If the file exists but is a directory rather than a regular file, does |
106 * If the file exists but is a directory rather than a regular file, does |
107 * not exist but cannot be created, or cannot be opened for any other |
107 * not exist but cannot be created, or cannot be opened for any other |
108 * reason then a <code>FileNotFoundException</code> is thrown. |
108 * reason then a {@code FileNotFoundException} is thrown. |
109 * |
109 * |
110 * @implSpec Invoking this constructor with the parameter {@code name} is |
110 * @implSpec Invoking this constructor with the parameter {@code name} is |
111 * equivalent to invoking {@link #FileOutputStream(String,boolean) |
111 * equivalent to invoking {@link #FileOutputStream(String,boolean) |
112 * new FileOutputStream(name, false)}. |
112 * new FileOutputStream(name, false)}. |
113 * |
113 * |
114 * @param name the system-dependent filename |
114 * @param name the system-dependent filename |
115 * @throws FileNotFoundException if the file exists but is a directory |
115 * @throws FileNotFoundException if the file exists but is a directory |
116 * rather than a regular file, does not exist but cannot |
116 * rather than a regular file, does not exist but cannot |
117 * be created, or cannot be opened for any other reason |
117 * be created, or cannot be opened for any other reason |
118 * @throws SecurityException if a security manager exists and its |
118 * @throws SecurityException if a security manager exists and its |
119 * <code>checkWrite</code> method denies write access |
119 * {@code checkWrite} method denies write access |
120 * to the file. |
120 * to the file. |
121 * @see java.lang.SecurityManager#checkWrite(java.lang.String) |
121 * @see java.lang.SecurityManager#checkWrite(java.lang.String) |
122 */ |
122 */ |
123 public FileOutputStream(String name) throws FileNotFoundException { |
123 public FileOutputStream(String name) throws FileNotFoundException { |
124 this(name != null ? new File(name) : null, false); |
124 this(name != null ? new File(name) : null, false); |
125 } |
125 } |
126 |
126 |
127 /** |
127 /** |
128 * Creates a file output stream to write to the file with the specified |
128 * Creates a file output stream to write to the file with the specified |
129 * name. If the second argument is <code>true</code>, then |
129 * name. If the second argument is {@code true}, then |
130 * bytes will be written to the end of the file rather than the beginning. |
130 * bytes will be written to the end of the file rather than the beginning. |
131 * A new <code>FileDescriptor</code> object is created to represent this |
131 * A new {@code FileDescriptor} object is created to represent this |
132 * file connection. |
132 * file connection. |
133 * <p> |
133 * <p> |
134 * First, if there is a security manager, its <code>checkWrite</code> |
134 * First, if there is a security manager, its {@code checkWrite} |
135 * method is called with <code>name</code> as its argument. |
135 * method is called with {@code name} as its argument. |
136 * <p> |
136 * <p> |
137 * If the file exists but is a directory rather than a regular file, does |
137 * If the file exists but is a directory rather than a regular file, does |
138 * not exist but cannot be created, or cannot be opened for any other |
138 * not exist but cannot be created, or cannot be opened for any other |
139 * reason then a <code>FileNotFoundException</code> is thrown. |
139 * reason then a {@code FileNotFoundException} is thrown. |
140 * |
140 * |
141 * @param name the system-dependent file name |
141 * @param name the system-dependent file name |
142 * @param append if <code>true</code>, then bytes will be written |
142 * @param append if {@code true}, then bytes will be written |
143 * to the end of the file rather than the beginning |
143 * to the end of the file rather than the beginning |
144 * @throws FileNotFoundException if the file exists but is a directory |
144 * @throws FileNotFoundException if the file exists but is a directory |
145 * rather than a regular file, does not exist but cannot |
145 * rather than a regular file, does not exist but cannot |
146 * be created, or cannot be opened for any other reason. |
146 * be created, or cannot be opened for any other reason. |
147 * @throws SecurityException if a security manager exists and its |
147 * @throws SecurityException if a security manager exists and its |
148 * <code>checkWrite</code> method denies write access |
148 * {@code checkWrite} method denies write access |
149 * to the file. |
149 * to the file. |
150 * @see java.lang.SecurityManager#checkWrite(java.lang.String) |
150 * @see java.lang.SecurityManager#checkWrite(java.lang.String) |
151 * @since 1.1 |
151 * @since 1.1 |
152 */ |
152 */ |
153 public FileOutputStream(String name, boolean append) |
153 public FileOutputStream(String name, boolean append) |
156 this(name != null ? new File(name) : null, append); |
156 this(name != null ? new File(name) : null, append); |
157 } |
157 } |
158 |
158 |
159 /** |
159 /** |
160 * Creates a file output stream to write to the file represented by |
160 * Creates a file output stream to write to the file represented by |
161 * the specified <code>File</code> object. A new |
161 * the specified {@code File} object. A new |
162 * <code>FileDescriptor</code> object is created to represent this |
162 * {@code FileDescriptor} object is created to represent this |
163 * file connection. |
163 * file connection. |
164 * <p> |
164 * <p> |
165 * First, if there is a security manager, its <code>checkWrite</code> |
165 * First, if there is a security manager, its {@code checkWrite} |
166 * method is called with the path represented by the <code>file</code> |
166 * method is called with the path represented by the {@code file} |
167 * argument as its argument. |
167 * argument as its argument. |
168 * <p> |
168 * <p> |
169 * If the file exists but is a directory rather than a regular file, does |
169 * If the file exists but is a directory rather than a regular file, does |
170 * not exist but cannot be created, or cannot be opened for any other |
170 * not exist but cannot be created, or cannot be opened for any other |
171 * reason then a <code>FileNotFoundException</code> is thrown. |
171 * reason then a {@code FileNotFoundException} is thrown. |
172 * |
172 * |
173 * @param file the file to be opened for writing. |
173 * @param file the file to be opened for writing. |
174 * @throws FileNotFoundException if the file exists but is a directory |
174 * @throws FileNotFoundException if the file exists but is a directory |
175 * rather than a regular file, does not exist but cannot |
175 * rather than a regular file, does not exist but cannot |
176 * be created, or cannot be opened for any other reason |
176 * be created, or cannot be opened for any other reason |
177 * @throws SecurityException if a security manager exists and its |
177 * @throws SecurityException if a security manager exists and its |
178 * <code>checkWrite</code> method denies write access |
178 * {@code checkWrite} method denies write access |
179 * to the file. |
179 * to the file. |
180 * @see java.io.File#getPath() |
180 * @see java.io.File#getPath() |
181 * @see java.lang.SecurityException |
181 * @see java.lang.SecurityException |
182 * @see java.lang.SecurityManager#checkWrite(java.lang.String) |
182 * @see java.lang.SecurityManager#checkWrite(java.lang.String) |
183 */ |
183 */ |
185 this(file, false); |
185 this(file, false); |
186 } |
186 } |
187 |
187 |
188 /** |
188 /** |
189 * Creates a file output stream to write to the file represented by |
189 * Creates a file output stream to write to the file represented by |
190 * the specified <code>File</code> object. If the second argument is |
190 * the specified {@code File} object. If the second argument is |
191 * <code>true</code>, then bytes will be written to the end of the file |
191 * {@code true}, then bytes will be written to the end of the file |
192 * rather than the beginning. A new <code>FileDescriptor</code> object is |
192 * rather than the beginning. A new {@code FileDescriptor} object is |
193 * created to represent this file connection. |
193 * created to represent this file connection. |
194 * <p> |
194 * <p> |
195 * First, if there is a security manager, its <code>checkWrite</code> |
195 * First, if there is a security manager, its {@code checkWrite} |
196 * method is called with the path represented by the <code>file</code> |
196 * method is called with the path represented by the {@code file} |
197 * argument as its argument. |
197 * argument as its argument. |
198 * <p> |
198 * <p> |
199 * If the file exists but is a directory rather than a regular file, does |
199 * If the file exists but is a directory rather than a regular file, does |
200 * not exist but cannot be created, or cannot be opened for any other |
200 * not exist but cannot be created, or cannot be opened for any other |
201 * reason then a <code>FileNotFoundException</code> is thrown. |
201 * reason then a {@code FileNotFoundException} is thrown. |
202 * |
202 * |
203 * @param file the file to be opened for writing. |
203 * @param file the file to be opened for writing. |
204 * @param append if <code>true</code>, then bytes will be written |
204 * @param append if {@code true}, then bytes will be written |
205 * to the end of the file rather than the beginning |
205 * to the end of the file rather than the beginning |
206 * @throws FileNotFoundException if the file exists but is a directory |
206 * @throws FileNotFoundException if the file exists but is a directory |
207 * rather than a regular file, does not exist but cannot |
207 * rather than a regular file, does not exist but cannot |
208 * be created, or cannot be opened for any other reason |
208 * be created, or cannot be opened for any other reason |
209 * @throws SecurityException if a security manager exists and its |
209 * @throws SecurityException if a security manager exists and its |
210 * <code>checkWrite</code> method denies write access |
210 * {@code checkWrite} method denies write access |
211 * to the file. |
211 * to the file. |
212 * @see java.io.File#getPath() |
212 * @see java.io.File#getPath() |
213 * @see java.lang.SecurityException |
213 * @see java.lang.SecurityException |
214 * @see java.lang.SecurityManager#checkWrite(java.lang.String) |
214 * @see java.lang.SecurityManager#checkWrite(java.lang.String) |
215 * @since 1.4 |
215 * @since 1.4 |
239 /** |
239 /** |
240 * Creates a file output stream to write to the specified file |
240 * Creates a file output stream to write to the specified file |
241 * descriptor, which represents an existing connection to an actual |
241 * descriptor, which represents an existing connection to an actual |
242 * file in the file system. |
242 * file in the file system. |
243 * <p> |
243 * <p> |
244 * First, if there is a security manager, its <code>checkWrite</code> |
244 * First, if there is a security manager, its {@code checkWrite} |
245 * method is called with the file descriptor <code>fdObj</code> |
245 * method is called with the file descriptor {@code fdObj} |
246 * argument as its argument. |
246 * argument as its argument. |
247 * <p> |
247 * <p> |
248 * If <code>fdObj</code> is null then a <code>NullPointerException</code> |
248 * If {@code fdObj} is null then a {@code NullPointerException} |
249 * is thrown. |
249 * is thrown. |
250 * <p> |
250 * <p> |
251 * This constructor does not throw an exception if <code>fdObj</code> |
251 * This constructor does not throw an exception if {@code fdObj} |
252 * is {@link java.io.FileDescriptor#valid() invalid}. |
252 * is {@link java.io.FileDescriptor#valid() invalid}. |
253 * However, if the methods are invoked on the resulting stream to attempt |
253 * However, if the methods are invoked on the resulting stream to attempt |
254 * I/O on the stream, an <code>IOException</code> is thrown. |
254 * I/O on the stream, an {@code IOException} is thrown. |
255 * |
255 * |
256 * @param fdObj the file descriptor to be opened for writing |
256 * @param fdObj the file descriptor to be opened for writing |
257 * @throws SecurityException if a security manager exists and its |
257 * @throws SecurityException if a security manager exists and its |
258 * <code>checkWrite</code> method denies |
258 * {@code checkWrite} method denies |
259 * write access to the file descriptor |
259 * write access to the file descriptor |
260 * @see java.lang.SecurityManager#checkWrite(java.io.FileDescriptor) |
260 * @see java.lang.SecurityManager#checkWrite(java.io.FileDescriptor) |
261 */ |
261 */ |
262 public FileOutputStream(FileDescriptor fdObj) { |
262 public FileOutputStream(FileDescriptor fdObj) { |
263 SecurityManager security = System.getSecurityManager(); |
263 SecurityManager security = System.getSecurityManager(); |
323 */ |
323 */ |
324 private native void writeBytes(byte b[], int off, int len, boolean append) |
324 private native void writeBytes(byte b[], int off, int len, boolean append) |
325 throws IOException; |
325 throws IOException; |
326 |
326 |
327 /** |
327 /** |
328 * Writes <code>b.length</code> bytes from the specified byte array |
328 * Writes {@code b.length} bytes from the specified byte array |
329 * to this file output stream. |
329 * to this file output stream. |
330 * |
330 * |
331 * @param b the data. |
331 * @param b the data. |
332 * @throws IOException if an I/O error occurs. |
332 * @throws IOException if an I/O error occurs. |
333 */ |
333 */ |
334 public void write(byte b[]) throws IOException { |
334 public void write(byte b[]) throws IOException { |
335 writeBytes(b, 0, b.length, fdAccess.getAppend(fd)); |
335 writeBytes(b, 0, b.length, fdAccess.getAppend(fd)); |
336 } |
336 } |
337 |
337 |
338 /** |
338 /** |
339 * Writes <code>len</code> bytes from the specified byte array |
339 * Writes {@code len} bytes from the specified byte array |
340 * starting at offset <code>off</code> to this file output stream. |
340 * starting at offset {@code off} to this file output stream. |
341 * |
341 * |
342 * @param b the data. |
342 * @param b the data. |
343 * @param off the start offset in the data. |
343 * @param off the start offset in the data. |
344 * @param len the number of bytes to write. |
344 * @param len the number of bytes to write. |
345 * @throws IOException if an I/O error occurs. |
345 * @throws IOException if an I/O error occurs. |