author | bpb |
Fri, 22 Nov 2019 09:00:16 -0800 | |
changeset 59227 | 46084917fde7 |
parent 54532 | e9c62d960d64 |
permissions | -rw-r--r-- |
2 | 1 |
/* |
59227
46084917fde7
8164993: (ch) ReadableByteChannel should note a possible IllegalArgumentException
bpb
parents:
54532
diff
changeset
|
2 |
* Copyright (c) 2000, 2019, Oracle and/or its affiliates. All rights reserved. |
2 | 3 |
* DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER. |
4 |
* |
|
5 |
* This code is free software; you can redistribute it and/or modify it |
|
6 |
* under the terms of the GNU General Public License version 2 only, as |
|
5506 | 7 |
* published by the Free Software Foundation. Oracle designates this |
2 | 8 |
* particular file as subject to the "Classpath" exception as provided |
5506 | 9 |
* by Oracle in the LICENSE file that accompanied this code. |
2 | 10 |
* |
11 |
* This code is distributed in the hope that it will be useful, but WITHOUT |
|
12 |
* ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or |
|
13 |
* FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License |
|
14 |
* version 2 for more details (a copy is included in the LICENSE file that |
|
15 |
* accompanied this code). |
|
16 |
* |
|
17 |
* You should have received a copy of the GNU General Public License version |
|
18 |
* 2 along with this work; if not, write to the Free Software Foundation, |
|
19 |
* Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA. |
|
20 |
* |
|
5506 | 21 |
* Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA |
22 |
* or visit www.oracle.com if you need additional information or have any |
|
23 |
* questions. |
|
2 | 24 |
*/ |
25 |
||
26 |
package java.nio.channels; |
|
27 |
||
28 |
import java.io.*; |
|
29 |
import java.nio.ByteBuffer; |
|
30 |
import java.nio.MappedByteBuffer; |
|
31 |
import java.nio.channels.spi.AbstractInterruptibleChannel; |
|
2057
3acf8e5e2ca0
6781363: New I/O: Update socket-channel API to jsr203/nio2-b99
alanb
parents:
2
diff
changeset
|
32 |
import java.nio.file.*; |
3acf8e5e2ca0
6781363: New I/O: Update socket-channel API to jsr203/nio2-b99
alanb
parents:
2
diff
changeset
|
33 |
import java.nio.file.attribute.FileAttribute; |
3acf8e5e2ca0
6781363: New I/O: Update socket-channel API to jsr203/nio2-b99
alanb
parents:
2
diff
changeset
|
34 |
import java.nio.file.spi.*; |
3acf8e5e2ca0
6781363: New I/O: Update socket-channel API to jsr203/nio2-b99
alanb
parents:
2
diff
changeset
|
35 |
import java.util.Set; |
3acf8e5e2ca0
6781363: New I/O: Update socket-channel API to jsr203/nio2-b99
alanb
parents:
2
diff
changeset
|
36 |
import java.util.HashSet; |
3acf8e5e2ca0
6781363: New I/O: Update socket-channel API to jsr203/nio2-b99
alanb
parents:
2
diff
changeset
|
37 |
import java.util.Collections; |
2 | 38 |
|
39 |
/** |
|
40 |
* A channel for reading, writing, mapping, and manipulating a file. |
|
41 |
* |
|
3631 | 42 |
* <p> A file channel is a {@link SeekableByteChannel} that is connected to |
2057
3acf8e5e2ca0
6781363: New I/O: Update socket-channel API to jsr203/nio2-b99
alanb
parents:
2
diff
changeset
|
43 |
* a file. It has a current <i>position</i> within its file which can |
3acf8e5e2ca0
6781363: New I/O: Update socket-channel API to jsr203/nio2-b99
alanb
parents:
2
diff
changeset
|
44 |
* be both {@link #position() <i>queried</i>} and {@link #position(long) |
3acf8e5e2ca0
6781363: New I/O: Update socket-channel API to jsr203/nio2-b99
alanb
parents:
2
diff
changeset
|
45 |
* <i>modified</i>}. The file itself contains a variable-length sequence |
2 | 46 |
* of bytes that can be read and written and whose current {@link #size |
2057
3acf8e5e2ca0
6781363: New I/O: Update socket-channel API to jsr203/nio2-b99
alanb
parents:
2
diff
changeset
|
47 |
* <i>size</i>} can be queried. The size of the file increases |
2 | 48 |
* when bytes are written beyond its current size; the size of the file |
18574
4aeaeb541678
8019380: doclint warnings in java.nio, java.nio.file.**, java.nio.channels.**
alanb
parents:
18164
diff
changeset
|
49 |
* decreases when it is {@link #truncate <i>truncated</i>}. The |
2 | 50 |
* file may also have some associated <i>metadata</i> such as access |
51 |
* permissions, content type, and last-modification time; this class does not |
|
52 |
* define methods for metadata access. |
|
53 |
* |
|
54 |
* <p> In addition to the familiar read, write, and close operations of byte |
|
55 |
* channels, this class defines the following file-specific operations: </p> |
|
56 |
* |
|
57 |
* <ul> |
|
58 |
* |
|
2057
3acf8e5e2ca0
6781363: New I/O: Update socket-channel API to jsr203/nio2-b99
alanb
parents:
2
diff
changeset
|
59 |
* <li><p> Bytes may be {@link #read(ByteBuffer, long) read} or |
3acf8e5e2ca0
6781363: New I/O: Update socket-channel API to jsr203/nio2-b99
alanb
parents:
2
diff
changeset
|
60 |
* {@link #write(ByteBuffer, long) <i>written</i>} at an absolute |
2 | 61 |
* position in a file in a way that does not affect the channel's current |
62 |
* position. </p></li> |
|
63 |
* |
|
2057
3acf8e5e2ca0
6781363: New I/O: Update socket-channel API to jsr203/nio2-b99
alanb
parents:
2
diff
changeset
|
64 |
* <li><p> A region of a file may be {@link #map <i>mapped</i>} |
2 | 65 |
* directly into memory; for large files this is often much more efficient |
32143
394ab6a6658d
8133459: replace <tt> tags (obsolete in html5) in java.nio docs
avstepan
parents:
29986
diff
changeset
|
66 |
* than invoking the usual {@code read} or {@code write} methods. |
2 | 67 |
* </p></li> |
68 |
* |
|
2057
3acf8e5e2ca0
6781363: New I/O: Update socket-channel API to jsr203/nio2-b99
alanb
parents:
2
diff
changeset
|
69 |
* <li><p> Updates made to a file may be {@link #force <i>forced |
3acf8e5e2ca0
6781363: New I/O: Update socket-channel API to jsr203/nio2-b99
alanb
parents:
2
diff
changeset
|
70 |
* out</i>} to the underlying storage device, ensuring that data are not |
2 | 71 |
* lost in the event of a system crash. </p></li> |
72 |
* |
|
2057
3acf8e5e2ca0
6781363: New I/O: Update socket-channel API to jsr203/nio2-b99
alanb
parents:
2
diff
changeset
|
73 |
* <li><p> Bytes can be transferred from a file {@link #transferTo <i>to |
3acf8e5e2ca0
6781363: New I/O: Update socket-channel API to jsr203/nio2-b99
alanb
parents:
2
diff
changeset
|
74 |
* some other channel</i>}, and {@link #transferFrom <i>vice |
3acf8e5e2ca0
6781363: New I/O: Update socket-channel API to jsr203/nio2-b99
alanb
parents:
2
diff
changeset
|
75 |
* versa</i>}, in a way that can be optimized by many operating systems |
2 | 76 |
* into a very fast transfer directly to or from the filesystem cache. |
77 |
* </p></li> |
|
78 |
* |
|
2057
3acf8e5e2ca0
6781363: New I/O: Update socket-channel API to jsr203/nio2-b99
alanb
parents:
2
diff
changeset
|
79 |
* <li><p> A region of a file may be {@link FileLock <i>locked</i>} |
2 | 80 |
* against access by other programs. </p></li> |
81 |
* |
|
82 |
* </ul> |
|
83 |
* |
|
84 |
* <p> File channels are safe for use by multiple concurrent threads. The |
|
85 |
* {@link Channel#close close} method may be invoked at any time, as specified |
|
86 |
* by the {@link Channel} interface. Only one operation that involves the |
|
87 |
* channel's position or can change its file's size may be in progress at any |
|
88 |
* given time; attempts to initiate a second such operation while the first is |
|
89 |
* still in progress will block until the first operation completes. Other |
|
90 |
* operations, in particular those that take an explicit position, may proceed |
|
91 |
* concurrently; whether they in fact do so is dependent upon the underlying |
|
92 |
* implementation and is therefore unspecified. |
|
93 |
* |
|
94 |
* <p> The view of a file provided by an instance of this class is guaranteed |
|
95 |
* to be consistent with other views of the same file provided by other |
|
96 |
* instances in the same program. The view provided by an instance of this |
|
97 |
* class may or may not, however, be consistent with the views seen by other |
|
98 |
* concurrently-running programs due to caching performed by the underlying |
|
99 |
* operating system and delays induced by network-filesystem protocols. This |
|
100 |
* is true regardless of the language in which these other programs are |
|
101 |
* written, and whether they are running on the same machine or on some other |
|
102 |
* machine. The exact nature of any such inconsistencies are system-dependent |
|
103 |
* and are therefore unspecified. |
|
104 |
* |
|
2057
3acf8e5e2ca0
6781363: New I/O: Update socket-channel API to jsr203/nio2-b99
alanb
parents:
2
diff
changeset
|
105 |
* <p> A file channel is created by invoking one of the {@link #open open} |
3acf8e5e2ca0
6781363: New I/O: Update socket-channel API to jsr203/nio2-b99
alanb
parents:
2
diff
changeset
|
106 |
* methods defined by this class. A file channel can also be obtained from an |
3acf8e5e2ca0
6781363: New I/O: Update socket-channel API to jsr203/nio2-b99
alanb
parents:
2
diff
changeset
|
107 |
* existing {@link java.io.FileInputStream#getChannel FileInputStream}, {@link |
2 | 108 |
* java.io.FileOutputStream#getChannel FileOutputStream}, or {@link |
109 |
* java.io.RandomAccessFile#getChannel RandomAccessFile} object by invoking |
|
32143
394ab6a6658d
8133459: replace <tt> tags (obsolete in html5) in java.nio docs
avstepan
parents:
29986
diff
changeset
|
110 |
* that object's {@code getChannel} method, which returns a file channel that |
2057
3acf8e5e2ca0
6781363: New I/O: Update socket-channel API to jsr203/nio2-b99
alanb
parents:
2
diff
changeset
|
111 |
* is connected to the same underlying file. Where the file channel is obtained |
3acf8e5e2ca0
6781363: New I/O: Update socket-channel API to jsr203/nio2-b99
alanb
parents:
2
diff
changeset
|
112 |
* from an existing stream or random access file then the state of the file |
32143
394ab6a6658d
8133459: replace <tt> tags (obsolete in html5) in java.nio docs
avstepan
parents:
29986
diff
changeset
|
113 |
* channel is intimately connected to that of the object whose {@code getChannel} |
2057
3acf8e5e2ca0
6781363: New I/O: Update socket-channel API to jsr203/nio2-b99
alanb
parents:
2
diff
changeset
|
114 |
* method returned the channel. Changing the channel's position, whether |
3acf8e5e2ca0
6781363: New I/O: Update socket-channel API to jsr203/nio2-b99
alanb
parents:
2
diff
changeset
|
115 |
* explicitly or by reading or writing bytes, will change the file position of |
3acf8e5e2ca0
6781363: New I/O: Update socket-channel API to jsr203/nio2-b99
alanb
parents:
2
diff
changeset
|
116 |
* the originating object, and vice versa. Changing the file's length via the |
3acf8e5e2ca0
6781363: New I/O: Update socket-channel API to jsr203/nio2-b99
alanb
parents:
2
diff
changeset
|
117 |
* file channel will change the length seen via the originating object, and vice |
3acf8e5e2ca0
6781363: New I/O: Update socket-channel API to jsr203/nio2-b99
alanb
parents:
2
diff
changeset
|
118 |
* versa. Changing the file's content by writing bytes will change the content |
3acf8e5e2ca0
6781363: New I/O: Update socket-channel API to jsr203/nio2-b99
alanb
parents:
2
diff
changeset
|
119 |
* seen by the originating object, and vice versa. |
2 | 120 |
* |
44844
b2b4d98404ba
8179364: update "<a name=" in java.base module to use id attribute
jjg
parents:
32143
diff
changeset
|
121 |
* <a id="open-mode"></a> <p> At various points this class specifies that an |
2 | 122 |
* instance that is "open for reading," "open for writing," or "open for |
123 |
* reading and writing" is required. A channel obtained via the {@link |
|
124 |
* java.io.FileInputStream#getChannel getChannel} method of a {@link |
|
125 |
* java.io.FileInputStream} instance will be open for reading. A channel |
|
126 |
* obtained via the {@link java.io.FileOutputStream#getChannel getChannel} |
|
127 |
* method of a {@link java.io.FileOutputStream} instance will be open for |
|
128 |
* writing. Finally, a channel obtained via the {@link |
|
129 |
* java.io.RandomAccessFile#getChannel getChannel} method of a {@link |
|
130 |
* java.io.RandomAccessFile} instance will be open for reading if the instance |
|
32143
394ab6a6658d
8133459: replace <tt> tags (obsolete in html5) in java.nio docs
avstepan
parents:
29986
diff
changeset
|
131 |
* was created with mode {@code "r"} and will be open for reading and writing |
394ab6a6658d
8133459: replace <tt> tags (obsolete in html5) in java.nio docs
avstepan
parents:
29986
diff
changeset
|
132 |
* if the instance was created with mode {@code "rw"}. |
2 | 133 |
* |
44844
b2b4d98404ba
8179364: update "<a name=" in java.base module to use id attribute
jjg
parents:
32143
diff
changeset
|
134 |
* <a id="append-mode"></a><p> A file channel that is open for writing may be in |
2 | 135 |
* <i>append mode</i>, for example if it was obtained from a file-output stream |
136 |
* that was created by invoking the {@link |
|
137 |
* java.io.FileOutputStream#FileOutputStream(java.io.File,boolean) |
|
32143
394ab6a6658d
8133459: replace <tt> tags (obsolete in html5) in java.nio docs
avstepan
parents:
29986
diff
changeset
|
138 |
* FileOutputStream(File,boolean)} constructor and passing {@code true} for |
2 | 139 |
* the second parameter. In this mode each invocation of a relative write |
140 |
* operation first advances the position to the end of the file and then writes |
|
141 |
* the requested data. Whether the advancement of the position and the writing |
|
142 |
* of the data are done in a single atomic operation is system-dependent and |
|
143 |
* therefore unspecified. |
|
144 |
* |
|
145 |
* @see java.io.FileInputStream#getChannel() |
|
146 |
* @see java.io.FileOutputStream#getChannel() |
|
147 |
* @see java.io.RandomAccessFile#getChannel() |
|
148 |
* |
|
149 |
* @author Mark Reinhold |
|
150 |
* @author Mike McCloskey |
|
151 |
* @author JSR-51 Expert Group |
|
152 |
* @since 1.4 |
|
153 |
*/ |
|
154 |
||
155 |
public abstract class FileChannel |
|
156 |
extends AbstractInterruptibleChannel |
|
2057
3acf8e5e2ca0
6781363: New I/O: Update socket-channel API to jsr203/nio2-b99
alanb
parents:
2
diff
changeset
|
157 |
implements SeekableByteChannel, GatheringByteChannel, ScatteringByteChannel |
2 | 158 |
{ |
159 |
/** |
|
160 |
* Initializes a new instance of this class. |
|
161 |
*/ |
|
162 |
protected FileChannel() { } |
|
163 |
||
2057
3acf8e5e2ca0
6781363: New I/O: Update socket-channel API to jsr203/nio2-b99
alanb
parents:
2
diff
changeset
|
164 |
/** |
3acf8e5e2ca0
6781363: New I/O: Update socket-channel API to jsr203/nio2-b99
alanb
parents:
2
diff
changeset
|
165 |
* Opens or creates a file, returning a file channel to access the file. |
3acf8e5e2ca0
6781363: New I/O: Update socket-channel API to jsr203/nio2-b99
alanb
parents:
2
diff
changeset
|
166 |
* |
3acf8e5e2ca0
6781363: New I/O: Update socket-channel API to jsr203/nio2-b99
alanb
parents:
2
diff
changeset
|
167 |
* <p> The {@code options} parameter determines how the file is opened. |
3acf8e5e2ca0
6781363: New I/O: Update socket-channel API to jsr203/nio2-b99
alanb
parents:
2
diff
changeset
|
168 |
* The {@link StandardOpenOption#READ READ} and {@link StandardOpenOption#WRITE |
3acf8e5e2ca0
6781363: New I/O: Update socket-channel API to jsr203/nio2-b99
alanb
parents:
2
diff
changeset
|
169 |
* WRITE} options determine if the file should be opened for reading and/or |
3acf8e5e2ca0
6781363: New I/O: Update socket-channel API to jsr203/nio2-b99
alanb
parents:
2
diff
changeset
|
170 |
* writing. If neither option (or the {@link StandardOpenOption#APPEND APPEND} |
3acf8e5e2ca0
6781363: New I/O: Update socket-channel API to jsr203/nio2-b99
alanb
parents:
2
diff
changeset
|
171 |
* option) is contained in the array then the file is opened for reading. |
3acf8e5e2ca0
6781363: New I/O: Update socket-channel API to jsr203/nio2-b99
alanb
parents:
2
diff
changeset
|
172 |
* By default reading or writing commences at the beginning of the file. |
3acf8e5e2ca0
6781363: New I/O: Update socket-channel API to jsr203/nio2-b99
alanb
parents:
2
diff
changeset
|
173 |
* |
3acf8e5e2ca0
6781363: New I/O: Update socket-channel API to jsr203/nio2-b99
alanb
parents:
2
diff
changeset
|
174 |
* <p> In the addition to {@code READ} and {@code WRITE}, the following |
3acf8e5e2ca0
6781363: New I/O: Update socket-channel API to jsr203/nio2-b99
alanb
parents:
2
diff
changeset
|
175 |
* options may be present: |
3acf8e5e2ca0
6781363: New I/O: Update socket-channel API to jsr203/nio2-b99
alanb
parents:
2
diff
changeset
|
176 |
* |
45124
144479e89cdb
8179592: Update tables in java.base to be HTML 5-friendly.
jjg
parents:
44844
diff
changeset
|
177 |
* <table class="striped"> |
144479e89cdb
8179592: Update tables in java.base to be HTML 5-friendly.
jjg
parents:
44844
diff
changeset
|
178 |
* <caption style="display:none">additional options</caption> |
144479e89cdb
8179592: Update tables in java.base to be HTML 5-friendly.
jjg
parents:
44844
diff
changeset
|
179 |
* <thead> |
45881
aaec0fbe17ae
8184208: update class="striped" tables for accessibility
jjg
parents:
45124
diff
changeset
|
180 |
* <tr> <th scope="col">Option</th> <th scope="col">Description</th> </tr> |
45124
144479e89cdb
8179592: Update tables in java.base to be HTML 5-friendly.
jjg
parents:
44844
diff
changeset
|
181 |
* </thead> |
144479e89cdb
8179592: Update tables in java.base to be HTML 5-friendly.
jjg
parents:
44844
diff
changeset
|
182 |
* <tbody> |
2057
3acf8e5e2ca0
6781363: New I/O: Update socket-channel API to jsr203/nio2-b99
alanb
parents:
2
diff
changeset
|
183 |
* <tr> |
45881
aaec0fbe17ae
8184208: update class="striped" tables for accessibility
jjg
parents:
45124
diff
changeset
|
184 |
* <th scope="row"> {@link StandardOpenOption#APPEND APPEND} </th> |
2057
3acf8e5e2ca0
6781363: New I/O: Update socket-channel API to jsr203/nio2-b99
alanb
parents:
2
diff
changeset
|
185 |
* <td> If this option is present then the file is opened for writing and |
3acf8e5e2ca0
6781363: New I/O: Update socket-channel API to jsr203/nio2-b99
alanb
parents:
2
diff
changeset
|
186 |
* each invocation of the channel's {@code write} method first advances |
3acf8e5e2ca0
6781363: New I/O: Update socket-channel API to jsr203/nio2-b99
alanb
parents:
2
diff
changeset
|
187 |
* the position to the end of the file and then writes the requested |
3acf8e5e2ca0
6781363: New I/O: Update socket-channel API to jsr203/nio2-b99
alanb
parents:
2
diff
changeset
|
188 |
* data. Whether the advancement of the position and the writing of the |
3acf8e5e2ca0
6781363: New I/O: Update socket-channel API to jsr203/nio2-b99
alanb
parents:
2
diff
changeset
|
189 |
* data are done in a single atomic operation is system-dependent and |
3acf8e5e2ca0
6781363: New I/O: Update socket-channel API to jsr203/nio2-b99
alanb
parents:
2
diff
changeset
|
190 |
* therefore unspecified. This option may not be used in conjunction |
3acf8e5e2ca0
6781363: New I/O: Update socket-channel API to jsr203/nio2-b99
alanb
parents:
2
diff
changeset
|
191 |
* with the {@code READ} or {@code TRUNCATE_EXISTING} options. </td> |
3acf8e5e2ca0
6781363: New I/O: Update socket-channel API to jsr203/nio2-b99
alanb
parents:
2
diff
changeset
|
192 |
* </tr> |
3acf8e5e2ca0
6781363: New I/O: Update socket-channel API to jsr203/nio2-b99
alanb
parents:
2
diff
changeset
|
193 |
* <tr> |
45881
aaec0fbe17ae
8184208: update class="striped" tables for accessibility
jjg
parents:
45124
diff
changeset
|
194 |
* <th scope="row"> {@link StandardOpenOption#TRUNCATE_EXISTING TRUNCATE_EXISTING} </th> |
2057
3acf8e5e2ca0
6781363: New I/O: Update socket-channel API to jsr203/nio2-b99
alanb
parents:
2
diff
changeset
|
195 |
* <td> If this option is present then the existing file is truncated to |
3acf8e5e2ca0
6781363: New I/O: Update socket-channel API to jsr203/nio2-b99
alanb
parents:
2
diff
changeset
|
196 |
* a size of 0 bytes. This option is ignored when the file is opened only |
3acf8e5e2ca0
6781363: New I/O: Update socket-channel API to jsr203/nio2-b99
alanb
parents:
2
diff
changeset
|
197 |
* for reading. </td> |
3acf8e5e2ca0
6781363: New I/O: Update socket-channel API to jsr203/nio2-b99
alanb
parents:
2
diff
changeset
|
198 |
* </tr> |
3acf8e5e2ca0
6781363: New I/O: Update socket-channel API to jsr203/nio2-b99
alanb
parents:
2
diff
changeset
|
199 |
* <tr> |
45881
aaec0fbe17ae
8184208: update class="striped" tables for accessibility
jjg
parents:
45124
diff
changeset
|
200 |
* <th scope="row"> {@link StandardOpenOption#CREATE_NEW CREATE_NEW} </th> |
2057
3acf8e5e2ca0
6781363: New I/O: Update socket-channel API to jsr203/nio2-b99
alanb
parents:
2
diff
changeset
|
201 |
* <td> If this option is present then a new file is created, failing if |
3acf8e5e2ca0
6781363: New I/O: Update socket-channel API to jsr203/nio2-b99
alanb
parents:
2
diff
changeset
|
202 |
* the file already exists. When creating a file the check for the |
3acf8e5e2ca0
6781363: New I/O: Update socket-channel API to jsr203/nio2-b99
alanb
parents:
2
diff
changeset
|
203 |
* existence of the file and the creation of the file if it does not exist |
3acf8e5e2ca0
6781363: New I/O: Update socket-channel API to jsr203/nio2-b99
alanb
parents:
2
diff
changeset
|
204 |
* is atomic with respect to other file system operations. This option is |
3acf8e5e2ca0
6781363: New I/O: Update socket-channel API to jsr203/nio2-b99
alanb
parents:
2
diff
changeset
|
205 |
* ignored when the file is opened only for reading. </td> |
3acf8e5e2ca0
6781363: New I/O: Update socket-channel API to jsr203/nio2-b99
alanb
parents:
2
diff
changeset
|
206 |
* </tr> |
3acf8e5e2ca0
6781363: New I/O: Update socket-channel API to jsr203/nio2-b99
alanb
parents:
2
diff
changeset
|
207 |
* <tr> |
45881
aaec0fbe17ae
8184208: update class="striped" tables for accessibility
jjg
parents:
45124
diff
changeset
|
208 |
* <th scope="row" > {@link StandardOpenOption#CREATE CREATE} </th> |
2057
3acf8e5e2ca0
6781363: New I/O: Update socket-channel API to jsr203/nio2-b99
alanb
parents:
2
diff
changeset
|
209 |
* <td> If this option is present then an existing file is opened if it |
3acf8e5e2ca0
6781363: New I/O: Update socket-channel API to jsr203/nio2-b99
alanb
parents:
2
diff
changeset
|
210 |
* exists, otherwise a new file is created. When creating a file the check |
3acf8e5e2ca0
6781363: New I/O: Update socket-channel API to jsr203/nio2-b99
alanb
parents:
2
diff
changeset
|
211 |
* for the existence of the file and the creation of the file if it does |
3acf8e5e2ca0
6781363: New I/O: Update socket-channel API to jsr203/nio2-b99
alanb
parents:
2
diff
changeset
|
212 |
* not exist is atomic with respect to other file system operations. This |
3acf8e5e2ca0
6781363: New I/O: Update socket-channel API to jsr203/nio2-b99
alanb
parents:
2
diff
changeset
|
213 |
* option is ignored if the {@code CREATE_NEW} option is also present or |
3acf8e5e2ca0
6781363: New I/O: Update socket-channel API to jsr203/nio2-b99
alanb
parents:
2
diff
changeset
|
214 |
* the file is opened only for reading. </td> |
3acf8e5e2ca0
6781363: New I/O: Update socket-channel API to jsr203/nio2-b99
alanb
parents:
2
diff
changeset
|
215 |
* </tr> |
3acf8e5e2ca0
6781363: New I/O: Update socket-channel API to jsr203/nio2-b99
alanb
parents:
2
diff
changeset
|
216 |
* <tr> |
45881
aaec0fbe17ae
8184208: update class="striped" tables for accessibility
jjg
parents:
45124
diff
changeset
|
217 |
* <th scope="row" > {@link StandardOpenOption#DELETE_ON_CLOSE DELETE_ON_CLOSE} </th> |
2057
3acf8e5e2ca0
6781363: New I/O: Update socket-channel API to jsr203/nio2-b99
alanb
parents:
2
diff
changeset
|
218 |
* <td> When this option is present then the implementation makes a |
47478 | 219 |
* <em>best effort</em> attempt to delete the file when closed by |
2057
3acf8e5e2ca0
6781363: New I/O: Update socket-channel API to jsr203/nio2-b99
alanb
parents:
2
diff
changeset
|
220 |
* the {@link #close close} method. If the {@code close} method is not |
3acf8e5e2ca0
6781363: New I/O: Update socket-channel API to jsr203/nio2-b99
alanb
parents:
2
diff
changeset
|
221 |
* invoked then a <em>best effort</em> attempt is made to delete the file |
3acf8e5e2ca0
6781363: New I/O: Update socket-channel API to jsr203/nio2-b99
alanb
parents:
2
diff
changeset
|
222 |
* when the Java virtual machine terminates. </td> |
3acf8e5e2ca0
6781363: New I/O: Update socket-channel API to jsr203/nio2-b99
alanb
parents:
2
diff
changeset
|
223 |
* </tr> |
3acf8e5e2ca0
6781363: New I/O: Update socket-channel API to jsr203/nio2-b99
alanb
parents:
2
diff
changeset
|
224 |
* <tr> |
45881
aaec0fbe17ae
8184208: update class="striped" tables for accessibility
jjg
parents:
45124
diff
changeset
|
225 |
* <th scope="row">{@link StandardOpenOption#SPARSE SPARSE} </th> |
2057
3acf8e5e2ca0
6781363: New I/O: Update socket-channel API to jsr203/nio2-b99
alanb
parents:
2
diff
changeset
|
226 |
* <td> When creating a new file this option is a <em>hint</em> that the |
3acf8e5e2ca0
6781363: New I/O: Update socket-channel API to jsr203/nio2-b99
alanb
parents:
2
diff
changeset
|
227 |
* new file will be sparse. This option is ignored when not creating |
3acf8e5e2ca0
6781363: New I/O: Update socket-channel API to jsr203/nio2-b99
alanb
parents:
2
diff
changeset
|
228 |
* a new file. </td> |
3acf8e5e2ca0
6781363: New I/O: Update socket-channel API to jsr203/nio2-b99
alanb
parents:
2
diff
changeset
|
229 |
* </tr> |
3acf8e5e2ca0
6781363: New I/O: Update socket-channel API to jsr203/nio2-b99
alanb
parents:
2
diff
changeset
|
230 |
* <tr> |
45881
aaec0fbe17ae
8184208: update class="striped" tables for accessibility
jjg
parents:
45124
diff
changeset
|
231 |
* <th scope="row"> {@link StandardOpenOption#SYNC SYNC} </th> |
2057
3acf8e5e2ca0
6781363: New I/O: Update socket-channel API to jsr203/nio2-b99
alanb
parents:
2
diff
changeset
|
232 |
* <td> Requires that every update to the file's content or metadata be |
3acf8e5e2ca0
6781363: New I/O: Update socket-channel API to jsr203/nio2-b99
alanb
parents:
2
diff
changeset
|
233 |
* written synchronously to the underlying storage device. (see <a |
3acf8e5e2ca0
6781363: New I/O: Update socket-channel API to jsr203/nio2-b99
alanb
parents:
2
diff
changeset
|
234 |
* href="../file/package-summary.html#integrity"> Synchronized I/O file |
3acf8e5e2ca0
6781363: New I/O: Update socket-channel API to jsr203/nio2-b99
alanb
parents:
2
diff
changeset
|
235 |
* integrity</a>). </td> |
21801
b8a5ff5f0c2a
8028049: Tidy warnings cleanup for packages java.nio/java.io
yan
parents:
18574
diff
changeset
|
236 |
* </tr> |
2057
3acf8e5e2ca0
6781363: New I/O: Update socket-channel API to jsr203/nio2-b99
alanb
parents:
2
diff
changeset
|
237 |
* <tr> |
45881
aaec0fbe17ae
8184208: update class="striped" tables for accessibility
jjg
parents:
45124
diff
changeset
|
238 |
* <th scope="row"> {@link StandardOpenOption#DSYNC DSYNC} </th> |
2057
3acf8e5e2ca0
6781363: New I/O: Update socket-channel API to jsr203/nio2-b99
alanb
parents:
2
diff
changeset
|
239 |
* <td> Requires that every update to the file's content be written |
3acf8e5e2ca0
6781363: New I/O: Update socket-channel API to jsr203/nio2-b99
alanb
parents:
2
diff
changeset
|
240 |
* synchronously to the underlying storage device. (see <a |
3acf8e5e2ca0
6781363: New I/O: Update socket-channel API to jsr203/nio2-b99
alanb
parents:
2
diff
changeset
|
241 |
* href="../file/package-summary.html#integrity"> Synchronized I/O file |
3acf8e5e2ca0
6781363: New I/O: Update socket-channel API to jsr203/nio2-b99
alanb
parents:
2
diff
changeset
|
242 |
* integrity</a>). </td> |
3acf8e5e2ca0
6781363: New I/O: Update socket-channel API to jsr203/nio2-b99
alanb
parents:
2
diff
changeset
|
243 |
* </tr> |
45124
144479e89cdb
8179592: Update tables in java.base to be HTML 5-friendly.
jjg
parents:
44844
diff
changeset
|
244 |
* </tbody> |
2057
3acf8e5e2ca0
6781363: New I/O: Update socket-channel API to jsr203/nio2-b99
alanb
parents:
2
diff
changeset
|
245 |
* </table> |
3acf8e5e2ca0
6781363: New I/O: Update socket-channel API to jsr203/nio2-b99
alanb
parents:
2
diff
changeset
|
246 |
* |
3acf8e5e2ca0
6781363: New I/O: Update socket-channel API to jsr203/nio2-b99
alanb
parents:
2
diff
changeset
|
247 |
* <p> An implementation may also support additional options. |
3acf8e5e2ca0
6781363: New I/O: Update socket-channel API to jsr203/nio2-b99
alanb
parents:
2
diff
changeset
|
248 |
* |
3acf8e5e2ca0
6781363: New I/O: Update socket-channel API to jsr203/nio2-b99
alanb
parents:
2
diff
changeset
|
249 |
* <p> The {@code attrs} parameter is an optional array of file {@link |
3acf8e5e2ca0
6781363: New I/O: Update socket-channel API to jsr203/nio2-b99
alanb
parents:
2
diff
changeset
|
250 |
* FileAttribute file-attributes} to set atomically when creating the file. |
3acf8e5e2ca0
6781363: New I/O: Update socket-channel API to jsr203/nio2-b99
alanb
parents:
2
diff
changeset
|
251 |
* |
3acf8e5e2ca0
6781363: New I/O: Update socket-channel API to jsr203/nio2-b99
alanb
parents:
2
diff
changeset
|
252 |
* <p> The new channel is created by invoking the {@link |
3acf8e5e2ca0
6781363: New I/O: Update socket-channel API to jsr203/nio2-b99
alanb
parents:
2
diff
changeset
|
253 |
* FileSystemProvider#newFileChannel newFileChannel} method on the |
3acf8e5e2ca0
6781363: New I/O: Update socket-channel API to jsr203/nio2-b99
alanb
parents:
2
diff
changeset
|
254 |
* provider that created the {@code Path}. |
3acf8e5e2ca0
6781363: New I/O: Update socket-channel API to jsr203/nio2-b99
alanb
parents:
2
diff
changeset
|
255 |
* |
8158 | 256 |
* @param path |
2057
3acf8e5e2ca0
6781363: New I/O: Update socket-channel API to jsr203/nio2-b99
alanb
parents:
2
diff
changeset
|
257 |
* The path of the file to open or create |
3acf8e5e2ca0
6781363: New I/O: Update socket-channel API to jsr203/nio2-b99
alanb
parents:
2
diff
changeset
|
258 |
* @param options |
3acf8e5e2ca0
6781363: New I/O: Update socket-channel API to jsr203/nio2-b99
alanb
parents:
2
diff
changeset
|
259 |
* Options specifying how the file is opened |
3acf8e5e2ca0
6781363: New I/O: Update socket-channel API to jsr203/nio2-b99
alanb
parents:
2
diff
changeset
|
260 |
* @param attrs |
3acf8e5e2ca0
6781363: New I/O: Update socket-channel API to jsr203/nio2-b99
alanb
parents:
2
diff
changeset
|
261 |
* An optional list of file attributes to set atomically when |
3acf8e5e2ca0
6781363: New I/O: Update socket-channel API to jsr203/nio2-b99
alanb
parents:
2
diff
changeset
|
262 |
* creating the file |
3acf8e5e2ca0
6781363: New I/O: Update socket-channel API to jsr203/nio2-b99
alanb
parents:
2
diff
changeset
|
263 |
* |
3acf8e5e2ca0
6781363: New I/O: Update socket-channel API to jsr203/nio2-b99
alanb
parents:
2
diff
changeset
|
264 |
* @return A new file channel |
3acf8e5e2ca0
6781363: New I/O: Update socket-channel API to jsr203/nio2-b99
alanb
parents:
2
diff
changeset
|
265 |
* |
3acf8e5e2ca0
6781363: New I/O: Update socket-channel API to jsr203/nio2-b99
alanb
parents:
2
diff
changeset
|
266 |
* @throws IllegalArgumentException |
3acf8e5e2ca0
6781363: New I/O: Update socket-channel API to jsr203/nio2-b99
alanb
parents:
2
diff
changeset
|
267 |
* If the set contains an invalid combination of options |
3acf8e5e2ca0
6781363: New I/O: Update socket-channel API to jsr203/nio2-b99
alanb
parents:
2
diff
changeset
|
268 |
* @throws UnsupportedOperationException |
8158 | 269 |
* If the {@code path} is associated with a provider that does not |
2057
3acf8e5e2ca0
6781363: New I/O: Update socket-channel API to jsr203/nio2-b99
alanb
parents:
2
diff
changeset
|
270 |
* support creating file channels, or an unsupported open option is |
3acf8e5e2ca0
6781363: New I/O: Update socket-channel API to jsr203/nio2-b99
alanb
parents:
2
diff
changeset
|
271 |
* specified, or the array contains an attribute that cannot be set |
3acf8e5e2ca0
6781363: New I/O: Update socket-channel API to jsr203/nio2-b99
alanb
parents:
2
diff
changeset
|
272 |
* atomically when creating the file |
3acf8e5e2ca0
6781363: New I/O: Update socket-channel API to jsr203/nio2-b99
alanb
parents:
2
diff
changeset
|
273 |
* @throws IOException |
3acf8e5e2ca0
6781363: New I/O: Update socket-channel API to jsr203/nio2-b99
alanb
parents:
2
diff
changeset
|
274 |
* If an I/O error occurs |
3acf8e5e2ca0
6781363: New I/O: Update socket-channel API to jsr203/nio2-b99
alanb
parents:
2
diff
changeset
|
275 |
* @throws SecurityException |
3acf8e5e2ca0
6781363: New I/O: Update socket-channel API to jsr203/nio2-b99
alanb
parents:
2
diff
changeset
|
276 |
* If a security manager is installed and it denies an |
3acf8e5e2ca0
6781363: New I/O: Update socket-channel API to jsr203/nio2-b99
alanb
parents:
2
diff
changeset
|
277 |
* unspecified permission required by the implementation. |
3acf8e5e2ca0
6781363: New I/O: Update socket-channel API to jsr203/nio2-b99
alanb
parents:
2
diff
changeset
|
278 |
* In the case of the default provider, the {@link |
3acf8e5e2ca0
6781363: New I/O: Update socket-channel API to jsr203/nio2-b99
alanb
parents:
2
diff
changeset
|
279 |
* SecurityManager#checkRead(String)} method is invoked to check |
3acf8e5e2ca0
6781363: New I/O: Update socket-channel API to jsr203/nio2-b99
alanb
parents:
2
diff
changeset
|
280 |
* read access if the file is opened for reading. The {@link |
3acf8e5e2ca0
6781363: New I/O: Update socket-channel API to jsr203/nio2-b99
alanb
parents:
2
diff
changeset
|
281 |
* SecurityManager#checkWrite(String)} method is invoked to check |
3acf8e5e2ca0
6781363: New I/O: Update socket-channel API to jsr203/nio2-b99
alanb
parents:
2
diff
changeset
|
282 |
* write access if the file is opened for writing |
3acf8e5e2ca0
6781363: New I/O: Update socket-channel API to jsr203/nio2-b99
alanb
parents:
2
diff
changeset
|
283 |
* |
3acf8e5e2ca0
6781363: New I/O: Update socket-channel API to jsr203/nio2-b99
alanb
parents:
2
diff
changeset
|
284 |
* @since 1.7 |
3acf8e5e2ca0
6781363: New I/O: Update socket-channel API to jsr203/nio2-b99
alanb
parents:
2
diff
changeset
|
285 |
*/ |
8158 | 286 |
public static FileChannel open(Path path, |
2057
3acf8e5e2ca0
6781363: New I/O: Update socket-channel API to jsr203/nio2-b99
alanb
parents:
2
diff
changeset
|
287 |
Set<? extends OpenOption> options, |
3acf8e5e2ca0
6781363: New I/O: Update socket-channel API to jsr203/nio2-b99
alanb
parents:
2
diff
changeset
|
288 |
FileAttribute<?>... attrs) |
3acf8e5e2ca0
6781363: New I/O: Update socket-channel API to jsr203/nio2-b99
alanb
parents:
2
diff
changeset
|
289 |
throws IOException |
3acf8e5e2ca0
6781363: New I/O: Update socket-channel API to jsr203/nio2-b99
alanb
parents:
2
diff
changeset
|
290 |
{ |
8158 | 291 |
FileSystemProvider provider = path.getFileSystem().provider(); |
292 |
return provider.newFileChannel(path, options, attrs); |
|
2057
3acf8e5e2ca0
6781363: New I/O: Update socket-channel API to jsr203/nio2-b99
alanb
parents:
2
diff
changeset
|
293 |
} |
3acf8e5e2ca0
6781363: New I/O: Update socket-channel API to jsr203/nio2-b99
alanb
parents:
2
diff
changeset
|
294 |
|
13795
73850c397272
7193406: Clean-up JDK Build Warnings in java.util, java.io
dxu
parents:
10137
diff
changeset
|
295 |
@SuppressWarnings({"unchecked", "rawtypes"}) // generic array construction |
2057
3acf8e5e2ca0
6781363: New I/O: Update socket-channel API to jsr203/nio2-b99
alanb
parents:
2
diff
changeset
|
296 |
private static final FileAttribute<?>[] NO_ATTRIBUTES = new FileAttribute[0]; |
3acf8e5e2ca0
6781363: New I/O: Update socket-channel API to jsr203/nio2-b99
alanb
parents:
2
diff
changeset
|
297 |
|
3acf8e5e2ca0
6781363: New I/O: Update socket-channel API to jsr203/nio2-b99
alanb
parents:
2
diff
changeset
|
298 |
/** |
3acf8e5e2ca0
6781363: New I/O: Update socket-channel API to jsr203/nio2-b99
alanb
parents:
2
diff
changeset
|
299 |
* Opens or creates a file, returning a file channel to access the file. |
3acf8e5e2ca0
6781363: New I/O: Update socket-channel API to jsr203/nio2-b99
alanb
parents:
2
diff
changeset
|
300 |
* |
3acf8e5e2ca0
6781363: New I/O: Update socket-channel API to jsr203/nio2-b99
alanb
parents:
2
diff
changeset
|
301 |
* <p> An invocation of this method behaves in exactly the same way as the |
3acf8e5e2ca0
6781363: New I/O: Update socket-channel API to jsr203/nio2-b99
alanb
parents:
2
diff
changeset
|
302 |
* invocation |
3acf8e5e2ca0
6781363: New I/O: Update socket-channel API to jsr203/nio2-b99
alanb
parents:
2
diff
changeset
|
303 |
* <pre> |
8158 | 304 |
* fc.{@link #open(Path,Set,FileAttribute[]) open}(file, opts, new FileAttribute<?>[0]); |
2057
3acf8e5e2ca0
6781363: New I/O: Update socket-channel API to jsr203/nio2-b99
alanb
parents:
2
diff
changeset
|
305 |
* </pre> |
8158 | 306 |
* where {@code opts} is a set of the options specified in the {@code |
307 |
* options} array. |
|
2057
3acf8e5e2ca0
6781363: New I/O: Update socket-channel API to jsr203/nio2-b99
alanb
parents:
2
diff
changeset
|
308 |
* |
8158 | 309 |
* @param path |
2057
3acf8e5e2ca0
6781363: New I/O: Update socket-channel API to jsr203/nio2-b99
alanb
parents:
2
diff
changeset
|
310 |
* The path of the file to open or create |
3acf8e5e2ca0
6781363: New I/O: Update socket-channel API to jsr203/nio2-b99
alanb
parents:
2
diff
changeset
|
311 |
* @param options |
3acf8e5e2ca0
6781363: New I/O: Update socket-channel API to jsr203/nio2-b99
alanb
parents:
2
diff
changeset
|
312 |
* Options specifying how the file is opened |
3acf8e5e2ca0
6781363: New I/O: Update socket-channel API to jsr203/nio2-b99
alanb
parents:
2
diff
changeset
|
313 |
* |
3acf8e5e2ca0
6781363: New I/O: Update socket-channel API to jsr203/nio2-b99
alanb
parents:
2
diff
changeset
|
314 |
* @return A new file channel |
3acf8e5e2ca0
6781363: New I/O: Update socket-channel API to jsr203/nio2-b99
alanb
parents:
2
diff
changeset
|
315 |
* |
3acf8e5e2ca0
6781363: New I/O: Update socket-channel API to jsr203/nio2-b99
alanb
parents:
2
diff
changeset
|
316 |
* @throws IllegalArgumentException |
3acf8e5e2ca0
6781363: New I/O: Update socket-channel API to jsr203/nio2-b99
alanb
parents:
2
diff
changeset
|
317 |
* If the set contains an invalid combination of options |
3acf8e5e2ca0
6781363: New I/O: Update socket-channel API to jsr203/nio2-b99
alanb
parents:
2
diff
changeset
|
318 |
* @throws UnsupportedOperationException |
8158 | 319 |
* If the {@code path} is associated with a provider that does not |
2057
3acf8e5e2ca0
6781363: New I/O: Update socket-channel API to jsr203/nio2-b99
alanb
parents:
2
diff
changeset
|
320 |
* support creating file channels, or an unsupported open option is |
3acf8e5e2ca0
6781363: New I/O: Update socket-channel API to jsr203/nio2-b99
alanb
parents:
2
diff
changeset
|
321 |
* specified |
3acf8e5e2ca0
6781363: New I/O: Update socket-channel API to jsr203/nio2-b99
alanb
parents:
2
diff
changeset
|
322 |
* @throws IOException |
3acf8e5e2ca0
6781363: New I/O: Update socket-channel API to jsr203/nio2-b99
alanb
parents:
2
diff
changeset
|
323 |
* If an I/O error occurs |
3acf8e5e2ca0
6781363: New I/O: Update socket-channel API to jsr203/nio2-b99
alanb
parents:
2
diff
changeset
|
324 |
* @throws SecurityException |
3acf8e5e2ca0
6781363: New I/O: Update socket-channel API to jsr203/nio2-b99
alanb
parents:
2
diff
changeset
|
325 |
* If a security manager is installed and it denies an |
3acf8e5e2ca0
6781363: New I/O: Update socket-channel API to jsr203/nio2-b99
alanb
parents:
2
diff
changeset
|
326 |
* unspecified permission required by the implementation. |
3acf8e5e2ca0
6781363: New I/O: Update socket-channel API to jsr203/nio2-b99
alanb
parents:
2
diff
changeset
|
327 |
* In the case of the default provider, the {@link |
3acf8e5e2ca0
6781363: New I/O: Update socket-channel API to jsr203/nio2-b99
alanb
parents:
2
diff
changeset
|
328 |
* SecurityManager#checkRead(String)} method is invoked to check |
3acf8e5e2ca0
6781363: New I/O: Update socket-channel API to jsr203/nio2-b99
alanb
parents:
2
diff
changeset
|
329 |
* read access if the file is opened for reading. The {@link |
3acf8e5e2ca0
6781363: New I/O: Update socket-channel API to jsr203/nio2-b99
alanb
parents:
2
diff
changeset
|
330 |
* SecurityManager#checkWrite(String)} method is invoked to check |
3acf8e5e2ca0
6781363: New I/O: Update socket-channel API to jsr203/nio2-b99
alanb
parents:
2
diff
changeset
|
331 |
* write access if the file is opened for writing |
3acf8e5e2ca0
6781363: New I/O: Update socket-channel API to jsr203/nio2-b99
alanb
parents:
2
diff
changeset
|
332 |
* |
3acf8e5e2ca0
6781363: New I/O: Update socket-channel API to jsr203/nio2-b99
alanb
parents:
2
diff
changeset
|
333 |
* @since 1.7 |
3acf8e5e2ca0
6781363: New I/O: Update socket-channel API to jsr203/nio2-b99
alanb
parents:
2
diff
changeset
|
334 |
*/ |
8158 | 335 |
public static FileChannel open(Path path, OpenOption... options) |
2057
3acf8e5e2ca0
6781363: New I/O: Update socket-channel API to jsr203/nio2-b99
alanb
parents:
2
diff
changeset
|
336 |
throws IOException |
3acf8e5e2ca0
6781363: New I/O: Update socket-channel API to jsr203/nio2-b99
alanb
parents:
2
diff
changeset
|
337 |
{ |
50701
80fe6f64d8a0
8199124: (fs) Reduce allocation for file system methods that are invoked with no open options
bpb
parents:
47478
diff
changeset
|
338 |
Set<OpenOption> set; |
80fe6f64d8a0
8199124: (fs) Reduce allocation for file system methods that are invoked with no open options
bpb
parents:
47478
diff
changeset
|
339 |
if (options.length == 0) { |
80fe6f64d8a0
8199124: (fs) Reduce allocation for file system methods that are invoked with no open options
bpb
parents:
47478
diff
changeset
|
340 |
set = Collections.emptySet(); |
80fe6f64d8a0
8199124: (fs) Reduce allocation for file system methods that are invoked with no open options
bpb
parents:
47478
diff
changeset
|
341 |
} else { |
80fe6f64d8a0
8199124: (fs) Reduce allocation for file system methods that are invoked with no open options
bpb
parents:
47478
diff
changeset
|
342 |
set = new HashSet<>(); |
80fe6f64d8a0
8199124: (fs) Reduce allocation for file system methods that are invoked with no open options
bpb
parents:
47478
diff
changeset
|
343 |
Collections.addAll(set, options); |
80fe6f64d8a0
8199124: (fs) Reduce allocation for file system methods that are invoked with no open options
bpb
parents:
47478
diff
changeset
|
344 |
} |
8158 | 345 |
return open(path, set, NO_ATTRIBUTES); |
2057
3acf8e5e2ca0
6781363: New I/O: Update socket-channel API to jsr203/nio2-b99
alanb
parents:
2
diff
changeset
|
346 |
} |
2 | 347 |
|
348 |
// -- Channel operations -- |
|
349 |
||
350 |
/** |
|
351 |
* Reads a sequence of bytes from this channel into the given buffer. |
|
352 |
* |
|
353 |
* <p> Bytes are read starting at this channel's current file position, and |
|
354 |
* then the file position is updated with the number of bytes actually |
|
355 |
* read. Otherwise this method behaves exactly as specified in the {@link |
|
356 |
* ReadableByteChannel} interface. </p> |
|
357 |
*/ |
|
358 |
public abstract int read(ByteBuffer dst) throws IOException; |
|
359 |
||
360 |
/** |
|
361 |
* Reads a sequence of bytes from this channel into a subsequence of the |
|
362 |
* given buffers. |
|
363 |
* |
|
364 |
* <p> Bytes are read starting at this channel's current file position, and |
|
365 |
* then the file position is updated with the number of bytes actually |
|
366 |
* read. Otherwise this method behaves exactly as specified in the {@link |
|
367 |
* ScatteringByteChannel} interface. </p> |
|
368 |
*/ |
|
369 |
public abstract long read(ByteBuffer[] dsts, int offset, int length) |
|
370 |
throws IOException; |
|
371 |
||
372 |
/** |
|
373 |
* Reads a sequence of bytes from this channel into the given buffers. |
|
374 |
* |
|
375 |
* <p> Bytes are read starting at this channel's current file position, and |
|
376 |
* then the file position is updated with the number of bytes actually |
|
377 |
* read. Otherwise this method behaves exactly as specified in the {@link |
|
378 |
* ScatteringByteChannel} interface. </p> |
|
379 |
*/ |
|
380 |
public final long read(ByteBuffer[] dsts) throws IOException { |
|
381 |
return read(dsts, 0, dsts.length); |
|
382 |
} |
|
383 |
||
384 |
/** |
|
385 |
* Writes a sequence of bytes to this channel from the given buffer. |
|
386 |
* |
|
387 |
* <p> Bytes are written starting at this channel's current file position |
|
388 |
* unless the channel is in append mode, in which case the position is |
|
389 |
* first advanced to the end of the file. The file is grown, if necessary, |
|
390 |
* to accommodate the written bytes, and then the file position is updated |
|
391 |
* with the number of bytes actually written. Otherwise this method |
|
392 |
* behaves exactly as specified by the {@link WritableByteChannel} |
|
393 |
* interface. </p> |
|
394 |
*/ |
|
395 |
public abstract int write(ByteBuffer src) throws IOException; |
|
396 |
||
397 |
/** |
|
398 |
* Writes a sequence of bytes to this channel from a subsequence of the |
|
399 |
* given buffers. |
|
400 |
* |
|
401 |
* <p> Bytes are written starting at this channel's current file position |
|
402 |
* unless the channel is in append mode, in which case the position is |
|
403 |
* first advanced to the end of the file. The file is grown, if necessary, |
|
404 |
* to accommodate the written bytes, and then the file position is updated |
|
405 |
* with the number of bytes actually written. Otherwise this method |
|
406 |
* behaves exactly as specified in the {@link GatheringByteChannel} |
|
407 |
* interface. </p> |
|
408 |
*/ |
|
409 |
public abstract long write(ByteBuffer[] srcs, int offset, int length) |
|
410 |
throws IOException; |
|
411 |
||
412 |
/** |
|
413 |
* Writes a sequence of bytes to this channel from the given buffers. |
|
414 |
* |
|
415 |
* <p> Bytes are written starting at this channel's current file position |
|
416 |
* unless the channel is in append mode, in which case the position is |
|
417 |
* first advanced to the end of the file. The file is grown, if necessary, |
|
418 |
* to accommodate the written bytes, and then the file position is updated |
|
419 |
* with the number of bytes actually written. Otherwise this method |
|
420 |
* behaves exactly as specified in the {@link GatheringByteChannel} |
|
421 |
* interface. </p> |
|
422 |
*/ |
|
423 |
public final long write(ByteBuffer[] srcs) throws IOException { |
|
424 |
return write(srcs, 0, srcs.length); |
|
425 |
} |
|
426 |
||
427 |
||
428 |
// -- Other operations -- |
|
429 |
||
430 |
/** |
|
18164 | 431 |
* Returns this channel's file position. |
2 | 432 |
* |
433 |
* @return This channel's file position, |
|
434 |
* a non-negative integer counting the number of bytes |
|
435 |
* from the beginning of the file to the current position |
|
436 |
* |
|
437 |
* @throws ClosedChannelException |
|
438 |
* If this channel is closed |
|
439 |
* |
|
440 |
* @throws IOException |
|
441 |
* If some other I/O error occurs |
|
442 |
*/ |
|
443 |
public abstract long position() throws IOException; |
|
444 |
||
445 |
/** |
|
446 |
* Sets this channel's file position. |
|
447 |
* |
|
448 |
* <p> Setting the position to a value that is greater than the file's |
|
449 |
* current size is legal but does not change the size of the file. A later |
|
450 |
* attempt to read bytes at such a position will immediately return an |
|
451 |
* end-of-file indication. A later attempt to write bytes at such a |
|
452 |
* position will cause the file to be grown to accommodate the new bytes; |
|
453 |
* the values of any bytes between the previous end-of-file and the |
|
454 |
* newly-written bytes are unspecified. </p> |
|
455 |
* |
|
456 |
* @param newPosition |
|
457 |
* The new position, a non-negative integer counting |
|
458 |
* the number of bytes from the beginning of the file |
|
459 |
* |
|
460 |
* @return This file channel |
|
461 |
* |
|
462 |
* @throws ClosedChannelException |
|
463 |
* If this channel is closed |
|
464 |
* |
|
465 |
* @throws IllegalArgumentException |
|
466 |
* If the new position is negative |
|
467 |
* |
|
468 |
* @throws IOException |
|
469 |
* If some other I/O error occurs |
|
470 |
*/ |
|
471 |
public abstract FileChannel position(long newPosition) throws IOException; |
|
472 |
||
473 |
/** |
|
18164 | 474 |
* Returns the current size of this channel's file. |
2 | 475 |
* |
476 |
* @return The current size of this channel's file, |
|
477 |
* measured in bytes |
|
478 |
* |
|
479 |
* @throws ClosedChannelException |
|
480 |
* If this channel is closed |
|
481 |
* |
|
482 |
* @throws IOException |
|
483 |
* If some other I/O error occurs |
|
484 |
*/ |
|
485 |
public abstract long size() throws IOException; |
|
486 |
||
487 |
/** |
|
488 |
* Truncates this channel's file to the given size. |
|
489 |
* |
|
490 |
* <p> If the given size is less than the file's current size then the file |
|
491 |
* is truncated, discarding any bytes beyond the new end of the file. If |
|
492 |
* the given size is greater than or equal to the file's current size then |
|
493 |
* the file is not modified. In either case, if this channel's file |
|
494 |
* position is greater than the given size then it is set to that size. |
|
495 |
* </p> |
|
496 |
* |
|
497 |
* @param size |
|
498 |
* The new size, a non-negative byte count |
|
499 |
* |
|
500 |
* @return This file channel |
|
501 |
* |
|
502 |
* @throws NonWritableChannelException |
|
503 |
* If this channel was not opened for writing |
|
504 |
* |
|
505 |
* @throws ClosedChannelException |
|
506 |
* If this channel is closed |
|
507 |
* |
|
508 |
* @throws IllegalArgumentException |
|
509 |
* If the new size is negative |
|
510 |
* |
|
511 |
* @throws IOException |
|
512 |
* If some other I/O error occurs |
|
513 |
*/ |
|
514 |
public abstract FileChannel truncate(long size) throws IOException; |
|
515 |
||
516 |
/** |
|
517 |
* Forces any updates to this channel's file to be written to the storage |
|
518 |
* device that contains it. |
|
519 |
* |
|
520 |
* <p> If this channel's file resides on a local storage device then when |
|
521 |
* this method returns it is guaranteed that all changes made to the file |
|
522 |
* since this channel was created, or since this method was last invoked, |
|
523 |
* will have been written to that device. This is useful for ensuring that |
|
524 |
* critical information is not lost in the event of a system crash. |
|
525 |
* |
|
526 |
* <p> If the file does not reside on a local device then no such guarantee |
|
527 |
* is made. |
|
528 |
* |
|
32143
394ab6a6658d
8133459: replace <tt> tags (obsolete in html5) in java.nio docs
avstepan
parents:
29986
diff
changeset
|
529 |
* <p> The {@code metaData} parameter can be used to limit the number of |
2 | 530 |
* I/O operations that this method is required to perform. Passing |
32143
394ab6a6658d
8133459: replace <tt> tags (obsolete in html5) in java.nio docs
avstepan
parents:
29986
diff
changeset
|
531 |
* {@code false} for this parameter indicates that only updates to the |
394ab6a6658d
8133459: replace <tt> tags (obsolete in html5) in java.nio docs
avstepan
parents:
29986
diff
changeset
|
532 |
* file's content need be written to storage; passing {@code true} |
2 | 533 |
* indicates that updates to both the file's content and metadata must be |
534 |
* written, which generally requires at least one more I/O operation. |
|
535 |
* Whether this parameter actually has any effect is dependent upon the |
|
536 |
* underlying operating system and is therefore unspecified. |
|
537 |
* |
|
538 |
* <p> Invoking this method may cause an I/O operation to occur even if the |
|
539 |
* channel was only opened for reading. Some operating systems, for |
|
540 |
* example, maintain a last-access time as part of a file's metadata, and |
|
541 |
* this time is updated whenever the file is read. Whether or not this is |
|
542 |
* actually done is system-dependent and is therefore unspecified. |
|
543 |
* |
|
544 |
* <p> This method is only guaranteed to force changes that were made to |
|
545 |
* this channel's file via the methods defined in this class. It may or |
|
546 |
* may not force changes that were made by modifying the content of a |
|
2057
3acf8e5e2ca0
6781363: New I/O: Update socket-channel API to jsr203/nio2-b99
alanb
parents:
2
diff
changeset
|
547 |
* {@link MappedByteBuffer <i>mapped byte buffer</i>} obtained by |
2 | 548 |
* invoking the {@link #map map} method. Invoking the {@link |
549 |
* MappedByteBuffer#force force} method of the mapped byte buffer will |
|
550 |
* force changes made to the buffer's content to be written. </p> |
|
551 |
* |
|
552 |
* @param metaData |
|
32143
394ab6a6658d
8133459: replace <tt> tags (obsolete in html5) in java.nio docs
avstepan
parents:
29986
diff
changeset
|
553 |
* If {@code true} then this method is required to force changes |
2 | 554 |
* to both the file's content and metadata to be written to |
555 |
* storage; otherwise, it need only force content changes to be |
|
556 |
* written |
|
557 |
* |
|
558 |
* @throws ClosedChannelException |
|
559 |
* If this channel is closed |
|
560 |
* |
|
561 |
* @throws IOException |
|
562 |
* If some other I/O error occurs |
|
563 |
*/ |
|
564 |
public abstract void force(boolean metaData) throws IOException; |
|
565 |
||
566 |
/** |
|
567 |
* Transfers bytes from this channel's file to the given writable byte |
|
568 |
* channel. |
|
569 |
* |
|
32143
394ab6a6658d
8133459: replace <tt> tags (obsolete in html5) in java.nio docs
avstepan
parents:
29986
diff
changeset
|
570 |
* <p> An attempt is made to read up to {@code count} bytes starting at |
394ab6a6658d
8133459: replace <tt> tags (obsolete in html5) in java.nio docs
avstepan
parents:
29986
diff
changeset
|
571 |
* the given {@code position} in this channel's file and write them to the |
2 | 572 |
* target channel. An invocation of this method may or may not transfer |
573 |
* all of the requested bytes; whether or not it does so depends upon the |
|
574 |
* natures and states of the channels. Fewer than the requested number of |
|
575 |
* bytes are transferred if this channel's file contains fewer than |
|
32143
394ab6a6658d
8133459: replace <tt> tags (obsolete in html5) in java.nio docs
avstepan
parents:
29986
diff
changeset
|
576 |
* {@code count} bytes starting at the given {@code position}, or if the |
394ab6a6658d
8133459: replace <tt> tags (obsolete in html5) in java.nio docs
avstepan
parents:
29986
diff
changeset
|
577 |
* target channel is non-blocking and it has fewer than {@code count} |
2 | 578 |
* bytes free in its output buffer. |
579 |
* |
|
580 |
* <p> This method does not modify this channel's position. If the given |
|
581 |
* position is greater than the file's current size then no bytes are |
|
582 |
* transferred. If the target channel has a position then bytes are |
|
583 |
* written starting at that position and then the position is incremented |
|
584 |
* by the number of bytes written. |
|
585 |
* |
|
586 |
* <p> This method is potentially much more efficient than a simple loop |
|
587 |
* that reads from this channel and writes to the target channel. Many |
|
588 |
* operating systems can transfer bytes directly from the filesystem cache |
|
589 |
* to the target channel without actually copying them. </p> |
|
590 |
* |
|
591 |
* @param position |
|
592 |
* The position within the file at which the transfer is to begin; |
|
593 |
* must be non-negative |
|
594 |
* |
|
595 |
* @param count |
|
596 |
* The maximum number of bytes to be transferred; must be |
|
597 |
* non-negative |
|
598 |
* |
|
599 |
* @param target |
|
600 |
* The target channel |
|
601 |
* |
|
602 |
* @return The number of bytes, possibly zero, |
|
603 |
* that were actually transferred |
|
604 |
* |
|
605 |
* @throws IllegalArgumentException |
|
606 |
* If the preconditions on the parameters do not hold |
|
607 |
* |
|
608 |
* @throws NonReadableChannelException |
|
609 |
* If this channel was not opened for reading |
|
610 |
* |
|
611 |
* @throws NonWritableChannelException |
|
612 |
* If the target channel was not opened for writing |
|
613 |
* |
|
614 |
* @throws ClosedChannelException |
|
615 |
* If either this channel or the target channel is closed |
|
616 |
* |
|
617 |
* @throws AsynchronousCloseException |
|
618 |
* If another thread closes either channel |
|
619 |
* while the transfer is in progress |
|
620 |
* |
|
621 |
* @throws ClosedByInterruptException |
|
622 |
* If another thread interrupts the current thread while the |
|
623 |
* transfer is in progress, thereby closing both channels and |
|
624 |
* setting the current thread's interrupt status |
|
625 |
* |
|
626 |
* @throws IOException |
|
627 |
* If some other I/O error occurs |
|
628 |
*/ |
|
629 |
public abstract long transferTo(long position, long count, |
|
630 |
WritableByteChannel target) |
|
631 |
throws IOException; |
|
632 |
||
633 |
/** |
|
634 |
* Transfers bytes into this channel's file from the given readable byte |
|
635 |
* channel. |
|
636 |
* |
|
32143
394ab6a6658d
8133459: replace <tt> tags (obsolete in html5) in java.nio docs
avstepan
parents:
29986
diff
changeset
|
637 |
* <p> An attempt is made to read up to {@code count} bytes from the |
2 | 638 |
* source channel and write them to this channel's file starting at the |
32143
394ab6a6658d
8133459: replace <tt> tags (obsolete in html5) in java.nio docs
avstepan
parents:
29986
diff
changeset
|
639 |
* given {@code position}. An invocation of this method may or may not |
2 | 640 |
* transfer all of the requested bytes; whether or not it does so depends |
641 |
* upon the natures and states of the channels. Fewer than the requested |
|
642 |
* number of bytes will be transferred if the source channel has fewer than |
|
32143
394ab6a6658d
8133459: replace <tt> tags (obsolete in html5) in java.nio docs
avstepan
parents:
29986
diff
changeset
|
643 |
* {@code count} bytes remaining, or if the source channel is non-blocking |
394ab6a6658d
8133459: replace <tt> tags (obsolete in html5) in java.nio docs
avstepan
parents:
29986
diff
changeset
|
644 |
* and has fewer than {@code count} bytes immediately available in its |
2 | 645 |
* input buffer. |
646 |
* |
|
647 |
* <p> This method does not modify this channel's position. If the given |
|
648 |
* position is greater than the file's current size then no bytes are |
|
649 |
* transferred. If the source channel has a position then bytes are read |
|
650 |
* starting at that position and then the position is incremented by the |
|
651 |
* number of bytes read. |
|
652 |
* |
|
653 |
* <p> This method is potentially much more efficient than a simple loop |
|
654 |
* that reads from the source channel and writes to this channel. Many |
|
655 |
* operating systems can transfer bytes directly from the source channel |
|
656 |
* into the filesystem cache without actually copying them. </p> |
|
657 |
* |
|
658 |
* @param src |
|
659 |
* The source channel |
|
660 |
* |
|
661 |
* @param position |
|
662 |
* The position within the file at which the transfer is to begin; |
|
663 |
* must be non-negative |
|
664 |
* |
|
665 |
* @param count |
|
666 |
* The maximum number of bytes to be transferred; must be |
|
667 |
* non-negative |
|
668 |
* |
|
669 |
* @return The number of bytes, possibly zero, |
|
670 |
* that were actually transferred |
|
671 |
* |
|
672 |
* @throws IllegalArgumentException |
|
673 |
* If the preconditions on the parameters do not hold |
|
674 |
* |
|
675 |
* @throws NonReadableChannelException |
|
676 |
* If the source channel was not opened for reading |
|
677 |
* |
|
678 |
* @throws NonWritableChannelException |
|
679 |
* If this channel was not opened for writing |
|
680 |
* |
|
681 |
* @throws ClosedChannelException |
|
682 |
* If either this channel or the source channel is closed |
|
683 |
* |
|
684 |
* @throws AsynchronousCloseException |
|
685 |
* If another thread closes either channel |
|
686 |
* while the transfer is in progress |
|
687 |
* |
|
688 |
* @throws ClosedByInterruptException |
|
689 |
* If another thread interrupts the current thread while the |
|
690 |
* transfer is in progress, thereby closing both channels and |
|
691 |
* setting the current thread's interrupt status |
|
692 |
* |
|
693 |
* @throws IOException |
|
694 |
* If some other I/O error occurs |
|
695 |
*/ |
|
696 |
public abstract long transferFrom(ReadableByteChannel src, |
|
697 |
long position, long count) |
|
698 |
throws IOException; |
|
699 |
||
700 |
/** |
|
701 |
* Reads a sequence of bytes from this channel into the given buffer, |
|
702 |
* starting at the given file position. |
|
703 |
* |
|
704 |
* <p> This method works in the same manner as the {@link |
|
705 |
* #read(ByteBuffer)} method, except that bytes are read starting at the |
|
706 |
* given file position rather than at the channel's current position. This |
|
707 |
* method does not modify this channel's position. If the given position |
|
708 |
* is greater than the file's current size then no bytes are read. </p> |
|
709 |
* |
|
710 |
* @param dst |
|
711 |
* The buffer into which bytes are to be transferred |
|
712 |
* |
|
713 |
* @param position |
|
714 |
* The file position at which the transfer is to begin; |
|
715 |
* must be non-negative |
|
716 |
* |
|
32143
394ab6a6658d
8133459: replace <tt> tags (obsolete in html5) in java.nio docs
avstepan
parents:
29986
diff
changeset
|
717 |
* @return The number of bytes read, possibly zero, or {@code -1} if the |
2 | 718 |
* given position is greater than or equal to the file's current |
719 |
* size |
|
720 |
* |
|
721 |
* @throws IllegalArgumentException |
|
59227
46084917fde7
8164993: (ch) ReadableByteChannel should note a possible IllegalArgumentException
bpb
parents:
54532
diff
changeset
|
722 |
* If the position is negative or the buffer is read-only |
2 | 723 |
* |
724 |
* @throws NonReadableChannelException |
|
725 |
* If this channel was not opened for reading |
|
726 |
* |
|
727 |
* @throws ClosedChannelException |
|
728 |
* If this channel is closed |
|
729 |
* |
|
730 |
* @throws AsynchronousCloseException |
|
731 |
* If another thread closes this channel |
|
732 |
* while the read operation is in progress |
|
733 |
* |
|
734 |
* @throws ClosedByInterruptException |
|
735 |
* If another thread interrupts the current thread |
|
736 |
* while the read operation is in progress, thereby |
|
737 |
* closing the channel and setting the current thread's |
|
738 |
* interrupt status |
|
739 |
* |
|
740 |
* @throws IOException |
|
741 |
* If some other I/O error occurs |
|
742 |
*/ |
|
743 |
public abstract int read(ByteBuffer dst, long position) throws IOException; |
|
744 |
||
745 |
/** |
|
746 |
* Writes a sequence of bytes to this channel from the given buffer, |
|
747 |
* starting at the given file position. |
|
748 |
* |
|
749 |
* <p> This method works in the same manner as the {@link |
|
750 |
* #write(ByteBuffer)} method, except that bytes are written starting at |
|
751 |
* the given file position rather than at the channel's current position. |
|
752 |
* This method does not modify this channel's position. If the given |
|
753 |
* position is greater than the file's current size then the file will be |
|
754 |
* grown to accommodate the new bytes; the values of any bytes between the |
|
755 |
* previous end-of-file and the newly-written bytes are unspecified. </p> |
|
756 |
* |
|
757 |
* @param src |
|
758 |
* The buffer from which bytes are to be transferred |
|
759 |
* |
|
760 |
* @param position |
|
761 |
* The file position at which the transfer is to begin; |
|
762 |
* must be non-negative |
|
763 |
* |
|
764 |
* @return The number of bytes written, possibly zero |
|
765 |
* |
|
766 |
* @throws IllegalArgumentException |
|
767 |
* If the position is negative |
|
768 |
* |
|
769 |
* @throws NonWritableChannelException |
|
770 |
* If this channel was not opened for writing |
|
771 |
* |
|
772 |
* @throws ClosedChannelException |
|
773 |
* If this channel is closed |
|
774 |
* |
|
775 |
* @throws AsynchronousCloseException |
|
776 |
* If another thread closes this channel |
|
777 |
* while the write operation is in progress |
|
778 |
* |
|
779 |
* @throws ClosedByInterruptException |
|
780 |
* If another thread interrupts the current thread |
|
781 |
* while the write operation is in progress, thereby |
|
782 |
* closing the channel and setting the current thread's |
|
783 |
* interrupt status |
|
784 |
* |
|
785 |
* @throws IOException |
|
786 |
* If some other I/O error occurs |
|
787 |
*/ |
|
788 |
public abstract int write(ByteBuffer src, long position) throws IOException; |
|
789 |
||
790 |
||
791 |
// -- Memory-mapped buffers -- |
|
792 |
||
793 |
/** |
|
54532 | 794 |
* A file-mapping mode. |
2 | 795 |
* |
796 |
* @since 1.4 |
|
797 |
* |
|
798 |
* @see java.nio.channels.FileChannel#map |
|
799 |
*/ |
|
800 |
public static class MapMode { |
|
801 |
||
802 |
/** |
|
803 |
* Mode for a read-only mapping. |
|
804 |
*/ |
|
805 |
public static final MapMode READ_ONLY |
|
806 |
= new MapMode("READ_ONLY"); |
|
807 |
||
808 |
/** |
|
809 |
* Mode for a read/write mapping. |
|
810 |
*/ |
|
811 |
public static final MapMode READ_WRITE |
|
812 |
= new MapMode("READ_WRITE"); |
|
813 |
||
814 |
/** |
|
815 |
* Mode for a private (copy-on-write) mapping. |
|
816 |
*/ |
|
817 |
public static final MapMode PRIVATE |
|
818 |
= new MapMode("PRIVATE"); |
|
819 |
||
820 |
private final String name; |
|
821 |
||
54532 | 822 |
/** |
823 |
* Constructs an instance of this class. This constructor may be used |
|
824 |
* by code in java.base to create file mapping modes beyond the file |
|
825 |
* mapping modes defined here. |
|
826 |
* @param name the name of the map mode |
|
827 |
*/ |
|
2 | 828 |
private MapMode(String name) { |
829 |
this.name = name; |
|
830 |
} |
|
831 |
||
832 |
/** |
|
833 |
* Returns a string describing this file-mapping mode. |
|
834 |
* |
|
835 |
* @return A descriptive string |
|
836 |
*/ |
|
837 |
public String toString() { |
|
838 |
return name; |
|
839 |
} |
|
840 |
||
841 |
} |
|
842 |
||
843 |
/** |
|
844 |
* Maps a region of this channel's file directly into memory. |
|
845 |
* |
|
54532 | 846 |
* <p> The {@code mode} parameter specifies how the region of the file is |
847 |
* mapped and may be one of the following modes: |
|
2 | 848 |
* |
18574
4aeaeb541678
8019380: doclint warnings in java.nio, java.nio.file.**, java.nio.channels.**
alanb
parents:
18164
diff
changeset
|
849 |
* <ul> |
2 | 850 |
* |
851 |
* <li><p> <i>Read-only:</i> Any attempt to modify the resulting buffer |
|
852 |
* will cause a {@link java.nio.ReadOnlyBufferException} to be thrown. |
|
853 |
* ({@link MapMode#READ_ONLY MapMode.READ_ONLY}) </p></li> |
|
854 |
* |
|
855 |
* <li><p> <i>Read/write:</i> Changes made to the resulting buffer will |
|
856 |
* eventually be propagated to the file; they may or may not be made |
|
857 |
* visible to other programs that have mapped the same file. ({@link |
|
858 |
* MapMode#READ_WRITE MapMode.READ_WRITE}) </p></li> |
|
859 |
* |
|
860 |
* <li><p> <i>Private:</i> Changes made to the resulting buffer will not |
|
861 |
* be propagated to the file and will not be visible to other programs |
|
862 |
* that have mapped the same file; instead, they will cause private |
|
863 |
* copies of the modified portions of the buffer to be created. ({@link |
|
864 |
* MapMode#PRIVATE MapMode.PRIVATE}) </p></li> |
|
865 |
* |
|
866 |
* </ul> |
|
867 |
* |
|
54532 | 868 |
* <p> An implementation may support additional map modes. |
869 |
* |
|
2 | 870 |
* <p> For a read-only mapping, this channel must have been opened for |
871 |
* reading; for a read/write or private mapping, this channel must have |
|
872 |
* been opened for both reading and writing. |
|
873 |
* |
|
2057
3acf8e5e2ca0
6781363: New I/O: Update socket-channel API to jsr203/nio2-b99
alanb
parents:
2
diff
changeset
|
874 |
* <p> The {@link MappedByteBuffer <i>mapped byte buffer</i>} |
2 | 875 |
* returned by this method will have a position of zero and a limit and |
32143
394ab6a6658d
8133459: replace <tt> tags (obsolete in html5) in java.nio docs
avstepan
parents:
29986
diff
changeset
|
876 |
* capacity of {@code size}; its mark will be undefined. The buffer and |
2 | 877 |
* the mapping that it represents will remain valid until the buffer itself |
878 |
* is garbage-collected. |
|
879 |
* |
|
880 |
* <p> A mapping, once established, is not dependent upon the file channel |
|
881 |
* that was used to create it. Closing the channel, in particular, has no |
|
882 |
* effect upon the validity of the mapping. |
|
883 |
* |
|
884 |
* <p> Many of the details of memory-mapped files are inherently dependent |
|
885 |
* upon the underlying operating system and are therefore unspecified. The |
|
886 |
* behavior of this method when the requested region is not completely |
|
887 |
* contained within this channel's file is unspecified. Whether changes |
|
888 |
* made to the content or size of the underlying file, by this program or |
|
889 |
* another, are propagated to the buffer is unspecified. The rate at which |
|
890 |
* changes to the buffer are propagated to the file is unspecified. |
|
891 |
* |
|
892 |
* <p> For most operating systems, mapping a file into memory is more |
|
893 |
* expensive than reading or writing a few tens of kilobytes of data via |
|
894 |
* the usual {@link #read read} and {@link #write write} methods. From the |
|
895 |
* standpoint of performance it is generally only worth mapping relatively |
|
896 |
* large files into memory. </p> |
|
897 |
* |
|
898 |
* @param mode |
|
899 |
* One of the constants {@link MapMode#READ_ONLY READ_ONLY}, {@link |
|
900 |
* MapMode#READ_WRITE READ_WRITE}, or {@link MapMode#PRIVATE |
|
901 |
* PRIVATE} defined in the {@link MapMode} class, according to |
|
902 |
* whether the file is to be mapped read-only, read/write, or |
|
54532 | 903 |
* privately (copy-on-write), respectively, or an implementation |
904 |
* specific map mode |
|
2 | 905 |
* |
906 |
* @param position |
|
907 |
* The position within the file at which the mapped region |
|
908 |
* is to start; must be non-negative |
|
909 |
* |
|
910 |
* @param size |
|
911 |
* The size of the region to be mapped; must be non-negative and |
|
912 |
* no greater than {@link java.lang.Integer#MAX_VALUE} |
|
913 |
* |
|
2057
3acf8e5e2ca0
6781363: New I/O: Update socket-channel API to jsr203/nio2-b99
alanb
parents:
2
diff
changeset
|
914 |
* @return The mapped byte buffer |
3acf8e5e2ca0
6781363: New I/O: Update socket-channel API to jsr203/nio2-b99
alanb
parents:
2
diff
changeset
|
915 |
* |
2 | 916 |
* @throws NonReadableChannelException |
54532 | 917 |
* If the {@code mode} is {@link MapMode#READ_ONLY READ_ONLY} or |
918 |
* an implementation specific map mode requiring read access |
|
919 |
* but this channel was not opened for reading |
|
2 | 920 |
* |
921 |
* @throws NonWritableChannelException |
|
54532 | 922 |
* If the {@code mode} is {@link MapMode#READ_WRITE READ_WRITE}. |
923 |
* {@link MapMode#PRIVATE PRIVATE} or an implementation specific |
|
924 |
* map mode requiring write access but this channel was not |
|
925 |
* opened for both reading and writing |
|
2 | 926 |
* |
927 |
* @throws IllegalArgumentException |
|
928 |
* If the preconditions on the parameters do not hold |
|
929 |
* |
|
54532 | 930 |
* @throws UnsupportedOperationException |
931 |
* If an unsupported map mode is specified |
|
932 |
* |
|
2 | 933 |
* @throws IOException |
934 |
* If some other I/O error occurs |
|
935 |
* |
|
936 |
* @see java.nio.channels.FileChannel.MapMode |
|
937 |
* @see java.nio.MappedByteBuffer |
|
938 |
*/ |
|
54532 | 939 |
public abstract MappedByteBuffer map(MapMode mode, long position, long size) |
2 | 940 |
throws IOException; |
941 |
||
942 |
||
943 |
// -- Locks -- |
|
944 |
||
945 |
/** |
|
946 |
* Acquires a lock on the given region of this channel's file. |
|
947 |
* |
|
948 |
* <p> An invocation of this method will block until the region can be |
|
949 |
* locked, this channel is closed, or the invoking thread is interrupted, |
|
950 |
* whichever comes first. |
|
951 |
* |
|
952 |
* <p> If this channel is closed by another thread during an invocation of |
|
953 |
* this method then an {@link AsynchronousCloseException} will be thrown. |
|
954 |
* |
|
955 |
* <p> If the invoking thread is interrupted while waiting to acquire the |
|
956 |
* lock then its interrupt status will be set and a {@link |
|
957 |
* FileLockInterruptionException} will be thrown. If the invoker's |
|
958 |
* interrupt status is set when this method is invoked then that exception |
|
959 |
* will be thrown immediately; the thread's interrupt status will not be |
|
960 |
* changed. |
|
961 |
* |
|
32143
394ab6a6658d
8133459: replace <tt> tags (obsolete in html5) in java.nio docs
avstepan
parents:
29986
diff
changeset
|
962 |
* <p> The region specified by the {@code position} and {@code size} |
2 | 963 |
* parameters need not be contained within, or even overlap, the actual |
964 |
* underlying file. Lock regions are fixed in size; if a locked region |
|
965 |
* initially contains the end of the file and the file grows beyond the |
|
966 |
* region then the new portion of the file will not be covered by the lock. |
|
967 |
* If a file is expected to grow in size and a lock on the entire file is |
|
968 |
* required then a region starting at zero, and no smaller than the |
|
969 |
* expected maximum size of the file, should be locked. The zero-argument |
|
970 |
* {@link #lock()} method simply locks a region of size {@link |
|
971 |
* Long#MAX_VALUE}. |
|
972 |
* |
|
973 |
* <p> Some operating systems do not support shared locks, in which case a |
|
974 |
* request for a shared lock is automatically converted into a request for |
|
975 |
* an exclusive lock. Whether the newly-acquired lock is shared or |
|
976 |
* exclusive may be tested by invoking the resulting lock object's {@link |
|
977 |
* FileLock#isShared() isShared} method. |
|
978 |
* |
|
979 |
* <p> File locks are held on behalf of the entire Java virtual machine. |
|
980 |
* They are not suitable for controlling access to a file by multiple |
|
981 |
* threads within the same virtual machine. </p> |
|
982 |
* |
|
983 |
* @param position |
|
984 |
* The position at which the locked region is to start; must be |
|
985 |
* non-negative |
|
986 |
* |
|
987 |
* @param size |
|
988 |
* The size of the locked region; must be non-negative, and the sum |
|
32143
394ab6a6658d
8133459: replace <tt> tags (obsolete in html5) in java.nio docs
avstepan
parents:
29986
diff
changeset
|
989 |
* {@code position} + {@code size} must be non-negative |
2 | 990 |
* |
991 |
* @param shared |
|
32143
394ab6a6658d
8133459: replace <tt> tags (obsolete in html5) in java.nio docs
avstepan
parents:
29986
diff
changeset
|
992 |
* {@code true} to request a shared lock, in which case this |
2 | 993 |
* channel must be open for reading (and possibly writing); |
32143
394ab6a6658d
8133459: replace <tt> tags (obsolete in html5) in java.nio docs
avstepan
parents:
29986
diff
changeset
|
994 |
* {@code false} to request an exclusive lock, in which case this |
2 | 995 |
* channel must be open for writing (and possibly reading) |
996 |
* |
|
997 |
* @return A lock object representing the newly-acquired lock |
|
998 |
* |
|
999 |
* @throws IllegalArgumentException |
|
1000 |
* If the preconditions on the parameters do not hold |
|
1001 |
* |
|
1002 |
* @throws ClosedChannelException |
|
1003 |
* If this channel is closed |
|
1004 |
* |
|
1005 |
* @throws AsynchronousCloseException |
|
1006 |
* If another thread closes this channel while the invoking |
|
1007 |
* thread is blocked in this method |
|
1008 |
* |
|
1009 |
* @throws FileLockInterruptionException |
|
1010 |
* If the invoking thread is interrupted while blocked in this |
|
1011 |
* method |
|
1012 |
* |
|
1013 |
* @throws OverlappingFileLockException |
|
1014 |
* If a lock that overlaps the requested region is already held by |
|
1015 |
* this Java virtual machine, or if another thread is already |
|
1016 |
* blocked in this method and is attempting to lock an overlapping |
|
1017 |
* region |
|
1018 |
* |
|
1019 |
* @throws NonReadableChannelException |
|
32143
394ab6a6658d
8133459: replace <tt> tags (obsolete in html5) in java.nio docs
avstepan
parents:
29986
diff
changeset
|
1020 |
* If {@code shared} is {@code true} this channel was not |
2 | 1021 |
* opened for reading |
1022 |
* |
|
1023 |
* @throws NonWritableChannelException |
|
32143
394ab6a6658d
8133459: replace <tt> tags (obsolete in html5) in java.nio docs
avstepan
parents:
29986
diff
changeset
|
1024 |
* If {@code shared} is {@code false} but this channel was not |
2 | 1025 |
* opened for writing |
1026 |
* |
|
1027 |
* @throws IOException |
|
1028 |
* If some other I/O error occurs |
|
1029 |
* |
|
1030 |
* @see #lock() |
|
1031 |
* @see #tryLock() |
|
1032 |
* @see #tryLock(long,long,boolean) |
|
1033 |
*/ |
|
1034 |
public abstract FileLock lock(long position, long size, boolean shared) |
|
1035 |
throws IOException; |
|
1036 |
||
1037 |
/** |
|
1038 |
* Acquires an exclusive lock on this channel's file. |
|
1039 |
* |
|
32143
394ab6a6658d
8133459: replace <tt> tags (obsolete in html5) in java.nio docs
avstepan
parents:
29986
diff
changeset
|
1040 |
* <p> An invocation of this method of the form {@code fc.lock()} behaves |
2 | 1041 |
* in exactly the same way as the invocation |
1042 |
* |
|
1043 |
* <pre> |
|
1044 |
* fc.{@link #lock(long,long,boolean) lock}(0L, Long.MAX_VALUE, false) </pre> |
|
1045 |
* |
|
1046 |
* @return A lock object representing the newly-acquired lock |
|
1047 |
* |
|
1048 |
* @throws ClosedChannelException |
|
1049 |
* If this channel is closed |
|
1050 |
* |
|
1051 |
* @throws AsynchronousCloseException |
|
1052 |
* If another thread closes this channel while the invoking |
|
1053 |
* thread is blocked in this method |
|
1054 |
* |
|
1055 |
* @throws FileLockInterruptionException |
|
1056 |
* If the invoking thread is interrupted while blocked in this |
|
1057 |
* method |
|
1058 |
* |
|
1059 |
* @throws OverlappingFileLockException |
|
1060 |
* If a lock that overlaps the requested region is already held by |
|
1061 |
* this Java virtual machine, or if another thread is already |
|
1062 |
* blocked in this method and is attempting to lock an overlapping |
|
1063 |
* region of the same file |
|
1064 |
* |
|
1065 |
* @throws NonWritableChannelException |
|
1066 |
* If this channel was not opened for writing |
|
1067 |
* |
|
1068 |
* @throws IOException |
|
1069 |
* If some other I/O error occurs |
|
1070 |
* |
|
1071 |
* @see #lock(long,long,boolean) |
|
1072 |
* @see #tryLock() |
|
1073 |
* @see #tryLock(long,long,boolean) |
|
1074 |
*/ |
|
1075 |
public final FileLock lock() throws IOException { |
|
1076 |
return lock(0L, Long.MAX_VALUE, false); |
|
1077 |
} |
|
1078 |
||
1079 |
/** |
|
1080 |
* Attempts to acquire a lock on the given region of this channel's file. |
|
1081 |
* |
|
1082 |
* <p> This method does not block. An invocation always returns |
|
1083 |
* immediately, either having acquired a lock on the requested region or |
|
1084 |
* having failed to do so. If it fails to acquire a lock because an |
|
1085 |
* overlapping lock is held by another program then it returns |
|
32143
394ab6a6658d
8133459: replace <tt> tags (obsolete in html5) in java.nio docs
avstepan
parents:
29986
diff
changeset
|
1086 |
* {@code null}. If it fails to acquire a lock for any other reason then |
2 | 1087 |
* an appropriate exception is thrown. |
1088 |
* |
|
32143
394ab6a6658d
8133459: replace <tt> tags (obsolete in html5) in java.nio docs
avstepan
parents:
29986
diff
changeset
|
1089 |
* <p> The region specified by the {@code position} and {@code size} |
2 | 1090 |
* parameters need not be contained within, or even overlap, the actual |
1091 |
* underlying file. Lock regions are fixed in size; if a locked region |
|
1092 |
* initially contains the end of the file and the file grows beyond the |
|
1093 |
* region then the new portion of the file will not be covered by the lock. |
|
1094 |
* If a file is expected to grow in size and a lock on the entire file is |
|
1095 |
* required then a region starting at zero, and no smaller than the |
|
1096 |
* expected maximum size of the file, should be locked. The zero-argument |
|
1097 |
* {@link #tryLock()} method simply locks a region of size {@link |
|
1098 |
* Long#MAX_VALUE}. |
|
1099 |
* |
|
1100 |
* <p> Some operating systems do not support shared locks, in which case a |
|
1101 |
* request for a shared lock is automatically converted into a request for |
|
1102 |
* an exclusive lock. Whether the newly-acquired lock is shared or |
|
1103 |
* exclusive may be tested by invoking the resulting lock object's {@link |
|
1104 |
* FileLock#isShared() isShared} method. |
|
1105 |
* |
|
1106 |
* <p> File locks are held on behalf of the entire Java virtual machine. |
|
1107 |
* They are not suitable for controlling access to a file by multiple |
|
1108 |
* threads within the same virtual machine. </p> |
|
1109 |
* |
|
1110 |
* @param position |
|
1111 |
* The position at which the locked region is to start; must be |
|
1112 |
* non-negative |
|
1113 |
* |
|
1114 |
* @param size |
|
1115 |
* The size of the locked region; must be non-negative, and the sum |
|
32143
394ab6a6658d
8133459: replace <tt> tags (obsolete in html5) in java.nio docs
avstepan
parents:
29986
diff
changeset
|
1116 |
* {@code position} + {@code size} must be non-negative |
2 | 1117 |
* |
1118 |
* @param shared |
|
32143
394ab6a6658d
8133459: replace <tt> tags (obsolete in html5) in java.nio docs
avstepan
parents:
29986
diff
changeset
|
1119 |
* {@code true} to request a shared lock, |
394ab6a6658d
8133459: replace <tt> tags (obsolete in html5) in java.nio docs
avstepan
parents:
29986
diff
changeset
|
1120 |
* {@code false} to request an exclusive lock |
2 | 1121 |
* |
1122 |
* @return A lock object representing the newly-acquired lock, |
|
32143
394ab6a6658d
8133459: replace <tt> tags (obsolete in html5) in java.nio docs
avstepan
parents:
29986
diff
changeset
|
1123 |
* or {@code null} if the lock could not be acquired |
2 | 1124 |
* because another program holds an overlapping lock |
1125 |
* |
|
1126 |
* @throws IllegalArgumentException |
|
1127 |
* If the preconditions on the parameters do not hold |
|
1128 |
* |
|
1129 |
* @throws ClosedChannelException |
|
1130 |
* If this channel is closed |
|
1131 |
* |
|
1132 |
* @throws OverlappingFileLockException |
|
1133 |
* If a lock that overlaps the requested region is already held by |
|
1134 |
* this Java virtual machine, or if another thread is already |
|
1135 |
* blocked in this method and is attempting to lock an overlapping |
|
1136 |
* region of the same file |
|
1137 |
* |
|
1138 |
* @throws IOException |
|
1139 |
* If some other I/O error occurs |
|
1140 |
* |
|
1141 |
* @see #lock() |
|
1142 |
* @see #lock(long,long,boolean) |
|
1143 |
* @see #tryLock() |
|
1144 |
*/ |
|
1145 |
public abstract FileLock tryLock(long position, long size, boolean shared) |
|
1146 |
throws IOException; |
|
1147 |
||
1148 |
/** |
|
1149 |
* Attempts to acquire an exclusive lock on this channel's file. |
|
1150 |
* |
|
32143
394ab6a6658d
8133459: replace <tt> tags (obsolete in html5) in java.nio docs
avstepan
parents:
29986
diff
changeset
|
1151 |
* <p> An invocation of this method of the form {@code fc.tryLock()} |
2 | 1152 |
* behaves in exactly the same way as the invocation |
1153 |
* |
|
1154 |
* <pre> |
|
1155 |
* fc.{@link #tryLock(long,long,boolean) tryLock}(0L, Long.MAX_VALUE, false) </pre> |
|
1156 |
* |
|
1157 |
* @return A lock object representing the newly-acquired lock, |
|
32143
394ab6a6658d
8133459: replace <tt> tags (obsolete in html5) in java.nio docs
avstepan
parents:
29986
diff
changeset
|
1158 |
* or {@code null} if the lock could not be acquired |
2 | 1159 |
* because another program holds an overlapping lock |
1160 |
* |
|
1161 |
* @throws ClosedChannelException |
|
1162 |
* If this channel is closed |
|
1163 |
* |
|
1164 |
* @throws OverlappingFileLockException |
|
1165 |
* If a lock that overlaps the requested region is already held by |
|
1166 |
* this Java virtual machine, or if another thread is already |
|
1167 |
* blocked in this method and is attempting to lock an overlapping |
|
1168 |
* region |
|
1169 |
* |
|
1170 |
* @throws IOException |
|
1171 |
* If some other I/O error occurs |
|
1172 |
* |
|
1173 |
* @see #lock() |
|
1174 |
* @see #lock(long,long,boolean) |
|
1175 |
* @see #tryLock(long,long,boolean) |
|
1176 |
*/ |
|
1177 |
public final FileLock tryLock() throws IOException { |
|
1178 |
return tryLock(0L, Long.MAX_VALUE, false); |
|
1179 |
} |
|
1180 |
||
1181 |
} |