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 }