content: /*
   * 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 com.aliyun.odps.io;
  
  import java.io.DataInput;
  import java.io.DataInputStream;
  import java.io.IOException;
  import java.io.InputStream;
  
  /**
   * BlobDataInputStream是blob列类型的读取流，只能通过
   * {@link InputBlobWritable#getInputStream()} 接口获得该对象。
   *
   * <p>
   * BlobDataInputStream 继承自 {@link DataInputStream}，提供了 {@link DataInput}的实现。
   *
   * <p>
   * 代码示例:
   *
   * <pre>
   * BlobDataInputStream in = inputBlobWritable.getInputStream();
   * 使用in.read读取字节数组
   * 使用in.readType读取java基本数据类型
   * in.close();
   * </pre>
   *
   * @see DataInputStream
   * @see InputBlobWritable#getInputStream()
   */
  public abstract class BlobDataInputStream extends DataInputStream {
  
    /**
     * BlobDataInputStream在seek时的位置标志
     *
     * <pre>
     * SET 起始位置
     * CUR 当前位置
     * END 末尾位置
     * </pre>
     */
    public enum SeekFlag {
      SET, CUR, END,
    }
  
    ;
  
    /**
     * 构建BlobDataInputStream对象
     *
     * @param in
     *     基本的数据输入流
     */
    public BlobDataInputStream(InputStream in) {
      super(in);
    }
  
    /**
     * 将BlobDataInputStream的位置定位到指定位置
     *
     * @param offset
     *     偏移
     * @param seekFlag
     *     相对位置
     * @throws IOException
     */
    public abstract void seek(long offset, SeekFlag seekFlag) throws IOException;
  
    /**
     * 获取当前位置
     *
     * @return BlobDataInputStream的当前位置
     * @throws IOException
     */
    public abstract long getPos() throws IOException;
  
    /**
     * 从指定位置读取指定长度的字节
     *
     * @param position
     *     BlobDataInputStream的绝对位置
     * @param buffer
     *     读取的字节要放入的缓存
     * @param offset
     *     缓存的其实位置
     * @param length
     *     待读取的字节数
     * @return 实际读取的字节数，－1表示没有可读取的字节
     * @throws IOException
     */
    public abstract int read(long position, byte[] buffer, int offset, int length)
        throws IOException;
  
    /**
     * 从指定位置读取length个字节
     *
     * @param position
     *     BlobDataInputStream的绝对位置
     * @param buffer
     *     读取的字节要放入的缓存
     * @param offset
     *     缓存的起始位置
     * @param length
     *     待读取的字节数
     * @throws IOException
     *     剩余的字节数小于length时
     */
    public abstract void readFully(long position, byte[] buffer, int offset,
                                   int length) throws IOException;
  
    /**
     * 从指定读取字节，填充满buffer传存
     *
     * @param position
     *     BlobDataInputStream的绝对位置
     * @param buffer
     *     读取的字节要放入的缓存
     * @throws IOException
     *     剩余的字节数小于传存buffer的长度时
     */
    public abstract void readFully(long position, byte[] buffer)
        throws IOException;
  }
  