< prev index next >

src/java.base/share/classes/java/nio/channels/FileChannel.java

Print this page




 774      *
 775      * @throws  AsynchronousCloseException
 776      *          If another thread closes this channel
 777      *          while the write operation is in progress
 778      *
 779      * @throws  ClosedByInterruptException
 780      *          If another thread interrupts the current thread
 781      *          while the write operation is in progress, thereby
 782      *          closing the channel and setting the current thread's
 783      *          interrupt status
 784      *
 785      * @throws  IOException
 786      *          If some other I/O error occurs
 787      */
 788     public abstract int write(ByteBuffer src, long position) throws IOException;
 789 
 790 
 791     // -- Memory-mapped buffers --
 792 
 793     /**
 794      * A file-mapping mode.
 795      *
 796      * @since 1.4
 797      *
 798      * @see java.nio.channels.FileChannel#map
 799      */
 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         /**
 823          * Constructs an instance of this class. This constructor may be used
 824          * by code in java.base to create file mapping modes beyond the file
 825          * mapping modes defined here.
 826          * @param name the name of the map mode
 827          */
 828         private MapMode(String name) {
 829             this.name = name;
 830         }
 831 
 832         /**
 833          * Returns a string describing this file-mapping mode.
 834          *
 835          * @return  A descriptive string
 836          */
 837         public String toString() {
 838             return name;
 839         }
 840 
 841     }
 842 
 843     /**
 844      * Maps a region of this channel's file directly into memory.
 845      *
 846      * <p> The {@code mode} parameter specifies how the region of the file is
 847      * mapped and may be one of the following modes:
 848      *
 849      * <ul>
 850      *
 851      *   <li><p> <i>Read-only:</i> Any attempt to modify the resulting buffer
 852      *   will cause a {@link java.nio.ReadOnlyBufferException} to be thrown.
 853      *   ({@link MapMode#READ_ONLY MapMode.READ_ONLY}) </p></li>
 854      *
 855      *   <li><p> <i>Read/write:</i> Changes made to the resulting buffer will
 856      *   eventually be propagated to the file; they may or may not be made
 857      *   visible to other programs that have mapped the same file.  ({@link
 858      *   MapMode#READ_WRITE MapMode.READ_WRITE}) </p></li>
 859      *
 860      *   <li><p> <i>Private:</i> Changes made to the resulting buffer will not
 861      *   be propagated to the file and will not be visible to other programs
 862      *   that have mapped the same file; instead, they will cause private
 863      *   copies of the modified portions of the buffer to be created.  ({@link
 864      *   MapMode#PRIVATE MapMode.PRIVATE}) </p></li>
 865      *
 866      * </ul>
 867      *
 868      * <p> An implementation may support additional map modes.
 869      *
 870      * <p> For a read-only mapping, this channel must have been opened for
 871      * reading; for a read/write or private mapping, this channel must have
 872      * been opened for both reading and writing.
 873      *
 874      * <p> The {@link MappedByteBuffer <i>mapped byte buffer</i>}
 875      * returned by this method will have a position of zero and a limit and
 876      * capacity of {@code size}; its mark will be undefined.  The buffer and
 877      * the mapping that it represents will remain valid until the buffer itself
 878      * is garbage-collected.
 879      *
 880      * <p> A mapping, once established, is not dependent upon the file channel
 881      * that was used to create it.  Closing the channel, in particular, has no
 882      * effect upon the validity of the mapping.
 883      *
 884      * <p> Many of the details of memory-mapped files are inherently dependent
 885      * upon the underlying operating system and are therefore unspecified.  The
 886      * behavior of this method when the requested region is not completely
 887      * contained within this channel's file is unspecified.  Whether changes
 888      * made to the content or size of the underlying file, by this program or
 889      * another, are propagated to the buffer is unspecified.  The rate at which
 890      * changes to the buffer are propagated to the file is unspecified.
 891      *
 892      * <p> For most operating systems, mapping a file into memory is more
 893      * expensive than reading or writing a few tens of kilobytes of data via
 894      * the usual {@link #read read} and {@link #write write} methods.  From the
 895      * standpoint of performance it is generally only worth mapping relatively
 896      * large files into memory.  </p>
 897      *
 898      * @param  mode
 899      *         One of the constants {@link MapMode#READ_ONLY READ_ONLY}, {@link
 900      *         MapMode#READ_WRITE READ_WRITE}, or {@link MapMode#PRIVATE
 901      *         PRIVATE} defined in the {@link MapMode} class, according to
 902      *         whether the file is to be mapped read-only, read/write, or
 903      *         privately (copy-on-write), respectively, or an implementation
 904      *         specific map mode
 905      *
 906      * @param  position
 907      *         The position within the file at which the mapped region
 908      *         is to start; must be non-negative
 909      *
 910      * @param  size
 911      *         The size of the region to be mapped; must be non-negative and
 912      *         no greater than {@link java.lang.Integer#MAX_VALUE}
 913      *
 914      * @return  The mapped byte buffer
 915      *
 916      * @throws NonReadableChannelException
 917      *         If the {@code mode} is {@link MapMode#READ_ONLY READ_ONLY} or
 918      *         an implementation specific map mode requiring read access
 919      *         but this channel was not opened for reading
 920      *
 921      * @throws NonWritableChannelException
 922      *         If the {@code mode} is {@link MapMode#READ_WRITE READ_WRITE}.
 923      *         {@link MapMode#PRIVATE PRIVATE} or an implementation specific
 924      *         map mode requiring write access but this channel was not
 925      *         opened for both reading and writing
 926      *
 927      * @throws IllegalArgumentException
 928      *         If the preconditions on the parameters do not hold
 929      *
 930      * @throws UnsupportedOperationException
 931      *         If an unsupported map mode is specified
 932      *
 933      * @throws IOException
 934      *         If some other I/O error occurs
 935      *
 936      * @see java.nio.channels.FileChannel.MapMode
 937      * @see java.nio.MappedByteBuffer
 938      */
 939     public abstract MappedByteBuffer map(MapMode mode, long position, long size)

 940         throws IOException;
 941 
 942 
 943     // -- Locks --
 944 
 945     /**
 946      * Acquires a lock on the given region of this channel's file.
 947      *
 948      * <p> An invocation of this method will block until the region can be
 949      * locked, this channel is closed, or the invoking thread is interrupted,
 950      * whichever comes first.
 951      *
 952      * <p> If this channel is closed by another thread during an invocation of
 953      * this method then an {@link AsynchronousCloseException} will be thrown.
 954      *
 955      * <p> If the invoking thread is interrupted while waiting to acquire the
 956      * lock then its interrupt status will be set and a {@link
 957      * FileLockInterruptionException} will be thrown.  If the invoker's
 958      * interrupt status is set when this method is invoked then that exception
 959      * will be thrown immediately; the thread's interrupt status will not be




 774      *
 775      * @throws  AsynchronousCloseException
 776      *          If another thread closes this channel
 777      *          while the write operation is in progress
 778      *
 779      * @throws  ClosedByInterruptException
 780      *          If another thread interrupts the current thread
 781      *          while the write operation is in progress, thereby
 782      *          closing the channel and setting the current thread's
 783      *          interrupt status
 784      *
 785      * @throws  IOException
 786      *          If some other I/O error occurs
 787      */
 788     public abstract int write(ByteBuffer src, long position) throws IOException;
 789 
 790 
 791     // -- Memory-mapped buffers --
 792 
 793     /**
 794      * A typesafe enumeration for file-mapping modes.
 795      *
 796      * @since 1.4
 797      *
 798      * @see java.nio.channels.FileChannel#map
 799      */
 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      *
 840      * <p> A region of a file may be mapped into memory in one of three modes:
 841      * </p>
 842      *
 843      * <ul>
 844      *
 845      *   <li><p> <i>Read-only:</i> Any attempt to modify the resulting buffer
 846      *   will cause a {@link java.nio.ReadOnlyBufferException} to be thrown.
 847      *   ({@link MapMode#READ_ONLY MapMode.READ_ONLY}) </p></li>
 848      *
 849      *   <li><p> <i>Read/write:</i> Changes made to the resulting buffer will
 850      *   eventually be propagated to the file; they may or may not be made
 851      *   visible to other programs that have mapped the same file.  ({@link
 852      *   MapMode#READ_WRITE MapMode.READ_WRITE}) </p></li>
 853      *
 854      *   <li><p> <i>Private:</i> Changes made to the resulting buffer will not
 855      *   be propagated to the file and will not be visible to other programs
 856      *   that have mapped the same file; instead, they will cause private
 857      *   copies of the modified portions of the buffer to be created.  ({@link
 858      *   MapMode#PRIVATE MapMode.PRIVATE}) </p></li>
 859      *
 860      * </ul>
 861      *


 862      * <p> For a read-only mapping, this channel must have been opened for
 863      * reading; for a read/write or private mapping, this channel must have
 864      * been opened for both reading and writing.
 865      *
 866      * <p> The {@link MappedByteBuffer <i>mapped byte buffer</i>}
 867      * returned by this method will have a position of zero and a limit and
 868      * capacity of {@code size}; its mark will be undefined.  The buffer and
 869      * the mapping that it represents will remain valid until the buffer itself
 870      * is garbage-collected.
 871      *
 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      *
 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


< prev index next >