Produced by Araxis Merge on 9/25/2018 2:13:09 PM Central Daylight Time. See www.araxis.com for information about Merge. This report uses XHTML and CSS2, and is best viewed with a modern standards-compliant browser. For optimum results when printing this report, use landscape orientation and enable printing of background images and colours in your browser.
# | Location | File | Last Modified |
---|---|---|---|
1 | build 3.zip\build 3\MHLTH_YS_137_Source\JavaScript\resources\javaJDF-1.8.0\src\java\nio\channels | FileChannel.java | Mon Jan 22 14:46:52 2018 UTC |
2 | build 3.zip\build 3\MHLTH_YS_137_Source\JavaScript\resources\javaJDF-1.8.0\src\java\nio\channels | FileChannel.java | Wed Sep 12 17:10:46 2018 UTC |
Description | Between Files 1 and 2 |
|
---|---|---|
Text Blocks | Lines | |
Unchanged | 2 | 2314 |
Changed | 1 | 2 |
Inserted | 0 | 0 |
Removed | 0 | 0 |
Whitespace | |
---|---|
Character case | Differences in character case are significant |
Line endings | Differences in line endings (CR and LF characters) are ignored |
CR/LF characters | Not shown in the comparison detail |
No regular expressions were active.
1 | /* | |
2 | * Copyrig ht (c) 200 0, 2013, O racle and/ or its aff iliates. A ll rights reserved. | |
3 | * DO NOT ALTER OR R EMOVE COPY RIGHT NOTI CES OR THI S FILE HEA DER. | |
4 | * | |
5 | * This co de is free software; you can r edistribut e it and/o r modify i t | |
6 | * under t he terms o f the GNU General Pu blic Licen se version 2 only, a s | |
7 | * publish ed by the Free Softw are Founda tion. Ora cle design ates this | |
8 | * particu lar file a s subject to the "Cl asspath" e xception a s provided | |
9 | * by Orac le in the LICENSE fi le that ac companied this code. | |
10 | * | |
11 | * This co de is dist ributed in the hope that it wi ll be usef ul, but WI THOUT | |
12 | * ANY WAR RANTY; wit hout even the implie d warranty of MERCHA NTABILITY or | |
13 | * FITNESS FOR A PAR TICULAR PU RPOSE. Se e the GNU General Pu blic Licen se | |
14 | * version 2 for mor e details (a copy is included in the LIC ENSE file that | |
15 | * accompa nied this code). | |
16 | * | |
17 | * You sho uld have r eceived a copy of th e GNU Gene ral Public License v ersion | |
18 | * 2 along with this work; if not, write to the Fr ee Softwar e Foundati on, | |
19 | * Inc., 5 1 Franklin St, Fifth Floor, Bo ston, MA 0 2110-1301 USA. | |
20 | * | |
21 | * Please contact Or acle, 500 Oracle Par kway, Redw ood Shores , CA 94065 USA | |
22 | * or visi t www.orac le.com if you need a dditional informatio n or have any | |
23 | * questio ns. | |
24 | */ | |
25 | ||
26 | package ja va.nio.cha nnels; | |
27 | ||
28 | import jav a.io.*; | |
29 | import jav a.nio.Byte Buffer; | |
30 | import jav a.nio.Mapp edByteBuff er; | |
31 | import jav a.nio.chan nels.spi.A bstractInt erruptible Channel; | |
32 | import jav a.nio.file .*; | |
33 | import jav a.nio.file .attribute .FileAttri bute; | |
34 | import jav a.nio.file .spi.*; | |
35 | import jav a.util.Set ; | |
36 | import jav a.util.Has hSet; | |
37 | import jav a.util.Col lections; | |
38 | ||
39 | /** | |
40 | * A chann el for rea ding, writ ing, mappi ng, and ma nipulating a file. | |
41 | * | |
42 | * <p> A f ile channe l is a {@l ink Seekab leByteChan nel} that is connect ed to | |
43 | * a file. It has a current <i >position< /i> within its file which can | |
44 | * be both {@link #p osition() <i>queried </i>} and {@link #po sition(lon g) | |
45 | * <i>modi fied</i>}. The file itself co ntains a v ariable-le ngth seque nce | |
46 | * of byte s that can be read a nd written and whose current { @link #siz e | |
47 | * <i>size </i>} can be queried . The siz e of the f ile increa ses | |
48 | * when by tes are wr itten beyo nd its cur rent size; the size of the fil e | |
49 | * decreas es when it is {@link #truncate <i>trunca ted</i>}. The | |
50 | * file ma y also hav e some ass ociated <i >metadata< /i> such a s access | |
51 | * permiss ions, cont ent type, and last-m odificatio n time; th is class d oes not | |
52 | * define methods fo r metadata access. | |
53 | * | |
54 | * <p> In addition t o the fami liar read, write, an d close op erations o f byte | |
55 | * channel s, this cl ass define s the foll owing file -specific operations : </p> | |
56 | * | |
57 | * <ul> | |
58 | * | |
59 | * <li>< p> Bytes m ay be {@li nk #read(B yteBuffer, long) rea d} or | |
60 | * {@lin k #write(B yteBuffer, long) <i> written</i >} at an a bsolute | |
61 | * posit ion in a f ile in a w ay that do es not aff ect the ch annel's cu rrent | |
62 | * posit ion. </p> </li> | |
63 | * | |
64 | * <li>< p> A regio n of a fil e may be { @link #map <i>mapped </i>} | |
65 | * direc tly into m emory; for large fil es this is often muc h more eff icient | |
66 | * than invoking t he usual < tt>read</t t> or <tt> write</tt> methods. | |
67 | * </p>< /li> | |
68 | * | |
69 | * <li>< p> Updates made to a file may be {@link #force <i> forced | |
70 | * out</ i>} to the underlyin g storage device, en suring tha t data are not | |
71 | * lost in the eve nt of a sy stem crash . </p></l i> | |
72 | * | |
73 | * <li>< p> Bytes c an be tran sferred fr om a file {@link #tr ansferTo < i>to | |
74 | * some other chan nel</i>}, and {@link #transfer From <i>vi ce | |
75 | * versa </i>}, in a way that can be op timized by many oper ating syst ems | |
76 | * into a very fas t transfer directly to or from the files ystem cach e. | |
77 | * </p>< /li> | |
78 | * | |
79 | * <li>< p> A regio n of a fil e may be { @link File Lock <i>lo cked</i>} | |
80 | * again st access by other p rograms. </p></li> | |
81 | * | |
82 | * </ul> | |
83 | * | |
84 | * <p> Fil e channels are safe for use by multiple concurrent threads. The | |
85 | * {@link Channel#cl ose close} method ma y be invok ed at any time, as s pecified | |
86 | * by the {@link Cha nnel} inte rface. On ly one ope ration tha t involves the | |
87 | * channel 's positio n or can c hange its file's siz e may be i n progress at any | |
88 | * given t ime; attem pts to ini tiate a se cond such operation while the first is | |
89 | * still i n progress will bloc k until th e first op eration co mpletes. Other | |
90 | * operati ons, in pa rticular t hose that take an ex plicit pos ition, may proceed | |
91 | * concurr ently; whe ther they in fact do so is dep endent upo n the unde rlying | |
92 | * impleme ntation an d is there fore unspe cified. | |
93 | * | |
94 | * <p> The view of a file prov ided by an instance of this cl ass is gua ranteed | |
95 | * to be c onsistent with other views of the same f ile provid ed by othe r | |
96 | * instanc es in the same progr am. The v iew provid ed by an i nstance of this | |
97 | * class m ay or may not, howev er, be con sistent wi th the vie ws seen by other | |
98 | * concurr ently-runn ing progra ms due to caching pe rformed by the under lying | |
99 | * operati ng system and delays induced b y network- filesystem protocols . This | |
100 | * is true regardles s of the l anguage in which the se other p rograms ar e | |
101 | * written , and whet her they a re running on the sa me machine or on som e other | |
102 | * machine . The exa ct nature of any suc h inconsis tencies ar e system-d ependent | |
103 | * and are therefore unspecifi ed. | |
104 | * | |
105 | * <p> A f ile channe l is creat ed by invo king one o f the {@li nk #open o pen} | |
106 | * methods defined b y this cla ss. A file channel c an also be obtained from an | |
107 | * existin g {@link j ava.io.Fil eInputStre am#getChan nel FileIn putStream} , {@link | |
108 | * java.io .FileOutpu tStream#ge tChannel F ileOutputS tream}, or {@link | |
109 | * java.io .RandomAcc essFile#ge tChannel R andomAcces sFile} obj ect by inv oking | |
110 | * that ob ject's <tt >getChanne l</tt> met hod, which returns a file chan nel that | |
111 | * is conn ected to t he same un derlying f ile. Where the file channel is obtained | |
112 | * from an existing stream or random acc ess file t hen the st ate of the file | |
113 | * channel is intima tely conne cted to th at of the object who se <tt>get Channel</t t> | |
114 | * method returned t he channel . Changin g the chan nel's posi tion, whet her | |
115 | * explici tly or by reading or writing b ytes, will change th e file pos ition of | |
116 | * the ori ginating o bject, and vice vers a. Changin g the file 's length via the | |
117 | * file ch annel will change th e length s een via th e originat ing object , and vice | |
118 | * versa. Changing the file's content b y writing bytes will change th e content | |
119 | * seen by the origi nating obj ect, and v ice versa. | |
120 | * | |
121 | * <a name ="open-mod e"></a> <p > At vario us points this class specifies that an | |
122 | * instanc e that is "open for reading," "open for writing," or "open f or | |
123 | * reading and writi ng" is req uired. A channel ob tained via the {@lin k | |
124 | * java.io .FileInput Stream#get Channel ge tChannel} method of a {@link | |
125 | * java.io .FileInput Stream} in stance wil l be open for readin g. A chan nel | |
126 | * obtaine d via the {@link jav a.io.FileO utputStrea m#getChann el getChan nel} | |
127 | * method of a {@lin k java.io. FileOutput Stream} in stance wil l be open for | |
128 | * writing . Finally , a channe l obtained via the { @link | |
129 | * java.io .RandomAcc essFile#ge tChannel g etChannel} method of a {@link | |
130 | * java.io .RandomAcc essFile} i nstance wi ll be open for readi ng if the instance | |
131 | * was cre ated with mode <tt>" r"</tt> an d will be open for r eading and writing | |
132 | * if the instance w as created with mode <tt>"rw"< /tt>. | |
133 | * | |
134 | * <a name ="append-m ode"></a>< p> A file channel th at is open for writi ng may be in | |
135 | * <i>appe nd mode</i >, for exa mple if it was obtai ned from a file-outp ut stream | |
136 | * that wa s created by invokin g the {@li nk | |
137 | * java.io .FileOutpu tStream#Fi leOutputSt ream(java. io.File,bo olean) | |
138 | * FileOut putStream( File,boole an)} const ructor and passing < tt>true</t t> for | |
139 | * the sec ond parame ter. In t his mode e ach invoca tion of a relative w rite | |
140 | * operati on first a dvances th e position to the en d of the f ile and th en writes | |
141 | * the req uested dat a. Whethe r the adva ncement of the posit ion and th e writing | |
142 | * of the data are d one in a s ingle atom ic operati on is syst em-depende nt and | |
143 | * therefo re unspeci fied. | |
144 | * | |
145 | * @see ja va.io.File InputStrea m#getChann el() | |
146 | * @see ja va.io.File OutputStre am#getChan nel() | |
147 | * @see ja va.io.Rand omAccessFi le#getChan nel() | |
148 | * | |
149 | * @author Mark Rein hold | |
150 | * @author Mike McCl oskey | |
151 | * @author JSR-51 Ex pert Group | |
152 | * @since 1.4 | |
153 | */ | |
154 | ||
155 | public abs tract clas s FileChan nel | |
156 | extend s Abstract Interrupti bleChannel | |
157 | implem ents Seeka bleByteCha nnel, Gath eringByteC hannel, Sc atteringBy teChannel | |
158 | { | |
159 | /** | |
160 | * Ini tializes a new insta nce of thi s class. | |
161 | */ | |
162 | protec ted FileCh annel() { } | |
163 | ||
164 | /** | |
165 | * Ope ns or crea tes a file , returnin g a file c hannel to access the file. | |
166 | * | |
167 | * <p> The {@cod e options} parameter determine s how the file is op ened. | |
168 | * The {@link St andardOpen Option#REA D READ} an d {@link S tandardOpe nOption#WR ITE | |
169 | * WRI TE} option s determin e if the f ile should be opened for readi ng and/or | |
170 | * wri ting. If n either opt ion (or th e {@link S tandardOpe nOption#AP PEND APPEN D} | |
171 | * opt ion) is co ntained in the array then the file is op ened for r eading. | |
172 | * By default re ading or w riting com mences at the beginn ing of the file. | |
173 | * | |
174 | * <p> In the ad dition to {@code REA D} and {@c ode WRITE} , the foll owing | |
175 | * opt ions may b e present: | |
176 | * | |
177 | * <ta ble border =1 cellpad ding=5 sum mary=""> | |
178 | * <tr > <th>Opti on</th> <t h>Descript ion</th> < /tr> | |
179 | * <tr > | |
180 | * < td> {@link StandardO penOption# APPEND APP END} </td> | |
181 | * < td> If thi s option i s present then the f ile is ope ned for wr iting and | |
182 | * each invo cation of the channe l's {@code write} me thod first advances | |
183 | * the posit ion to the end of th e file and then writ es the req uested | |
184 | * data. Whe ther the a dvancement of the po sition and the writi ng of the | |
185 | * data are done in a single ato mic operat ion is sys tem-depend ent and | |
186 | * therefore unspecifi ed. This o ption may not be use d in conju nction | |
187 | * with the {@code REA D} or {@co de TRUNCAT E_EXISTING } options. </td> | |
188 | * </t r> | |
189 | * <tr > | |
190 | * < td> {@link StandardO penOption# TRUNCATE_E XISTING TR UNCATE_EXI STING} </t d> | |
191 | * < td> If thi s option i s present then the e xisting fi le is trun cated to | |
192 | * a size of 0 bytes. Th is option is ignored when the file is op ened only | |
193 | * f or reading . </td> | |
194 | * </t r> | |
195 | * <tr > | |
196 | * < td> {@link StandardO penOption# CREATE_NEW CREATE_NE W} </td> | |
197 | * < td> If thi s option i s present then a new file is c reated, fa iling if | |
198 | * t he file al ready exis ts. When c reating a file the c heck for t he | |
199 | * e xistence o f the file and the c reation of the file if it does not exist | |
200 | * i s atomic w ith respec t to other file syst em operati ons. This option is | |
201 | * i gnored whe n the file is opened only for reading. < /td> | |
202 | * </t r> | |
203 | * <tr > | |
204 | * < td > {@lin k Standard OpenOption #CREATE CR EATE} </td > | |
205 | * < td> If thi s option i s present then an ex isting fil e is opene d if it | |
206 | * e xists, oth erwise a n ew file is created. When creat ing a file the check | |
207 | * f or the exi stence of the file a nd the cre ation of t he file if it does | |
208 | * n ot exist i s atomic w ith respec t to other file syst em operati ons. This | |
209 | * o ption is i gnored if the {@code CREATE_NE W} option is also pr esent or | |
210 | * t he file is opened on ly for rea ding. </td > | |
211 | * </t r> | |
212 | * <tr > | |
213 | * < td > {@lin k Standard OpenOption #DELETE_ON _CLOSE DEL ETE_ON_CLO SE} </td> | |
214 | * < td> When t his option is presen t then the implement ation make s a | |
215 | * < em>best ef fort</em> attempt to delete th e file whe n closed b y the | |
216 | * t he {@link #close clo se} method . If the { @code clos e} method is not | |
217 | * i nvoked the n a <em>be st effort< /em> attem pt is made to delete the file | |
218 | * w hen the Ja va virtual machine t erminates. </td> | |
219 | * </t r> | |
220 | * <tr > | |
221 | * < td>{@link StandardOp enOption#S PARSE SPAR SE} </td> | |
222 | * < td> When c reating a new file t his option is a <em> hint</em> that the | |
223 | * n ew file wi ll be spar se. This o ption is i gnored whe n not crea ting | |
224 | * a new file. </td> | |
225 | * </t r> | |
226 | * <tr > | |
227 | * < td> {@link StandardO penOption# SYNC SYNC} </td> | |
228 | * < td> Requir es that ev ery update to the fi le's conte nt or meta data be | |
229 | * w ritten syn chronously to the un derlying s torage dev ice. (see <a | |
230 | * h ref="../fi le/package -summary.h tml#integr ity"> Sync hronized I /O file | |
231 | * i ntegrity</ a>). </td> | |
232 | * </t r> | |
233 | * <tr > | |
234 | * < td> {@link StandardO penOption# DSYNC DSYN C} </td> | |
235 | * < td> Requir es that ev ery update to the fi le's conte nt be writ ten | |
236 | * s ynchronous ly to the underlying storage d evice. (se e <a | |
237 | * h ref="../fi le/package -summary.h tml#integr ity"> Sync hronized I /O file | |
238 | * i ntegrity</ a>). </td> | |
239 | * </t r> | |
240 | * </t able> | |
241 | * | |
242 | * <p> An implem entation m ay also su pport addi tional opt ions. | |
243 | * | |
244 | * <p> The {@cod e attrs} p arameter i s an optio nal array of file {@ link | |
245 | * Fil eAttribute file-attr ibutes} to set atomi cally when creating the file. | |
246 | * | |
247 | * <p> The new c hannel is created by invoking the {@link | |
248 | * Fil eSystemPro vider#newF ileChannel newFileCh annel} met hod on the | |
249 | * pro vider that created t he {@code Path}. | |
250 | * | |
251 | * @pa ram path | |
252 | * The path of th e file to open or cr eate | |
253 | * @pa ram opti ons | |
254 | * Opti ons specif ying how t he file is opened | |
255 | * @pa ram attr s | |
256 | * An o ptional li st of file attribute s to set a tomically when | |
257 | * crea ting the f ile | |
258 | * | |
259 | * @re turn A ne w file cha nnel | |
260 | * | |
261 | * @th rows Ille galArgumen tException | |
262 | * If t he set con tains an i nvalid com bination o f options | |
263 | * @th rows Unsu pportedOpe rationExce ption | |
264 | * If t he {@code path} is a ssociated with a pro vider that does not | |
265 | * supp ort creati ng file ch annels, or an unsupp orted open option is | |
266 | * spec ified, or the array contains a n attribut e that can not be set | |
267 | * atom ically whe n creating the file | |
268 | * @th rows IOEx ception | |
269 | * If a n I/O erro r occurs | |
270 | * @th rows Secu rityExcept ion | |
271 | * If a security manager is installed and it de nies an | |
272 | * unsp ecified pe rmission r equired by the imple mentation. | |
273 | * In t he case of the defau lt provide r, the {@l ink | |
274 | * Secu rityManage r#checkRea d(String)} method is invoked t o check | |
275 | * read access if the file is opened for readin g. The {@l ink | |
276 | * Secu rityManage r#checkWri te(String) } method i s invoked to check | |
277 | * writ e access i f the file is opened for writi ng | |
278 | * | |
279 | * @si nce 1.7 | |
280 | */ | |
281 | public static Fi leChannel open(Path path, | |
282 | Set<? extends O penOption> options, | |
283 | FileA ttribute<? >... attrs ) | |
284 | th rows IOExc eption | |
285 | { | |
286 | Fi leSystemPr ovider pro vider = pa th.getFile System().p rovider(); | |
287 | re turn provi der.newFil eChannel(p ath, optio ns, attrs) ; | |
288 | } | |
289 | ||
290 | @Suppr essWarning s({"unchec ked", "raw types"}) / / generic array cons truction | |
291 | privat e static f inal FileA ttribute<? >[] NO_ATT RIBUTES = new FileAt tribute[0] ; | |
292 | ||
293 | /** | |
294 | * Ope ns or crea tes a file , returnin g a file c hannel to access the file. | |
295 | * | |
296 | * <p> An invoca tion of th is method behaves in exactly t he same wa y as the | |
297 | * inv ocation | |
298 | * <pr e> | |
299 | * fc.{@link #open(Pat h,Set,File Attribute[ ]) open}(f ile, opts, new FileA ttribute&l t;?>[0] ); | |
300 | * </p re> | |
301 | * whe re {@code opts} is a set of th e options specified in the {@c ode | |
302 | * opt ions} arra y. | |
303 | * | |
304 | * @pa ram path | |
305 | * The path of th e file to open or cr eate | |
306 | * @pa ram opti ons | |
307 | * Opti ons specif ying how t he file is opened | |
308 | * | |
309 | * @re turn A ne w file cha nnel | |
310 | * | |
311 | * @th rows Ille galArgumen tException | |
312 | * If t he set con tains an i nvalid com bination o f options | |
313 | * @th rows Unsu pportedOpe rationExce ption | |
314 | * If t he {@code path} is a ssociated with a pro vider that does not | |
315 | * supp ort creati ng file ch annels, or an unsupp orted open option is | |
316 | * spec ified | |
317 | * @th rows IOEx ception | |
318 | * If a n I/O erro r occurs | |
319 | * @th rows Secu rityExcept ion | |
320 | * If a security manager is installed and it de nies an | |
321 | * unsp ecified pe rmission r equired by the imple mentation. | |
322 | * In t he case of the defau lt provide r, the {@l ink | |
323 | * Secu rityManage r#checkRea d(String)} method is invoked t o check | |
324 | * read access if the file is opened for readin g. The {@l ink | |
325 | * Secu rityManage r#checkWri te(String) } method i s invoked to check | |
326 | * writ e access i f the file is opened for writi ng | |
327 | * | |
328 | * @si nce 1.7 | |
329 | */ | |
330 | public static Fi leChannel open(Path path, Open Option... options) | |
331 | th rows IOExc eption | |
332 | { | |
333 | Se t<OpenOpti on> set = new HashSe t<OpenOpti on>(option s.length); | |
334 | Co llections. addAll(set , options) ; | |
335 | re turn open( path, set, NO_ATTRIB UTES); | |
336 | } | |
337 | ||
338 | // -- Channel op erations - - | |
339 | ||
340 | /** | |
341 | * Rea ds a seque nce of byt es from th is channel into the given buff er. | |
342 | * | |
343 | * <p> Bytes are read star ting at th is channel 's current file posi tion, and | |
344 | * the n the file position is updated with the number of bytes actu ally | |
345 | * rea d. Otherw ise this m ethod beha ves exactl y as speci fied in th e {@link | |
346 | * Rea dableByteC hannel} in terface. < /p> | |
347 | */ | |
348 | public abstract int read(B yteBuffer dst) throw s IOExcept ion; | |
349 | ||
350 | /** | |
351 | * Rea ds a seque nce of byt es from th is channel into a su bsequence of the | |
352 | * giv en buffers . | |
353 | * | |
354 | * <p> Bytes are read star ting at th is channel 's current file posi tion, and | |
355 | * the n the file position is updated with the number of bytes actu ally | |
356 | * rea d. Otherw ise this m ethod beha ves exactl y as speci fied in th e {@link | |
357 | * Sca tteringByt eChannel} interface. </p> | |
358 | */ | |
359 | public abstract long read( ByteBuffer [] dsts, i nt offset, int lengt h) | |
360 | th rows IOExc eption; | |
361 | ||
362 | /** | |
363 | * Rea ds a seque nce of byt es from th is channel into the given buff ers. | |
364 | * | |
365 | * <p> Bytes are read star ting at th is channel 's current file posi tion, and | |
366 | * the n the file position is updated with the number of bytes actu ally | |
367 | * rea d. Otherw ise this m ethod beha ves exactl y as speci fied in th e {@link | |
368 | * Sca tteringByt eChannel} interface. </p> | |
369 | */ | |
370 | public final lon g read(Byt eBuffer[] dsts) thro ws IOExcep tion { | |
371 | re turn read( dsts, 0, d sts.length ); | |
372 | } | |
373 | ||
374 | /** | |
375 | * Wri tes a sequ ence of by tes to thi s channel from the g iven buffe r. | |
376 | * | |
377 | * <p> Bytes are written s tarting at this chan nel's curr ent file p osition | |
378 | * unl ess the ch annel is i n append m ode, in wh ich case t he positio n is | |
379 | * fir st advance d to the e nd of the file. The file is g rown, if n ecessary, | |
380 | * to accommodat e the writ ten bytes, and then the file p osition is updated | |
381 | * wit h the numb er of byte s actually written. Otherwise this meth od | |
382 | * beh aves exact ly as spec ified by t he {@link WritableBy teChannel} | |
383 | * int erface. </ p> | |
384 | */ | |
385 | public abstract int write( ByteBuffer src) thro ws IOExcep tion; | |
386 | ||
387 | /** | |
388 | * Wri tes a sequ ence of by tes to thi s channel from a sub sequence o f the | |
389 | * giv en buffers . | |
390 | * | |
391 | * <p> Bytes are written s tarting at this chan nel's curr ent file p osition | |
392 | * unl ess the ch annel is i n append m ode, in wh ich case t he positio n is | |
393 | * fir st advance d to the e nd of the file. The file is g rown, if n ecessary, | |
394 | * to accommodat e the writ ten bytes, and then the file p osition is updated | |
395 | * wit h the numb er of byte s actually written. Otherwise this meth od | |
396 | * beh aves exact ly as spec ified in t he {@link GatheringB yteChannel } | |
397 | * int erface. < /p> | |
398 | */ | |
399 | public abstract long write (ByteBuffe r[] srcs, int offset , int leng th) | |
400 | th rows IOExc eption; | |
401 | ||
402 | /** | |
403 | * Wri tes a sequ ence of by tes to thi s channel from the g iven buffe rs. | |
404 | * | |
405 | * <p> Bytes are written s tarting at this chan nel's curr ent file p osition | |
406 | * unl ess the ch annel is i n append m ode, in wh ich case t he positio n is | |
407 | * fir st advance d to the e nd of the file. The file is g rown, if n ecessary, | |
408 | * to accommodat e the writ ten bytes, and then the file p osition is updated | |
409 | * wit h the numb er of byte s actually written. Otherwise this meth od | |
410 | * beh aves exact ly as spec ified in t he {@link GatheringB yteChannel } | |
411 | * int erface. < /p> | |
412 | */ | |
413 | public final lon g write(By teBuffer[] srcs) thr ows IOExce ption { | |
414 | re turn write (srcs, 0, srcs.lengt h); | |
415 | } | |
416 | ||
417 | ||
418 | // -- Other oper ations -- | |
419 | ||
420 | /** | |
421 | * Ret urns this channel's file posit ion. | |
422 | * | |
423 | * @re turn This channel's file posi tion, | |
424 | * a no n-negative integer c ounting th e number o f bytes | |
425 | * from the begin ning of th e file to the curren t position | |
426 | * | |
427 | * @th rows Clos edChannelE xception | |
428 | * If t his channe l is close d | |
429 | * | |
430 | * @th rows IOEx ception | |
431 | * If s ome other I/O error occurs | |
432 | */ | |
433 | public abstract long posit ion() thro ws IOExcep tion; | |
434 | ||
435 | /** | |
436 | * Set s this cha nnel's fil e position . | |
437 | * | |
438 | * <p> Setting t he positio n to a val ue that is greater t han the fi le's | |
439 | * cur rent size is legal b ut does no t change t he size of the file. A later | |
440 | * att empt to re ad bytes a t such a p osition wi ll immedia tely retur n an | |
441 | * end -of-file i ndication. A later attempt to write byt es at such a | |
442 | * pos ition will cause the file to b e grown to accommoda te the new bytes; | |
443 | * the values of any bytes between t he previou s end-of-f ile and th e | |
444 | * new ly-written bytes are unspecifi ed. </p> | |
445 | * | |
446 | * @pa ram newPo sition | |
447 | * The n ew positio n, a non-n egative in teger coun ting | |
448 | * the n umber of b ytes from the beginn ing of the file | |
449 | * | |
450 | * @re turn This file chan nel | |
451 | * | |
452 | * @th rows Clos edChannelE xception | |
453 | * If t his channe l is close d | |
454 | * | |
455 | * @th rows Ille galArgumen tException | |
456 | * If t he new pos ition is n egative | |
457 | * | |
458 | * @th rows IOEx ception | |
459 | * If s ome other I/O error occurs | |
460 | */ | |
461 | public abstract FileChanne l position (long newP osition) t hrows IOEx ception; | |
462 | ||
463 | /** | |
464 | * Ret urns the c urrent siz e of this channel's file. | |
465 | * | |
466 | * @re turn The current si ze of this channel's file, | |
467 | * meas ured in by tes | |
468 | * | |
469 | * @th rows Clos edChannelE xception | |
470 | * If t his channe l is close d | |
471 | * | |
472 | * @th rows IOEx ception | |
473 | * If s ome other I/O error occurs | |
474 | */ | |
475 | public abstract long size( ) throws I OException ; | |
476 | ||
477 | /** | |
478 | * Tru ncates thi s channel' s file to the given size. | |
479 | * | |
480 | * <p> If the gi ven size i s less tha n the file 's current size then the file | |
481 | * is truncated, discardin g any byte s beyond t he new end of the fi le. If | |
482 | * the given siz e is great er than or equal to the file's current s ize then | |
483 | * the file is n ot modifie d. In eit her case, if this ch annel's fi le | |
484 | * pos ition is g reater tha n the give n size the n it is se t to that size. | |
485 | * </p > | |
486 | * | |
487 | * @pa ram size | |
488 | * The n ew size, a non-negat ive byte c ount | |
489 | * | |
490 | * @re turn This file chan nel | |
491 | * | |
492 | * @th rows NonW ritableCha nnelExcept ion | |
493 | * If t his channe l was not opened for writing | |
494 | * | |
495 | * @th rows Clos edChannelE xception | |
496 | * If t his channe l is close d | |
497 | * | |
498 | * @th rows Ille galArgumen tException | |
499 | * If t he new siz e is negat ive | |
500 | * | |
501 | * @th rows IOEx ception | |
502 | * If s ome other I/O error occurs | |
503 | */ | |
504 | public abstract FileChanne l truncate (long size ) throws I OException ; | |
505 | ||
506 | /** | |
507 | * For ces any up dates to t his channe l's file t o be writt en to the storage | |
508 | * dev ice that c ontains it . | |
509 | * | |
510 | * <p> If this c hannel's f ile reside s on a loc al storage device th en when | |
511 | * thi s method r eturns it is guarant eed that a ll changes made to t he file | |
512 | * sin ce this ch annel was created, o r since th is method was last i nvoked, | |
513 | * wil l have bee n written to that de vice. Thi s is usefu l for ensu ring that | |
514 | * cri tical info rmation is not lost in the eve nt of a sy stem crash . | |
515 | * | |
516 | * <p> If the fi le does no t reside o n a local device the n no such guarantee | |
517 | * is made. | |
518 | * | |
519 | * <p> The <tt>m etaData</t t> paramet er can be used to li mit the nu mber of | |
520 | * I/O operation s that thi s method i s required to perfor m. Passin g | |
521 | * <tt >false</tt > for this parameter indicates that only updates t o the | |
522 | * fil e's conten t need be written to storage; passing <t t>true</tt > | |
523 | * ind icates tha t updates to both th e file's c ontent and metadata must be | |
524 | * wri tten, whic h generall y requires at least one more I /O operati on. | |
525 | * Whe ther this parameter actually h as any eff ect is dep endent upo n the | |
526 | * und erlying op erating sy stem and i s therefor e unspecif ied. | |
527 | * | |
528 | * <p> Invoking this metho d may caus e an I/O o peration t o occur ev en if the | |
529 | * cha nnel was o nly opened for readi ng. Some operating systems, f or | |
530 | * exa mple, main tain a las t-access t ime as par t of a fil e's metada ta, and | |
531 | * thi s time is updated wh enever the file is r ead. Whet her or not this is | |
532 | * act ually done is system -dependent and is th erefore un specified. | |
533 | * | |
534 | * <p> This meth od is only guarantee d to force changes t hat were m ade to | |
535 | * thi s channel' s file via the metho ds defined in this c lass. It may or | |
536 | * may not force changes t hat were m ade by mod ifying the content o f a | |
537 | * {@l ink Mapped ByteBuffer <i>mapped byte buff er</i>} ob tained by | |
538 | * inv oking the {@link #ma p map} met hod. Invo king the { @link | |
539 | * Map pedByteBuf fer#force force} met hod of the mapped by te buffer will | |
540 | * for ce changes made to t he buffer' s content to be writ ten. </p> | |
541 | * | |
542 | * @pa ram meta Data | |
543 | * If < tt>true</t t> then th is method is require d to force changes | |
544 | * to b oth the fi le's conte nt and met adata to b e written to | |
545 | * stor age; other wise, it n eed only f orce conte nt changes to be | |
546 | * writ ten | |
547 | * | |
548 | * @th rows Clos edChannelE xception | |
549 | * If t his channe l is close d | |
550 | * | |
551 | * @th rows IOEx ception | |
552 | * If s ome other I/O error occurs | |
553 | */ | |
554 | public abstract void force (boolean m etaData) t hrows IOEx ception; | |
555 | ||
556 | /** | |
557 | * Tra nsfers byt es from th is channel 's file to the given writable byte | |
558 | * cha nnel. | |
559 | * | |
560 | * <p> An attemp t is made to read up to <tt>co unt</tt> b ytes start ing at | |
561 | * the given <tt >position< /tt> in th is channel 's file an d write th em to the | |
562 | * tar get channe l. An inv ocation of this meth od may or may not tr ansfer | |
563 | * all of the re quested by tes; wheth er or not it does so depends u pon the | |
564 | * nat ures and s tates of t he channel s. Fewer than the r equested n umber of | |
565 | * byt es are tra nsferred i f this cha nnel's fil e contains fewer tha n | |
566 | * <tt >count</tt > bytes st arting at the given <tt>positi on</tt>, o r if the | |
567 | * tar get channe l is non-b locking an d it has f ewer than <tt>count< /tt> | |
568 | * byt es free in its outpu t buffer. | |
569 | * | |
570 | * <p> This meth od does no t modify t his channe l's positi on. If th e given | |
571 | * pos ition is g reater tha n the file 's current size then no bytes are | |
572 | * tra nsferred. If the ta rget chann el has a p osition th en bytes a re | |
573 | * wri tten start ing at tha t position and then the positi on is incr emented | |
574 | * by the number of bytes written. | |
575 | * | |
576 | * <p> This meth od is pote ntially mu ch more ef ficient th an a simpl e loop | |
577 | * tha t reads fr om this ch annel and writes to the target channel. Many | |
578 | * ope rating sys tems can t ransfer by tes direct ly from th e filesyst em cache | |
579 | * to the target channel w ithout act ually copy ing them. </p> | |
580 | * | |
581 | * @pa ram posit ion | |
582 | * The p osition wi thin the f ile at whi ch the tra nsfer is t o begin; | |
583 | * must be non-neg ative | |
584 | * | |
585 | * @pa ram count | |
586 | * The m aximum num ber of byt es to be t ransferred ; must be | |
587 | * non-n egative | |
588 | * | |
589 | * @pa ram targe t | |
590 | * The t arget chan nel | |
591 | * | |
592 | * @re turn The number of bytes, pos sibly zero , | |
593 | * that were actu ally trans ferred | |
594 | * | |
595 | * @th rows Illeg alArgument Exception | |
596 | * If th e precondi tions on t he paramet ers do not hold | |
597 | * | |
598 | * @th rows NonR eadableCha nnelExcept ion | |
599 | * If t his channe l was not opened for reading | |
600 | * | |
601 | * @th rows NonW ritableCha nnelExcept ion | |
602 | * If t he target channel wa s not open ed for wri ting | |
603 | * | |
604 | * @th rows Clos edChannelE xception | |
605 | * If e ither this channel o r the targ et channel is closed | |
606 | * | |
607 | * @th rows Asyn chronousCl oseExcepti on | |
608 | * If a nother thr ead closes either ch annel | |
609 | * whil e the tran sfer is in progress | |
610 | * | |
611 | * @th rows Clos edByInterr uptExcepti on | |
612 | * If a nother thr ead interr upts the c urrent thr ead while the | |
613 | * tran sfer is in progress, thereby c losing bot h channels and | |
614 | * sett ing the cu rrent thre ad's inter rupt statu s | |
615 | * | |
616 | * @th rows IOEx ception | |
617 | * If s ome other I/O error occurs | |
618 | */ | |
619 | public abstract long trans ferTo(long position, long coun t, | |
620 | Writ ableByteCh annel targ et) | |
621 | th rows IOExc eption; | |
622 | ||
623 | /** | |
624 | * Tra nsfers byt es into th is channel 's file fr om the giv en readabl e byte | |
625 | * cha nnel. | |
626 | * | |
627 | * <p> An attemp t is made to read up to <tt>co unt</tt> b ytes from the | |
628 | * sou rce channe l and writ e them to this chann el's file starting a t the | |
629 | * giv en <tt>pos ition</tt> . An invo cation of this metho d may or m ay not | |
630 | * tra nsfer all of the req uested byt es; whethe r or not i t does so depends | |
631 | * upo n the natu res and st ates of th e channels . Fewer t han the re quested | |
632 | * num ber of byt es will be transferr ed if the source cha nnel has f ewer than | |
633 | * <tt >count</tt > bytes re maining, o r if the s ource chan nel is non -blocking | |
634 | * and has fewer than <tt> count</tt> bytes imm ediately a vailable i n its | |
635 | * inp ut buffer. | |
636 | * | |
637 | * <p> This meth od does no t modify t his channe l's positi on. If th e given | |
638 | * pos ition is g reater tha n the file 's current size then no bytes are | |
639 | * tra nsferred. If the so urce chann el has a p osition th en bytes a re read | |
640 | * sta rting at t hat positi on and the n the posi tion is in cremented by the | |
641 | * num ber of byt es read. | |
642 | * | |
643 | * <p> This meth od is pote ntially mu ch more ef ficient th an a simpl e loop | |
644 | * tha t reads fr om the sou rce channe l and writ es to this channel. Many | |
645 | * ope rating sys tems can t ransfer by tes direct ly from th e source c hannel | |
646 | * int o the file system cac he without actually copying th em. </p> | |
647 | * | |
648 | * @pa ram src | |
649 | * The s ource chan nel | |
650 | * | |
651 | * @pa ram posit ion | |
652 | * The p osition wi thin the f ile at whi ch the tra nsfer is t o begin; | |
653 | * must be non-neg ative | |
654 | * | |
655 | * @pa ram count | |
656 | * The m aximum num ber of byt es to be t ransferred ; must be | |
657 | * non-n egative | |
658 | * | |
659 | * @re turn The number of bytes, pos sibly zero , | |
660 | * that were actu ally trans ferred | |
661 | * | |
662 | * @th rows Illeg alArgument Exception | |
663 | * If th e precondi tions on t he paramet ers do not hold | |
664 | * | |
665 | * @th rows NonR eadableCha nnelExcept ion | |
666 | * If t he source channel wa s not open ed for rea ding | |
667 | * | |
668 | * @th rows NonW ritableCha nnelExcept ion | |
669 | * If t his channe l was not opened for writing | |
670 | * | |
671 | * @th rows Clos edChannelE xception | |
672 | * If e ither this channel o r the sour ce channel is closed | |
673 | * | |
674 | * @th rows Asyn chronousCl oseExcepti on | |
675 | * If a nother thr ead closes either ch annel | |
676 | * whil e the tran sfer is in progress | |
677 | * | |
678 | * @th rows Clos edByInterr uptExcepti on | |
679 | * If a nother thr ead interr upts the c urrent thr ead while the | |
680 | * tran sfer is in progress, thereby c losing bot h channels and | |
681 | * sett ing the cu rrent thre ad's inter rupt statu s | |
682 | * | |
683 | * @th rows IOEx ception | |
684 | * If s ome other I/O error occurs | |
685 | */ | |
686 | public abstract long trans ferFrom(Re adableByte Channel sr c, | |
687 | lo ng positio n, long co unt) | |
688 | th rows IOExc eption; | |
689 | ||
690 | /** | |
691 | * Rea ds a seque nce of byt es from th is channel into the given buff er, | |
692 | * sta rting at t he given f ile positi on. | |
693 | * | |
694 | * <p> This meth od works i n the same manner as the {@lin k | |
695 | * #re ad(ByteBuf fer)} meth od, except that byte s are read starting at the | |
696 | * giv en file po sition rat her than a t the chan nel's curr ent positi on. This | |
697 | * met hod does n ot modify this chann el's posit ion. If t he given p osition | |
698 | * is greater th an the fil e's curren t size the n no bytes are read. </p> | |
699 | * | |
700 | * @pa ram dst | |
701 | * The b uffer into which byt es are to be transfe rred | |
702 | * | |
703 | * @pa ram posit ion | |
704 | * The f ile positi on at whic h the tran sfer is to begin; | |
705 | * must be non-neg ative | |
706 | * | |
707 | * @re turn The number of bytes read , possibly zero, or <tt>-1</tt > if the | |
708 | * give n position is greate r than or equal to t he file's current | |
709 | * size | |
710 | * | |
711 | * @th rows Ille galArgumen tException | |
712 | * If t he positio n is negat ive | |
713 | * | |
714 | * @th rows NonR eadableCha nnelExcept ion | |
715 | * If t his channe l was not opened for reading | |
716 | * | |
717 | * @th rows Clos edChannelE xception | |
718 | * If t his channe l is close d | |
719 | * | |
720 | * @th rows Asyn chronousCl oseExcepti on | |
721 | * If a nother thr ead closes this chan nel | |
722 | * whil e the read operation is in pro gress | |
723 | * | |
724 | * @th rows Clos edByInterr uptExcepti on | |
725 | * If a nother thr ead interr upts the c urrent thr ead | |
726 | * whil e the read operation is in pro gress, the reby | |
727 | * clos ing the ch annel and setting th e current thread's | |
728 | * inte rrupt stat us | |
729 | * | |
730 | * @th rows IOEx ception | |
731 | * If s ome other I/O error occurs | |
732 | */ | |
733 | public abstract int read(B yteBuffer dst, long position) throws IOE xception; | |
734 | ||
735 | /** | |
736 | * Wri tes a sequ ence of by tes to thi s channel from the g iven buffe r, | |
737 | * sta rting at t he given f ile positi on. | |
738 | * | |
739 | * <p> This meth od works i n the same manner as the {@lin k | |
740 | * #wr ite(ByteBu ffer)} met hod, excep t that byt es are wri tten start ing at | |
741 | * the given fil e position rather th an at the channel's current po sition. | |
742 | * Thi s method d oes not mo dify this channel's position. If the gi ven | |
743 | * pos ition is g reater tha n the file 's current size then the file will be | |
744 | * gro wn to acco mmodate th e new byte s; the val ues of any bytes bet ween the | |
745 | * pre vious end- of-file an d the newl y-written bytes are unspecifie d. </p> | |
746 | * | |
747 | * @pa ram src | |
748 | * The b uffer from which byt es are to be transfe rred | |
749 | * | |
750 | * @pa ram posit ion | |
751 | * The f ile positi on at whic h the tran sfer is to begin; | |
752 | * must be non-neg ative | |
753 | * | |
754 | * @re turn The number of bytes writ ten, possi bly zero | |
755 | * | |
756 | * @th rows Ille galArgumen tException | |
757 | * If t he positio n is negat ive | |
758 | * | |
759 | * @th rows NonW ritableCha nnelExcept ion | |
760 | * If t his channe l was not opened for writing | |
761 | * | |
762 | * @th rows Clos edChannelE xception | |
763 | * If t his channe l is close d | |
764 | * | |
765 | * @th rows Asyn chronousCl oseExcepti on | |
766 | * If a nother thr ead closes this chan nel | |
767 | * whil e the writ e operatio n is in pr ogress | |
768 | * | |
769 | * @th rows Clos edByInterr uptExcepti on | |
770 | * If a nother thr ead interr upts the c urrent thr ead | |
771 | * whil e the writ e operatio n is in pr ogress, th ereby | |
772 | * clos ing the ch annel and setting th e current thread's | |
773 | * inte rrupt stat us | |
774 | * | |
775 | * @th rows IOEx ception | |
776 | * If s ome other I/O error occurs | |
777 | */ | |
778 | public abstract int write( ByteBuffer src, long position) throws IO Exception; | |
779 | ||
780 | ||
781 | // -- Memory-map ped buffer s -- | |
782 | ||
783 | /** | |
784 | * A t ypesafe en umeration for file-m apping mod es. | |
785 | * | |
786 | * @si nce 1.4 | |
787 | * | |
788 | * @se e java.nio .channels. FileChanne l#map | |
789 | */ | |
790 | public static cl ass MapMod e { | |
791 | ||
792 | /* * | |
793 | * Mode for a read-onl y mapping. | |
794 | * / | |
795 | pu blic stati c final Ma pMode READ _ONLY | |
796 | = new Ma pMode("REA D_ONLY"); | |
797 | ||
798 | /* * | |
799 | * Mode for a read/wri te mapping . | |
800 | * / | |
801 | pu blic stati c final Ma pMode READ _WRITE | |
802 | = new Ma pMode("REA D_WRITE"); | |
803 | ||
804 | /* * | |
805 | * Mode for a private (copy-on-w rite) mapp ing. | |
806 | * / | |
807 | pu blic stati c final Ma pMode PRIV ATE | |
808 | = new Ma pMode("PRI VATE"); | |
809 | ||
810 | pr ivate fina l String n ame; | |
811 | ||
812 | pr ivate MapM ode(String name) { | |
813 | this.nam e = name; | |
814 | } | |
815 | ||
816 | /* * | |
817 | * Returns a string de scribing t his file-m apping mod e. | |
818 | * | |
819 | * @return A descript ive string | |
820 | * / | |
821 | pu blic Strin g toString () { | |
822 | return n ame; | |
823 | } | |
824 | ||
825 | } | |
826 | ||
827 | /** | |
828 | * Map s a region of this c hannel's f ile direct ly into me mory. | |
829 | * | |
830 | * <p> A region of a file may be map ped into m emory in o ne of thre e modes: | |
831 | * </p > | |
832 | * | |
833 | * <ul > | |
834 | * | |
835 | * < li><p> <i> Read-only: </i> Any a ttempt to modify the resulting buffer | |
836 | * w ill cause a {@link j ava.nio.Re adOnlyBuff erExceptio n} to be t hrown. | |
837 | * ( {@link Map Mode#READ_ ONLY MapMo de.READ_ON LY}) </p>< /li> | |
838 | * | |
839 | * < li><p> <i> Read/write :</i> Chan ges made t o the resu lting buff er will | |
840 | * e ventually be propaga ted to the file; the y may or m ay not be made | |
841 | * v isible to other prog rams that have mappe d the same file. ({ @link | |
842 | * M apMode#REA D_WRITE Ma pMode.READ _WRITE}) < /p></li> | |
843 | * | |
844 | * < li><p> <i> Private:</ i> Changes made to t he resulti ng buffer will not | |
845 | * b e propagat ed to the file and w ill not be visible t o other pr ograms | |
846 | * t hat have m apped the same file; instead, they will cause priv ate | |
847 | * c opies of t he modifie d portions of the bu ffer to be created. ({@link | |
848 | * MapMode#PR I D A N E S M p ode.PRIVAT E}) </p></ li> | |
849 | * | |
850 | * </u l> | |
851 | * | |
852 | * <p> For a rea d-only map ping, this channel m ust have b een opened for | |
853 | * rea ding; for a read/wri te or priv ate mappin g, this ch annel must have | |
854 | * bee n opened f or both re ading and writing. | |
855 | * | |
856 | * <p> The {@lin k MappedBy teBuffer < i>mapped b yte buffer </i>} | |
857 | * ret urned by t his method will have a positio n of zero and a limi t and | |
858 | * cap acity of < tt>size</t t>; its ma rk will be undefined . The buf fer and | |
859 | * the mapping t hat it rep resents wi ll remain valid unti l the buff er itself | |
860 | * is garbage-co llected. | |
861 | * | |
862 | * <p> A mapping , once est ablished, is not dep endent upo n the file channel | |
863 | * tha t was used to create it. Clos ing the ch annel, in particular , has no | |
864 | * eff ect upon t he validit y of the m apping. | |
865 | * | |
866 | * <p> Many of t he details of memory -mapped fi les are in herently d ependent | |
867 | * upo n the unde rlying ope rating sys tem and ar e therefor e unspecif ied. The | |
868 | * beh avior of t his method when the requested region is not comple tely | |
869 | * con tained wit hin this c hannel's f ile is uns pecified. Whether c hanges | |
870 | * mad e to the c ontent or size of th e underlyi ng file, b y this pro gram or | |
871 | * ano ther, are propagated to the bu ffer is un specified. The rate at which | |
872 | * cha nges to th e buffer a re propaga ted to the file is u nspecified . | |
873 | * | |
874 | * <p> For most operating systems, m apping a f ile into m emory is m ore | |
875 | * exp ensive tha n reading or writing a few ten s of kilob ytes of da ta via | |
876 | * the usual {@l ink #read read} and {@link #wr ite write} methods. From the | |
877 | * sta ndpoint of performan ce it is g enerally o nly worth mapping re latively | |
878 | * lar ge files i nto memory . </p> | |
879 | * | |
880 | * @pa ram mode | |
881 | * One o f the cons tants {@li nk MapMode #READ_ONLY READ_ONLY }, {@link | |
882 | * MapMo de#READ_WR ITE READ_W RITE}, or {@link Map Mode#PRIVA TE | |
883 | * PRIVA TE} define d in the { @link MapM ode} class , accordin g to | |
884 | * wheth er the fil e is to be mapped re ad-only, r ead/write, or | |
885 | * priva tely (copy -on-write) , respecti vely | |
886 | * | |
887 | * @pa ram posit ion | |
888 | * The p osition wi thin the f ile at whi ch the map ped region | |
889 | * is to start; mu st be non- negative | |
890 | * | |
891 | * @pa ram size | |
892 | * The s ize of the region to be mapped ; must be non-negati ve and | |
893 | * no gr eater than {@link ja va.lang.In teger#MAX_ VALUE} | |
894 | * | |
895 | * @re turn The mapped byt e buffer | |
896 | * | |
897 | * @th rows NonRe adableChan nelExcepti on | |
898 | * If th e <tt>mode </tt> is { @link MapM ode#READ_O NLY READ_O NLY} but | |
899 | * this channel wa s not open ed for rea ding | |
900 | * | |
901 | * @th rows NonWr itableChan nelExcepti on | |
902 | * If th e <tt>mode </tt> is { @link MapM ode#READ_W RITE READ_ WRITE} or | |
903 | * {@lin k MapMode# PRIVATE PR IVATE} but this chan nel was no t opened | |
904 | * for b oth readin g and writ ing | |
905 | * | |
906 | * @th rows Illeg alArgument Exception | |
907 | * If th e precondi tions on t he paramet ers do not hold | |
908 | * | |
909 | * @th rows IOExc eption | |
910 | * If so me other I /O error o ccurs | |
911 | * | |
912 | * @se e java.nio .channels. FileChanne l.MapMode | |
913 | * @se e java.nio .MappedByt eBuffer | |
914 | */ | |
915 | public abstract MappedByte Buffer map (MapMode m ode, | |
916 | long posi tion, long size) | |
917 | th rows IOExc eption; | |
918 | ||
919 | ||
920 | // -- Locks -- | |
921 | ||
922 | /** | |
923 | * Acq uires a lo ck on the given regi on of this channel's file. | |
924 | * | |
925 | * <p> An invoca tion of th is method will block until the region ca n be | |
926 | * loc ked, this channel is closed, o r the invo king threa d is inter rupted, | |
927 | * whi chever com es first. | |
928 | * | |
929 | * <p> If this c hannel is closed by another th read durin g an invoc ation of | |
930 | * thi s method t hen an {@l ink Asynch ronousClos eException } will be thrown. | |
931 | * | |
932 | * <p> If the in voking thr ead is int errupted w hile waiti ng to acqu ire the | |
933 | * loc k then its interrupt status wi ll be set and a {@li nk | |
934 | * Fil eLockInter ruptionExc eption} wi ll be thro wn. If th e invoker' s | |
935 | * int errupt sta tus is set when this method is invoked t hen that e xception | |
936 | * wil l be throw n immediat ely; the t hread's in terrupt st atus will not be | |
937 | * cha nged. | |
938 | * | |
939 | * <p> The regio n specifie d by the < tt>positio n</tt> and <tt>size< /tt> | |
940 | * par ameters ne ed not be contained within, or even over lap, the a ctual | |
941 | * und erlying fi le. Lock regions ar e fixed in size; if a locked r egion | |
942 | * ini tially con tains the end of the file and the file g rows beyon d the | |
943 | * reg ion then t he new por tion of th e file wil l not be c overed by the lock. | |
944 | * If a file is expected t o grow in size and a lock on t he entire file is | |
945 | * req uired then a region starting a t zero, an d no small er than th e | |
946 | * exp ected maxi mum size o f the file , should b e locked. The zero- argument | |
947 | * {@l ink #lock( )} method simply loc ks a regio n of size {@link | |
948 | * Lon g#MAX_VALU E}. | |
949 | * | |
950 | * <p> Some oper ating syst ems do not support s hared lock s, in whic h case a | |
951 | * req uest for a shared lo ck is auto matically converted into a req uest for | |
952 | * an exclusive lock. Whe ther the n ewly-acqui red lock i s shared o r | |
953 | * exc lusive may be tested by invoki ng the res ulting loc k object's {@link | |
954 | * Fil eLock#isSh ared() isS hared} met hod. | |
955 | * | |
956 | * <p> File lock s are held on behalf of the en tire Java virtual ma chine. | |
957 | * The y are not suitable f or control ling acces s to a fil e by multi ple | |
958 | * thr eads withi n the same virtual m achine. < /p> | |
959 | * | |
960 | * @pa ram posit ion | |
961 | * The p osition at which the locked re gion is to start; mu st be | |
962 | * non-n egative | |
963 | * | |
964 | * @pa ram size | |
965 | * The s ize of the locked re gion; must be non-ne gative, an d the sum | |
966 | * <tt>p osition</t t> +& nbsp;<tt>s ize</tt> m ust be non -negative | |
967 | * | |
968 | * @pa ram share d | |
969 | * <tt>t rue</tt> t o request a shared l ock, in wh ich case t his | |
970 | * chann el must be open for reading (a nd possibl y writing) ; | |
971 | * <tt>f alse</tt> to request an exclus ive lock, in which c ase this | |
972 | * chann el must be open for writing (a nd possibl y reading) | |
973 | * | |
974 | * @re turn A lo ck object representi ng the new ly-acquire d lock | |
975 | * | |
976 | * @th rows Ille galArgumen tException | |
977 | * If t he precond itions on the parame ters do no t hold | |
978 | * | |
979 | * @th rows Clos edChannelE xception | |
980 | * If t his channe l is close d | |
981 | * | |
982 | * @th rows Asyn chronousCl oseExcepti on | |
983 | * If a nother thr ead closes this chan nel while the invoki ng | |
984 | * thre ad is bloc ked in thi s method | |
985 | * | |
986 | * @th rows File LockInterr uptionExce ption | |
987 | * If t he invokin g thread i s interrup ted while blocked in this | |
988 | * meth od | |
989 | * | |
990 | * @th rows Over lappingFil eLockExcep tion | |
991 | * If a lock that overlaps the reques ted region is alread y held by | |
992 | * this Java virt ual machin e, or if a nother thr ead is alr eady | |
993 | * bloc ked in thi s method a nd is atte mpting to lock an ov erlapping | |
994 | * regi on | |
995 | * | |
996 | * @th rows NonR eadableCha nnelExcept ion | |
997 | * If < tt>shared< /tt> is <t t>true</tt > this cha nnel was n ot | |
998 | * open ed for rea ding | |
999 | * | |
1000 | * @th rows NonW ritableCha nnelExcept ion | |
1001 | * If < tt>shared< /tt> is <t t>false</t t> but thi s channel was not | |
1002 | * open ed for wri ting | |
1003 | * | |
1004 | * @th rows IOEx ception | |
1005 | * If s ome other I/O error occurs | |
1006 | * | |
1007 | * @se e #loc k() | |
1008 | * @se e #try Lock() | |
1009 | * @se e #try Lock(long, long,boole an) | |
1010 | */ | |
1011 | public abstract FileLock l ock(long p osition, l ong size, boolean sh ared) | |
1012 | th rows IOExc eption; | |
1013 | ||
1014 | /** | |
1015 | * Acq uires an e xclusive l ock on thi s channel' s file. | |
1016 | * | |
1017 | * <p> An invoca tion of th is method of the for m <tt>fc.l ock()</tt> behaves | |
1018 | * in exactly th e same way as the in vocation | |
1019 | * | |
1020 | * <pr e> | |
1021 | * fc.{@link #lock(lon g,long,boo lean) lock }(0L, Long .MAX_VALUE , false) < /pre> | |
1022 | * | |
1023 | * @re turn A lo ck object representi ng the new ly-acquire d lock | |
1024 | * | |
1025 | * @th rows Clos edChannelE xception | |
1026 | * If t his channe l is close d | |
1027 | * | |
1028 | * @th rows Asyn chronousCl oseExcepti on | |
1029 | * If a nother thr ead closes this chan nel while the invoki ng | |
1030 | * thre ad is bloc ked in thi s method | |
1031 | * | |
1032 | * @th rows File LockInterr uptionExce ption | |
1033 | * If t he invokin g thread i s interrup ted while blocked in this | |
1034 | * meth od | |
1035 | * | |
1036 | * @th rows Over lappingFil eLockExcep tion | |
1037 | * If a lock that overlaps the reques ted region is alread y held by | |
1038 | * this Java virt ual machin e, or if a nother thr ead is alr eady | |
1039 | * bloc ked in thi s method a nd is atte mpting to lock an ov erlapping | |
1040 | * regi on of the same file | |
1041 | * | |
1042 | * @th rows NonW ritableCha nnelExcept ion | |
1043 | * If t his channe l was not opened for writing | |
1044 | * | |
1045 | * @th rows IOEx ception | |
1046 | * If s ome other I/O error occurs | |
1047 | * | |
1048 | * @se e #loc k(long,lon g,boolean) | |
1049 | * @se e #try Lock() | |
1050 | * @se e #try Lock(long, long,boole an) | |
1051 | */ | |
1052 | public final Fil eLock lock () throws IOExceptio n { | |
1053 | re turn lock( 0L, Long.M AX_VALUE, false); | |
1054 | } | |
1055 | ||
1056 | /** | |
1057 | * Att empts to a cquire a l ock on the given reg ion of thi s channel' s file. | |
1058 | * | |
1059 | * <p> This meth od does no t block. An invocat ion always returns | |
1060 | * imm ediately, either hav ing acquir ed a lock on the req uested reg ion or | |
1061 | * hav ing failed to do so. If it fa ils to acq uire a loc k because an | |
1062 | * ove rlapping l ock is hel d by anoth er program then it r eturns | |
1063 | * <tt >null</tt> . If it f ails to ac quire a lo ck for any other rea son then | |
1064 | * an appropriat e exceptio n is throw n. | |
1065 | * | |
1066 | * <p> The regio n specifie d by the < tt>positio n</tt> and <tt>size< /tt> | |
1067 | * par ameters ne ed not be contained within, or even over lap, the a ctual | |
1068 | * und erlying fi le. Lock regions ar e fixed in size; if a locked r egion | |
1069 | * ini tially con tains the end of the file and the file g rows beyon d the | |
1070 | * reg ion then t he new por tion of th e file wil l not be c overed by the lock. | |
1071 | * If a file is expected t o grow in size and a lock on t he entire file is | |
1072 | * req uired then a region starting a t zero, an d no small er than th e | |
1073 | * exp ected maxi mum size o f the file , should b e locked. The zero- argument | |
1074 | * {@l ink #tryLo ck()} meth od simply locks a re gion of si ze {@link | |
1075 | * Lon g#MAX_VALU E}. | |
1076 | * | |
1077 | * <p> Some oper ating syst ems do not support s hared lock s, in whic h case a | |
1078 | * req uest for a shared lo ck is auto matically converted into a req uest for | |
1079 | * an exclusive lock. Whe ther the n ewly-acqui red lock i s shared o r | |
1080 | * exc lusive may be tested by invoki ng the res ulting loc k object's {@link | |
1081 | * Fil eLock#isSh ared() isS hared} met hod. | |
1082 | * | |
1083 | * <p> File lock s are held on behalf of the en tire Java virtual ma chine. | |
1084 | * The y are not suitable f or control ling acces s to a fil e by multi ple | |
1085 | * thr eads withi n the same virtual m achine. < /p> | |
1086 | * | |
1087 | * @pa ram posit ion | |
1088 | * The p osition at which the locked re gion is to start; mu st be | |
1089 | * non-n egative | |
1090 | * | |
1091 | * @pa ram size | |
1092 | * The s ize of the locked re gion; must be non-ne gative, an d the sum | |
1093 | * <tt>p osition</t t> +& nbsp;<tt>s ize</tt> m ust be non -negative | |
1094 | * | |
1095 | * @pa ram share d | |
1096 | * <tt>t rue</tt> t o request a shared l ock, | |
1097 | * <tt>f alse</tt> to request an exclus ive lock | |
1098 | * | |
1099 | * @re turn A lo ck object representi ng the new ly-acquire d lock, | |
1100 | * or < tt>null</t t> if the lock could not be ac quired | |
1101 | * beca use anothe r program holds an o verlapping lock | |
1102 | * | |
1103 | * @th rows Ille galArgumen tException | |
1104 | * If t he precond itions on the parame ters do no t hold | |
1105 | * | |
1106 | * @th rows Clos edChannelE xception | |
1107 | * If t his channe l is close d | |
1108 | * | |
1109 | * @th rows Over lappingFil eLockExcep tion | |
1110 | * If a lock that overlaps the reques ted region is alread y held by | |
1111 | * this Java virt ual machin e, or if a nother thr ead is alr eady | |
1112 | * bloc ked in thi s method a nd is atte mpting to lock an ov erlapping | |
1113 | * regi on of the same file | |
1114 | * | |
1115 | * @th rows IOEx ception | |
1116 | * If s ome other I/O error occurs | |
1117 | * | |
1118 | * @se e #loc k() | |
1119 | * @se e #loc k(long,lon g,boolean) | |
1120 | * @se e #try Lock() | |
1121 | */ | |
1122 | public abstract FileLock t ryLock(lon g position , long siz e, boolean shared) | |
1123 | th rows IOExc eption; | |
1124 | ||
1125 | /** | |
1126 | * Att empts to a cquire an exclusive lock on th is channel 's file. | |
1127 | * | |
1128 | * <p> An invoca tion of th is method of the for m <tt>fc.t ryLock()</ tt> | |
1129 | * beh aves in ex actly the same way a s the invo cation | |
1130 | * | |
1131 | * <pr e> | |
1132 | * fc.{@link #tryLock( long,long, boolean) t ryLock}(0L , Long.MAX _VALUE, fa lse) </pre > | |
1133 | * | |
1134 | * @re turn A lo ck object representi ng the new ly-acquire d lock, | |
1135 | * or < tt>null</t t> if the lock could not be ac quired | |
1136 | * beca use anothe r program holds an o verlapping lock | |
1137 | * | |
1138 | * @th rows Clos edChannelE xception | |
1139 | * If t his channe l is close d | |
1140 | * | |
1141 | * @th rows Over lappingFil eLockExcep tion | |
1142 | * If a lock that overlaps the reques ted region is alread y held by | |
1143 | * this Java virt ual machin e, or if a nother thr ead is alr eady | |
1144 | * bloc ked in thi s method a nd is atte mpting to lock an ov erlapping | |
1145 | * regi on | |
1146 | * | |
1147 | * @th rows IOEx ception | |
1148 | * If s ome other I/O error occurs | |
1149 | * | |
1150 | * @se e #loc k() | |
1151 | * @se e #loc k(long,lon g,boolean) | |
1152 | * @se e #try Lock(long, long,boole an) | |
1153 | */ | |
1154 | public final Fil eLock tryL ock() thro ws IOExcep tion { | |
1155 | re turn tryLo ck(0L, Lon g.MAX_VALU E, false); | |
1156 | } | |
1157 | ||
1158 | } |
Araxis Merge (but not the data content of this report) is Copyright © 1993-2016 Araxis Ltd (www.araxis.com). All rights reserved.