157 implements SeekableByteChannel, GatheringByteChannel, ScatteringByteChannel
158 {
159 /**
160 * Initializes a new instance of this class.
161 */
162 protected FileChannel() { }
163
164 /**
165 * Opens or creates a file, returning a file channel to access the file.
166 *
167 * <p> The {@code options} parameter determines how the file is opened.
168 * The {@link StandardOpenOption#READ READ} and {@link StandardOpenOption#WRITE
169 * WRITE} options determine if the file should be opened for reading and/or
170 * writing. If neither option (or the {@link StandardOpenOption#APPEND APPEND}
171 * option) is contained in the array then the file is opened for reading.
172 * By default reading or writing commences at the beginning of the file.
173 *
174 * <p> In the addition to {@code READ} and {@code WRITE}, the following
175 * options may be present:
176 *
177 * <table border=1 cellpadding=5 summary="">
178 * <tr> <th>Option</th> <th>Description</th> </tr>
179 * <tr>
180 * <td> {@link StandardOpenOption#APPEND APPEND} </td>
181 * <td> If this option is present then the file is opened for writing and
182 * each invocation of the channel's {@code write} method first advances
183 * the position to the end of the file and then writes the requested
184 * data. Whether the advancement of the position and the writing of the
185 * data are done in a single atomic operation is system-dependent and
186 * therefore unspecified. This option may not be used in conjunction
187 * with the {@code READ} or {@code TRUNCATE_EXISTING} options. </td>
188 * </tr>
189 * <tr>
190 * <td> {@link StandardOpenOption#TRUNCATE_EXISTING TRUNCATE_EXISTING} </td>
191 * <td> If this option is present then the existing file is truncated to
192 * a size of 0 bytes. This option is ignored when the file is opened only
193 * for reading. </td>
194 * </tr>
195 * <tr>
196 * <td> {@link StandardOpenOption#CREATE_NEW CREATE_NEW} </td>
197 * <td> If this option is present then a new file is created, failing if
198 * the file already exists. When creating a file the check for the
220 * <tr>
221 * <td>{@link StandardOpenOption#SPARSE SPARSE} </td>
222 * <td> When creating a new file this option is a <em>hint</em> that the
223 * new file will be sparse. This option is ignored when not creating
224 * a new file. </td>
225 * </tr>
226 * <tr>
227 * <td> {@link StandardOpenOption#SYNC SYNC} </td>
228 * <td> Requires that every update to the file's content or metadata be
229 * written synchronously to the underlying storage device. (see <a
230 * href="../file/package-summary.html#integrity"> Synchronized I/O file
231 * integrity</a>). </td>
232 * </tr>
233 * <tr>
234 * <td> {@link StandardOpenOption#DSYNC DSYNC} </td>
235 * <td> Requires that every update to the file's content be written
236 * synchronously to the underlying storage device. (see <a
237 * href="../file/package-summary.html#integrity"> Synchronized I/O file
238 * integrity</a>). </td>
239 * </tr>
240 * </table>
241 *
242 * <p> An implementation may also support additional options.
243 *
244 * <p> The {@code attrs} parameter is an optional array of file {@link
245 * FileAttribute file-attributes} to set atomically when creating the file.
246 *
247 * <p> The new channel is created by invoking the {@link
248 * FileSystemProvider#newFileChannel newFileChannel} method on the
249 * provider that created the {@code Path}.
250 *
251 * @param path
252 * The path of the file to open or create
253 * @param options
254 * Options specifying how the file is opened
255 * @param attrs
256 * An optional list of file attributes to set atomically when
257 * creating the file
258 *
259 * @return A new file channel
|
157 implements SeekableByteChannel, GatheringByteChannel, ScatteringByteChannel
158 {
159 /**
160 * Initializes a new instance of this class.
161 */
162 protected FileChannel() { }
163
164 /**
165 * Opens or creates a file, returning a file channel to access the file.
166 *
167 * <p> The {@code options} parameter determines how the file is opened.
168 * The {@link StandardOpenOption#READ READ} and {@link StandardOpenOption#WRITE
169 * WRITE} options determine if the file should be opened for reading and/or
170 * writing. If neither option (or the {@link StandardOpenOption#APPEND APPEND}
171 * option) is contained in the array then the file is opened for reading.
172 * By default reading or writing commences at the beginning of the file.
173 *
174 * <p> In the addition to {@code READ} and {@code WRITE}, the following
175 * options may be present:
176 *
177 * <table class="striped">
178 * <caption style="display:none">additional options</caption>
179 * <thead>
180 * <tr> <th>Option</th> <th>Description</th> </tr>
181 * </thead>
182 * <tbody>
183 * <tr>
184 * <td> {@link StandardOpenOption#APPEND APPEND} </td>
185 * <td> If this option is present then the file is opened for writing and
186 * each invocation of the channel's {@code write} method first advances
187 * the position to the end of the file and then writes the requested
188 * data. Whether the advancement of the position and the writing of the
189 * data are done in a single atomic operation is system-dependent and
190 * therefore unspecified. This option may not be used in conjunction
191 * with the {@code READ} or {@code TRUNCATE_EXISTING} options. </td>
192 * </tr>
193 * <tr>
194 * <td> {@link StandardOpenOption#TRUNCATE_EXISTING TRUNCATE_EXISTING} </td>
195 * <td> If this option is present then the existing file is truncated to
196 * a size of 0 bytes. This option is ignored when the file is opened only
197 * for reading. </td>
198 * </tr>
199 * <tr>
200 * <td> {@link StandardOpenOption#CREATE_NEW CREATE_NEW} </td>
201 * <td> If this option is present then a new file is created, failing if
202 * the file already exists. When creating a file the check for the
224 * <tr>
225 * <td>{@link StandardOpenOption#SPARSE SPARSE} </td>
226 * <td> When creating a new file this option is a <em>hint</em> that the
227 * new file will be sparse. This option is ignored when not creating
228 * a new file. </td>
229 * </tr>
230 * <tr>
231 * <td> {@link StandardOpenOption#SYNC SYNC} </td>
232 * <td> Requires that every update to the file's content or metadata be
233 * written synchronously to the underlying storage device. (see <a
234 * href="../file/package-summary.html#integrity"> Synchronized I/O file
235 * integrity</a>). </td>
236 * </tr>
237 * <tr>
238 * <td> {@link StandardOpenOption#DSYNC DSYNC} </td>
239 * <td> Requires that every update to the file's content be written
240 * synchronously to the underlying storage device. (see <a
241 * href="../file/package-summary.html#integrity"> Synchronized I/O file
242 * integrity</a>). </td>
243 * </tr>
244 * </tbody>
245 * </table>
246 *
247 * <p> An implementation may also support additional options.
248 *
249 * <p> The {@code attrs} parameter is an optional array of file {@link
250 * FileAttribute file-attributes} to set atomically when creating the file.
251 *
252 * <p> The new channel is created by invoking the {@link
253 * FileSystemProvider#newFileChannel newFileChannel} method on the
254 * provider that created the {@code Path}.
255 *
256 * @param path
257 * The path of the file to open or create
258 * @param options
259 * Options specifying how the file is opened
260 * @param attrs
261 * An optional list of file attributes to set atomically when
262 * creating the file
263 *
264 * @return A new file channel
|