Summary

Overload MappedByteBuffer.force to specify a subregion of the mapped buffer to be written back to persistent storage.

Problem

The current force method only supports writeback of a buffer's full mapped region. Selective writeback will be more efficient for some current use cases where a buffer is backed by a disk file. It will be much more efficient for the new use case proposed in JEP 352 where the buffer is backed by NVRAM.

Solution

Overload the method to allow a region of the buffer to be specified and provide an implementation

Specification

Add the following new method with associated javadoc

/**
 * Forces any changes made to a region of this buffer's content to
 * be written to the storage device containing the mapped
 * file. The region starts at the given {@code index} in this
 * buffer and is {@code length} bytes.
 *
 * <p> If the file mapped into this buffer resides on a local
 * storage device then when this method returns it is guaranteed
 * that all changes made to the selected region buffer since it
 * was created, or since this method was last invoked, will have
 * been written to that device. The force operation is free to
 * write bytes that lie outside the specified region, for example
 * to ensure that data blocks of some device-specific granularity
 * are transferred in their entirety.
 *
 * <p> If the file does not reside on a local device then no such
 * guarantee is made.
 *
 * <p> If this buffer was not mapped in read/write mode ({@link
 * java.nio.channels.FileChannel.MapMode#READ_WRITE}) then
 * invoking this method has no effect. </p>
 *
 * @param index
 *        The index of the first byte in the buffer region that is
 *        to be written back to storage; must be non-negative
 *        and less than limit()
 *
 * @param length
 *        The length of the region in bytes; must be non-negative
 *        and no larger than limit() - index
 *
 * @throws IndexOutOfBoundsException
 *         if the preconditions on the index and length do not
 *         hold.
 *
 * @return  This buffer
 *
 * @since 13
 */
public final MappedByteBuffer force(int index, int length)
. . .