001/**
002 * Licensed to the Apache Software Foundation (ASF) under one
003 * or more contributor license agreements.  See the NOTICE file
004 * distributed with this work for additional information
005 * regarding copyright ownership.  The ASF licenses this file
006 * to you under the Apache License, Version 2.0 (the
007 * "License"); you may not use this file except in compliance
008 * with the License.  You may obtain a copy of the License at
009 *
010 *     http://www.apache.org/licenses/LICENSE-2.0
011 *
012 * Unless required by applicable law or agreed to in writing, software
013 * distributed under the License is distributed on an "AS IS" BASIS,
014 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
015 * See the License for the specific language governing permissions and
016 * limitations under the License.
017 */
018package org.apache.hadoop.hdfs;
019
020import org.apache.hadoop.classification.InterfaceAudience;
021import org.apache.hadoop.classification.InterfaceStability;
022
023import java.io.IOException;
024import java.nio.ByteBuffer;
025
026/**
027 * The public API for ReplicaAccessor objects.
028 */
029@InterfaceAudience.Public
030@InterfaceStability.Stable
031public abstract class ReplicaAccessor {
032  /**
033   * Read bytes from the replica.
034   *
035   * @param pos    The position in the replica to start reading at.
036   *                 Must not be negative.
037   * @param buf    The byte array to read into.
038   * @param off    The offset within buf to start reading into.
039   * @param len    The maximum length to read.
040   *
041   * @return       The number of bytes read.  If the read extends past the end
042   *                  of the replica, a short read count will be returned.  We
043   *                  will should return -1 if EOF is reached and no bytes
044   *                  can be returned.  We will never return a short read
045   *                  count unless EOF is reached.
046   */
047  public abstract int read(long pos, byte[] buf, int off, int len)
048      throws IOException;
049
050  /**
051   * Read bytes from the replica.
052   *
053   * @param pos    The position in the replica to start reading at.
054   *                 Must not be negative.
055   * @param buf    The byte buffer to read into.  The amount to read will be
056   *                 dictated by the remaining bytes between the current
057   *                 position and the limit.  The ByteBuffer may or may not be
058   *                 direct.
059   *
060   * @return       The number of bytes read.  If the read extends past the end
061   *                 of the replica, a short read count will be returned.  We
062   *                 should return -1 if EOF is reached and no bytes can be
063   *                 returned.  We will never return a short read count unless
064   *                 EOF is reached.
065   */
066  public abstract int read(long pos, ByteBuffer buf) throws IOException;
067
068  /**
069   * Release the resources associated with the ReplicaAccessor.
070   *
071   * It is recommended that implementations never throw an IOException.  The
072   * method is declared as throwing IOException in order to remain compatible
073   * with java.io.Closeable.  If an exception is thrown, the ReplicaAccessor
074   * must still be closed when the function returns in order to prevent a
075   * resource leak.
076   */
077  public abstract void close() throws IOException;
078
079  /**
080   * Return true if bytes read via this accessor should count towards the
081   * local byte count statistics.
082   */
083  public abstract boolean isLocal();
084
085  /**
086   * Return true if bytes read via this accessor should count towards the
087   * short-circuit byte count statistics.
088   */
089  public abstract boolean isShortCircuit();
090
091  /**
092   * Return the network distance between local machine and the remote machine.
093   */
094  public int getNetworkDistance() {
095    return isLocal() ? 0 : Integer.MAX_VALUE;
096  }
097}