001    /* FileChannel.java --
002       Copyright (C) 2002 Free Software Foundation, Inc.
003    
004    This file is part of GNU Classpath.
005    
006    GNU Classpath is free software; you can redistribute it and/or modify
007    it under the terms of the GNU General Public License as published by
008    the Free Software Foundation; either version 2, or (at your option)
009    any later version.
010    
011    GNU Classpath is distributed in the hope that it will be useful, but
012    WITHOUT ANY WARRANTY; without even the implied warranty of
013    MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
014    General Public License for more details.
015    
016    You should have received a copy of the GNU General Public License
017    along with GNU Classpath; see the file COPYING.  If not, write to the
018    Free Software Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA
019    02110-1301 USA.
020    
021    Linking this library statically or dynamically with other modules is
022    making a combined work based on this library.  Thus, the terms and
023    conditions of the GNU General Public License cover the whole
024    combination.
025    
026    As a special exception, the copyright holders of this library give you
027    permission to link this library with independent modules to produce an
028    executable, regardless of the license terms of these independent
029    modules, and to copy and distribute the resulting executable under
030    terms of your choice, provided that you also meet, for each linked
031    independent module, the terms and conditions of the license of that
032    module.  An independent module is a module which is not derived from
033    or based on this library.  If you modify this library, you may extend
034    this exception to your version of the library, but you are not
035    obligated to do so.  If you do not wish to do so, delete this
036    exception statement from your version. */
037    
038    package java.nio.channels;
039    
040    import java.io.IOException;
041    import java.nio.ByteBuffer;
042    import java.nio.MappedByteBuffer;
043    import java.nio.channels.spi.AbstractInterruptibleChannel;
044    
045    
046    /**
047     * @author Michael Koch
048     * @since 1.4
049     */
050    public abstract class FileChannel extends AbstractInterruptibleChannel
051      implements ByteChannel, GatheringByteChannel, ScatteringByteChannel
052    {
053      public static class MapMode
054      {
055        int m;
056        public static final MapMode READ_ONLY = new MapMode(0);
057        public static final MapMode READ_WRITE = new MapMode(1);
058        public static final MapMode PRIVATE = new MapMode(2);
059    
060        /**
061         * Initializes the MapMode.
062         */
063        MapMode(int a)
064        {
065          m = a;
066        }
067    
068        /**
069         * Returns a string representation of the <code>MapMode</code> object.
070         */
071        public String toString()
072        {
073          if (this == READ_ONLY)
074            return "READ_ONLY";
075          else if (this == READ_WRITE)
076            return "READ_WRITE";
077    
078          return "PRIVATE";
079        }
080      }
081    
082      /**
083       * Initializes the channel.
084       */
085      protected FileChannel()
086      {
087      }
088    
089      /**
090       * Maps the file into the memory.
091       *
092       * @exception IllegalArgumentException If the preconditions on the parameters
093       * do not hold.
094       * @exception IOException If an I/O error occurs.
095       * @exception NonReadableChannelException If mode is READ_ONLY but this channel was
096       * not opened for reading.
097       * @exception NonWritableChannelException If mode is READ_WRITE or PRIVATE but this
098       * channel was not opened for writing.
099       */
100      public abstract MappedByteBuffer map(MapMode mode, long position, long size)
101        throws IOException;
102    
103      /**
104       * Return the size of the file thus far
105       *
106       * @exception ClosedChannelException If this channel is closed.
107       */
108      public abstract long size() throws IOException;
109    
110      /**
111       * Writes data to the channel.
112       *
113       * @exception IOException If an I/O error occurs.
114       */
115      public final long write(ByteBuffer[] srcs) throws IOException
116      {
117        return write(srcs, 0, srcs.length);
118      }
119    
120      /**
121       * Writes data to the channel.
122       *
123       * @exception IOException If an I/O error occurs.
124       */
125      public abstract int write(ByteBuffer src) throws IOException;
126    
127      /**
128       * Writes data to the channel.
129       *
130       * @exception AsynchronousCloseException If another thread closes this channel
131       * while the transfer is in progress.
132       * @exception ClosedByInterruptException If another thread interrupts the
133       * current thread while the transfer is in progress, thereby closing both
134       * channels and setting the current thread's interrupt status.
135       * @exception ClosedChannelException If this channel is closed.
136       * @exception IllegalArgumentException If position is negative.
137       * @exception IOException If an I/O error occurs.
138       * @exception NonWritableChannelException If this channel was not opened for
139       * writing.
140       */
141      public abstract int write(ByteBuffer srcs, long position)
142        throws IOException;
143    
144      /**
145       * Writes data to the channel.
146       *
147       * @exception IOException If an I/O error occurs.
148       */
149      public abstract long write(ByteBuffer[] srcs, int offset, int length)
150        throws IOException;
151    
152      /**
153       * Reads data from the channel.
154       *
155       * @exception IOException If an I/O error occurs.
156       */
157      public abstract long read(ByteBuffer[] dsts, int offset, int length)
158        throws IOException;
159    
160      /**
161       * Reads data from the channel.
162       *
163       * @exception IOException If an I/O error occurs.
164       */
165      public final long read(ByteBuffer[] dsts) throws IOException
166      {
167        return read(dsts, 0, dsts.length);
168      }
169    
170      /**
171       * Reads data from the channel.
172       *
173       * @exception IOException If an I/O error occurs.
174       */
175      public abstract int read(ByteBuffer dst) throws IOException;
176    
177      /**
178       * Reads data from the channel.
179       *
180       * @exception AsynchronousCloseException If another thread closes this channel
181       * while the transfer is in progress.
182       * @exception ClosedByInterruptException If another thread interrupts the
183       * current thread while the transfer is in progress, thereby closing both
184       * channels and setting the current thread's interrupt status.
185       * @exception ClosedChannelException If this channel is closed.
186       * @exception IllegalArgumentException If position is negative.
187       * @exception IOException If an I/O error occurs.
188       * @exception NonReadableChannelException If this channel was not opened for
189       * reading.
190       */
191      public abstract int read(ByteBuffer dst, long position)
192        throws IOException;
193    
194      /**
195       * Closes the channel.
196       *
197       * This is called from @see close.
198       *
199       * @exception IOException If an I/O error occurs.
200       */
201      protected abstract void implCloseChannel() throws IOException;
202    
203      /**
204       * msync with the disk
205       *
206       * @exception ClosedChannelException If this channel is closed.
207       * @exception IOException If an I/O error occurs.
208       */
209      public abstract void force(boolean metaData) throws IOException;
210    
211      /**
212       * Creates a file lock for the whole associated file.
213       *
214       * @exception AsynchronousCloseException If another thread closes this channel
215       * while the transfer is in progress.
216       * @exception ClosedChannelException If this channel is closed.
217       * @exception FileLockInterruptionException If the invoking thread is
218       * interrupted while blocked in this method.
219       * @exception IOException If an I/O error occurs.
220       * @exception NonReadableChannelException If shared is true and this channel
221       * was not opened for reading.
222       * @exception NonWritableChannelException If shared is false and this channel
223       * was not opened for writing.
224       * @exception OverlappingFileLockException If a lock that overlaps the
225       * requested region is already held by this Java virtual machine, or if
226       * another thread is already blocked in this method and is attempting to lock
227       * an overlapping region.
228       */
229      public final FileLock lock() throws IOException
230      {
231        return lock(0, Long.MAX_VALUE, false);
232      }
233    
234      /**
235       * Creates a file lock for a region of the associated file.
236       *
237       * @exception AsynchronousCloseException If another thread closes this channel
238       * while the transfer is in progress.
239       * @exception ClosedChannelException If this channel is closed.
240       * @exception FileLockInterruptionException If the invoking thread is
241       * interrupted while blocked in this method.
242       * @exception IllegalArgumentException If the preconditions on the parameters
243       * do not hold.
244       * @exception IOException If an I/O error occurs.
245       * @exception OverlappingFileLockException If a lock that overlaps the
246       * requested region is already held by this Java virtual machine, or if
247       * another thread is already blocked in this method and is attempting to lock
248       * an overlapping region.
249       * @exception NonReadableChannelException If shared is true and this channel
250       * was not opened for reading.
251       * @exception NonWritableChannelException If shared is false and this channel
252       * was not opened for writing.
253       */
254      public abstract FileLock lock(long position, long size, boolean shared)
255        throws IOException;
256    
257      /**
258       * Tries to aqquire alock on the whole associated file.
259       *
260       * @exception ClosedChannelException If this channel is closed.
261       * @exception IOException If an I/O error occurs.
262       * @exception OverlappingFileLockException If a lock that overlaps the
263       * requested region is already held by this Java virtual machine, or if
264       * another thread is already blocked in this method and is attempting to lock
265       * an overlapping region.
266       */
267      public final FileLock tryLock() throws IOException
268      {
269        return tryLock(0, Long.MAX_VALUE, false);
270      }
271    
272      /**
273       * Tries to aqquire a lock on a region of the associated file.
274       *
275       * @exception ClosedChannelException If this channel is closed.
276       * @exception IllegalArgumentException If the preconditions on the parameters
277       * do not hold.
278       * @exception IOException If an I/O error occurs.
279       * @exception OverlappingFileLockException If a lock that overlaps the
280       * requested region is already held by this Java virtual machine, or if
281       * another thread is already blocked in this method and is attempting to lock
282       * an overlapping region.
283       */
284      public abstract FileLock tryLock(long position, long size, boolean shared)
285        throws IOException;
286    
287      /**
288       * Returns the current position on the file.
289       *
290       * @exception ClosedChannelException If this channel is closed.
291       * @exception IOException If an I/O error occurs.
292       */
293      public abstract long position() throws IOException;
294    
295      /**
296       * Sets the position of the channel on the assoziated file.
297       *
298       * @exception ClosedChannelException If this channel is closed.
299       * @exception IllegalArgumentException If newPosition is negative.
300       * @exception IOException If an I/O error occurs.
301       */
302      public abstract FileChannel position(long newPosition)
303        throws IOException;
304    
305      /**
306       * Transfers bytes from this channel's file to the given writable byte
307       * channel.
308       *
309       * @exception AsynchronousCloseException If another thread closes this channel
310       * while the transfer is in progress.
311       * @exception ClosedByInterruptException If another thread interrupts the
312       * current thread while the transfer is in progress, thereby closing both
313       * channels and setting the current thread's interrupt status.
314       * @exception ClosedChannelException If this channel is closed.
315       * @exception IllegalArgumentException If the preconditions on the parameters
316       * do not hold.
317       * @exception IOException If an I/O error occurs.
318       * @exception NonReadableChannelException If this channel was not opened for
319       * reading.
320       * @exception NonWritableChannelException If the target channel was not
321       * opened for writing.
322       */
323      public abstract long transferTo(long position, long count,
324                                      WritableByteChannel target)
325        throws IOException;
326    
327      /**
328       * Transfers bytes from the given readable channel into this channel.
329       *
330       * @exception AsynchronousCloseException If another thread closes this channel
331       * while the transfer is in progress.
332       * @exception ClosedByInterruptException If another thread interrupts the
333       * current thread while the transfer is in progress, thereby closing both
334       * channels and setting the current thread's interrupt status.
335       * @exception ClosedChannelException If this channel is closed.
336       * @exception IllegalArgumentException If the preconditions on the parameters
337       * do not hold.
338       * @exception IOException If an I/O error occurs.
339       * @exception NonReadableChannelException If the source channel was not
340       * opened for reading.
341       * @exception NonWritableChannelException If this channel was not opened for
342       * writing.
343       */
344      public abstract long transferFrom(ReadableByteChannel src, long position,
345                                        long count) throws IOException;
346    
347      /**
348       * Truncates the channel's file at <code>size</code>.
349       *
350       * @exception ClosedChannelException If this channel is closed.
351       * @exception IllegalArgumentException If size is negative.
352       * @exception IOException If an I/O error occurs.
353       * @exception NonWritableChannelException If this channel was not opened for
354       * writing.
355       */
356      public abstract FileChannel truncate(long size) throws IOException;
357    }