165. EPMO Open Source Coordination Office Redaction File Detail Report

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.

165.1 Files compared

# 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

165.2 Comparison summary

Description Between
Files 1 and 2
Text Blocks Lines
Unchanged 2 2314
Changed 1 2
Inserted 0 0
Removed 0 0

165.3 Comparison options

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

165.4 Active regular expressions

No regular expressions were active.

165.5 Comparison detail

  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;?&gt;[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;+& 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;+& 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   }