org.apache.hadoop.fs.HasEnhancedByteBufferAccess.java Source code

Introduction

Here is the source code for org.apache.hadoop.fs.HasEnhancedByteBufferAccess.java

Source

/**
 * Licensed to the Apache Software Foundation (ASF) under one
 * or more contributor license agreements.  See the NOTICE file
 * distributed with this work for additional information
 * regarding copyright ownership.  The ASF licenses this file
 * to you under the Apache License, Version 2.0 (the
 * "License"); you may not use this file except in compliance
 * with the License.  You may obtain a copy of the License at
 *
 *     http://www.apache.org/licenses/LICENSE-2.0
 *
 * Unless required by applicable law or agreed to in writing, software
 * distributed under the License is distributed on an "AS IS" BASIS,
 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
 * See the License for the specific language governing permissions and
 * limitations under the License.
 */

package org.apache.hadoop.fs;

import java.io.IOException;
import java.nio.ByteBuffer;
import java.util.EnumSet;

import org.apache.hadoop.classification.InterfaceAudience;
import org.apache.hadoop.classification.InterfaceStability;
import org.apache.hadoop.io.ByteBufferPool;

/**
 * FSDataInputStreams implement this interface to provide enhanced
 * byte buffer access.  Usually this takes the form of mmap support.
 */
@InterfaceAudience.Private
@InterfaceStability.Evolving
public interface HasEnhancedByteBufferAccess {
    /**
     * Get a ByteBuffer containing file data.
     *
     * This ByteBuffer may come from the stream itself, via a call like mmap,
     * or it may come from the ByteBufferFactory which is passed in as an
     * argument.
     *
     * @param factory
     *            If this is non-null, it will be used to create a fallback
     *            ByteBuffer when the stream itself cannot create one.
     * @param maxLength
     *            The maximum length of buffer to return.  We may return a buffer
     *            which is shorter than this.
     * @param opts
     *            Options to use when reading.
     *
     * @return
     *            We will always return an empty buffer if maxLength was 0,
     *            whether or not we are at EOF.
     *            If maxLength > 0, we will return null if the stream has
     *            reached EOF.
     *            Otherwise, we will return a ByteBuffer containing at least one 
     *            byte.  You must free this ByteBuffer when you are done with it 
     *            by calling releaseBuffer on it.  The buffer will continue to be
     *            readable until it is released in this manner.  However, the
     *            input stream's close method may warn about unclosed buffers.
     * @throws
     *            IOException: if there was an error reading.
     *            UnsupportedOperationException: if factory was null, and we
     *            needed an external byte buffer.  UnsupportedOperationException
     *            will never be thrown unless the factory argument is null.
     */
    public ByteBuffer read(ByteBufferPool factory, int maxLength, EnumSet<ReadOption> opts)
            throws IOException, UnsupportedOperationException;

    /**
     * Release a ByteBuffer which was created by the enhanced ByteBuffer read
     * function. You must not continue using the ByteBuffer after calling this 
     * function.
     *
     * @param buffer
     *            The ByteBuffer to release.
     */
    public void releaseBuffer(ByteBuffer buffer);
}