800 public static class MapMode {
801
802 /**
803 * Mode for a read-only mapping.
804 */
805 public static final MapMode READ_ONLY
806 = new MapMode("READ_ONLY");
807
808 /**
809 * Mode for a read/write mapping.
810 */
811 public static final MapMode READ_WRITE
812 = new MapMode("READ_WRITE");
813
814 /**
815 * Mode for a private (copy-on-write) mapping.
816 */
817 public static final MapMode PRIVATE
818 = new MapMode("PRIVATE");
819
820 private final String name;
821
822 private MapMode(String name) {
823 this.name = name;
824 }
825
826 /**
827 * Returns a string describing this file-mapping mode.
828 *
829 * @return A descriptive string
830 */
831 public String toString() {
832 return name;
833 }
834
835 }
836
837 /**
838 * Maps a region of this channel's file directly into memory.
839 *
872 * <p> A mapping, once established, is not dependent upon the file channel
873 * that was used to create it. Closing the channel, in particular, has no
874 * effect upon the validity of the mapping.
875 *
876 * <p> Many of the details of memory-mapped files are inherently dependent
877 * upon the underlying operating system and are therefore unspecified. The
878 * behavior of this method when the requested region is not completely
879 * contained within this channel's file is unspecified. Whether changes
880 * made to the content or size of the underlying file, by this program or
881 * another, are propagated to the buffer is unspecified. The rate at which
882 * changes to the buffer are propagated to the file is unspecified.
883 *
884 * <p> For most operating systems, mapping a file into memory is more
885 * expensive than reading or writing a few tens of kilobytes of data via
886 * the usual {@link #read read} and {@link #write write} methods. From the
887 * standpoint of performance it is generally only worth mapping relatively
888 * large files into memory. </p>
889 *
890 * @param mode
891 * One of the constants {@link MapMode#READ_ONLY READ_ONLY}, {@link
892 * MapMode#READ_WRITE READ_WRITE}, or {@link MapMode#PRIVATE
893 * PRIVATE} defined in the {@link MapMode} class, according to
894 * whether the file is to be mapped read-only, read/write, or
895 * privately (copy-on-write), respectively
896 *
897 * @param position
898 * The position within the file at which the mapped region
899 * is to start; must be non-negative
900 *
901 * @param size
902 * The size of the region to be mapped; must be non-negative and
903 * no greater than {@link java.lang.Integer#MAX_VALUE}
904 *
905 * @return The mapped byte buffer
906 *
907 * @throws NonReadableChannelException
908 * If the {@code mode} is {@link MapMode#READ_ONLY READ_ONLY} but
909 * this channel was not opened for reading
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 *
|
800 public static class MapMode {
801
802 /**
803 * Mode for a read-only mapping.
804 */
805 public static final MapMode READ_ONLY
806 = new MapMode("READ_ONLY");
807
808 /**
809 * Mode for a read/write mapping.
810 */
811 public static final MapMode READ_WRITE
812 = new MapMode("READ_WRITE");
813
814 /**
815 * Mode for a private (copy-on-write) mapping.
816 */
817 public static final MapMode PRIVATE
818 = new MapMode("PRIVATE");
819
820 /**
821 * Mode for a read-only mapping from a non-volatile device.
822 */
823 public static final MapMode READ_ONLY_PERSISTENT
824 = new MapMode("READ_ONLY_PERSISTENT");
825
826 /**
827 * Mode for a read/write mapping from a non-volatile device.
828 */
829 public static final MapMode READ_WRITE_PERSISTENT
830 = new MapMode("READ_WRITE_PERSISTENT");
831
832 private final String name;
833
834 private MapMode(String name) {
835 this.name = name;
836 }
837
838 /**
839 * Returns a string describing this file-mapping mode.
840 *
841 * @return A descriptive string
842 */
843 public String toString() {
844 return name;
845 }
846
847 }
848
849 /**
850 * Maps a region of this channel's file directly into memory.
851 *
884 * <p> A mapping, once established, is not dependent upon the file channel
885 * that was used to create it. Closing the channel, in particular, has no
886 * effect upon the validity of the mapping.
887 *
888 * <p> Many of the details of memory-mapped files are inherently dependent
889 * upon the underlying operating system and are therefore unspecified. The
890 * behavior of this method when the requested region is not completely
891 * contained within this channel's file is unspecified. Whether changes
892 * made to the content or size of the underlying file, by this program or
893 * another, are propagated to the buffer is unspecified. The rate at which
894 * changes to the buffer are propagated to the file is unspecified.
895 *
896 * <p> For most operating systems, mapping a file into memory is more
897 * expensive than reading or writing a few tens of kilobytes of data via
898 * the usual {@link #read read} and {@link #write write} methods. From the
899 * standpoint of performance it is generally only worth mapping relatively
900 * large files into memory. </p>
901 *
902 * @param mode
903 * One of the constants {@link MapMode#READ_ONLY READ_ONLY}, {@link
904 * MapMode#READ_WRITE READ_WRITE}, {@link MapMode#PRIVATE
905 * PRIVATE}, {@link MapMode#READ_ONLY_PERSISTENT READ_ONLY_PERSISTENT}
906 * or {@link MapMode#READ_WRITE_PERSISTENT READ_WRITE_PERSISTENT} defined in the {@link MapMode} class, according to
907 * whether the file is to be mapped read-only, read/write, or
908 * privately (copy-on-write), read-only from a non-volatile
909 * device or read-write from a non-volatile device, respectively
910 *
911 * @param position
912 * The position within the file at which the mapped region
913 * is to start; must be non-negative
914 *
915 * @param size
916 * The size of the region to be mapped; must be non-negative and
917 * no greater than {@link java.lang.Integer#MAX_VALUE}
918 *
919 * @return The mapped byte buffer
920 *
921 * @throws NonReadableChannelException
922 * If the {@code mode} is {@link MapMode#READ_ONLY READ_ONLY} or
923 * {@link MapMode#READ_ONLY_PERSISTENT READ_ONLY_PERSISTENT} but
924 * this channel was not opened for reading
925 *
926 * @throws NonWritableChannelException
927 * If the {@code mode} is {@link MapMode#READ_WRITE READ_WRITE},
928 * {@link MapMode#PRIVATE PRIVATE} or {@link MapMode#READ_WRITE_PERSISTENT READ_WRITE_PERSISTENT}
929 * but this channel was not opened for both reading and writing
930 *
931 * @throws IllegalArgumentException
932 * If the preconditions on the parameters do not hold
933 *
934 * @throws IOException
935 * If some other I/O error occurs
936 *
937 * @see java.nio.channels.FileChannel.MapMode
938 * @see java.nio.MappedByteBuffer
939 */
940 public abstract MappedByteBuffer map(MapMode mode,
941 long position, long size)
942 throws IOException;
943
944
945 // -- Locks --
946
947 /**
948 * Acquires a lock on the given region of this channel's file.
949 *
|