910 *
911 * @throws NonWritableChannelException
912 * If the {@code mode} is {@link MapMode#READ_WRITE READ_WRITE} or
913 * {@link MapMode#PRIVATE PRIVATE} but this channel was not opened
914 * for both reading and writing
915 *
916 * @throws IllegalArgumentException
917 * If the preconditions on the parameters do not hold
918 *
919 * @throws IOException
920 * If some other I/O error occurs
921 *
922 * @see java.nio.channels.FileChannel.MapMode
923 * @see java.nio.MappedByteBuffer
924 */
925 public abstract MappedByteBuffer map(MapMode mode,
926 long position, long size)
927 throws IOException;
928
929
930 // -- Locks --
931
932 /**
933 * Acquires a lock on the given region of this channel's file.
934 *
935 * <p> An invocation of this method will block until the region can be
936 * locked, this channel is closed, or the invoking thread is interrupted,
937 * whichever comes first.
938 *
939 * <p> If this channel is closed by another thread during an invocation of
940 * this method then an {@link AsynchronousCloseException} will be thrown.
941 *
942 * <p> If the invoking thread is interrupted while waiting to acquire the
943 * lock then its interrupt status will be set and a {@link
944 * FileLockInterruptionException} will be thrown. If the invoker's
945 * interrupt status is set when this method is invoked then that exception
946 * will be thrown immediately; the thread's interrupt status will not be
947 * changed.
948 *
949 * <p> The region specified by the {@code position} and {@code size}
|
910 *
911 * @throws NonWritableChannelException
912 * If the {@code mode} is {@link MapMode#READ_WRITE READ_WRITE} or
913 * {@link MapMode#PRIVATE PRIVATE} but this channel was not opened
914 * for both reading and writing
915 *
916 * @throws IllegalArgumentException
917 * If the preconditions on the parameters do not hold
918 *
919 * @throws IOException
920 * If some other I/O error occurs
921 *
922 * @see java.nio.channels.FileChannel.MapMode
923 * @see java.nio.MappedByteBuffer
924 */
925 public abstract MappedByteBuffer map(MapMode mode,
926 long position, long size)
927 throws IOException;
928
929
930 /**
931 * Maps a region of this channel's file directly into memory. This
932 * method operates in much the same way as method #map() except
933 * that the it expects the file to be associated with a persistent
934 * memory device.
935 *
936 * <p> A region of a file may be mapped into memory in one of two modes:
937 * </p>
938 *
939 * <ul>
940 *
941 * <li><p> <i>Read-only:</i> Any attempt to modify the resulting buffer
942 * will cause a {@link java.nio.ReadOnlyBufferException} to be thrown.
943 * ({@link MapMode#READ_ONLY MapMode.READ_ONLY}) </p></li>
944 *
945 * <li><p> <i>Read/write:</i> Changes made to the resulting buffer will
946 * eventually be propagated to the file; they may or may not be made
947 * visible to other programs that have mapped the same file. ({@link
948 * MapMode#READ_WRITE MapMode.READ_WRITE}) </p></li>
949 * </ul>
950 *
951 * <p> For a read-only mapping, this channel must have been opened for
952 * reading; for a read/write or private mapping, this channel must have
953 * been opened for both reading and writing.
954 *
955 * <p> The {@link MappedByteBuffer <i>mapped byte buffer</i>}
956 * returned by this method will have a position of zero and a limit and
957 * capacity of {@code size}; its mark will be undefined. The buffer and
958 * the mapping that it represents will remain valid until the buffer itself
959 * is garbage-collected.
960 *
961 * <p> A mapping, once established, is not dependent upon the file channel
962 * that was used to create it. Closing the channel, in particular, has no
963 * effect upon the validity of the mapping.
964 *
965 * <p> Many of the details of memory-mapped files are inherently dependent
966 * upon the underlying operating system and are therefore unspecified. The
967 * behavior of this method when the requested region is not completely
968 * contained within this channel's file is unspecified.
969 *
970 * <p>Writes to the buffer will not necessarily be written back
971 * immediately from cache to persistent memory. However, writeback
972 * may be guaranteed by calling the buffer's force method ({@link
973 * java.nio.MappedByteBuffer#force
974 * java.nio.MappedByteBuffer.force()}). Buffer get and put
975 * operations should be much faster than the usual {@link #read
976 * read} and {@link #write write} methods.
977 *
978 * @param mode
979
980 * One of the constants {@link MapMode#READ_ONLY
981 * READ_ONLY}, {@link MapMode#READ_WRITE READ_WRITE}
982 * defined in the {@link MapMode} class, according to
983 * whether the file is to be mapped read-only or
984 * read/write. Mode {@link MapMode#PRIVATE PRIVATE} is
985 * not allowed for a persistent mapped buffer.
986 *
987 * @param position
988 * The position within the file at which the mapped region
989 * is to start; must be non-negative
990 *
991 * @param size
992 * The size of the region to be mapped; must be non-negative and
993 * no greater than {@link java.lang.Integer#MAX_VALUE}
994 *
995 * @return The mapped byte buffer
996 *
997 * @throws NonReadableChannelException
998 * If the {@code mode} is {@link MapMode#READ_ONLY READ_ONLY} but
999 * this channel was not opened for reading
1000 *
1001 * @throws NonWritableChannelException
1002 * If the {@code mode} is {@link MapMode#READ_WRITE READ_WRITE} or
1003 * {@link MapMode#PRIVATE PRIVATE} but this channel was not opened
1004 * for both reading and writing
1005 *
1006 * @throws IllegalArgumentException
1007 * If the preconditions on the parameters do not hold
1008 *
1009 * @throws IOException
1010 * If some other I/O error occurs
1011 *
1012 * @see java.nio.channels.FileChannel.MapMode
1013 * @see java.nio.MappedByteBuffer
1014 */
1015 public MappedByteBuffer map_persistent(MapMode mode,
1016 long position, long size)
1017 throws IOException
1018 {
1019 // a default implementation is needed so that subclasses of
1020 // FileChannel created before this API was added fail
1021 // appropriately.
1022 throw new IOException("Unsupported operation: map_persistent");
1023 }
1024
1025
1026 // -- Locks --
1027
1028 /**
1029 * Acquires a lock on the given region of this channel's file.
1030 *
1031 * <p> An invocation of this method will block until the region can be
1032 * locked, this channel is closed, or the invoking thread is interrupted,
1033 * whichever comes first.
1034 *
1035 * <p> If this channel is closed by another thread during an invocation of
1036 * this method then an {@link AsynchronousCloseException} will be thrown.
1037 *
1038 * <p> If the invoking thread is interrupted while waiting to acquire the
1039 * lock then its interrupt status will be set and a {@link
1040 * FileLockInterruptionException} will be thrown. If the invoker's
1041 * interrupt status is set when this method is invoked then that exception
1042 * will be thrown immediately; the thread's interrupt status will not be
1043 * changed.
1044 *
1045 * <p> The region specified by the {@code position} and {@code size}
|