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.commons.crypto.stream.input; 019 020import java.io.Closeable; 021import java.io.IOException; 022import java.nio.ByteBuffer; 023 024/** 025 * The Input interface abstract the input source of 026 * {@code CryptoInputStream} so that different implementation of input can 027 * be used. The implementation Input interface will usually wraps an input 028 * mechanism such as {@code InputStream} or 029 * {@code ReadableByteChannel}. 030 */ 031public interface Input extends Closeable { 032 /** 033 * Reads a sequence of bytes from input into the given buffer. 034 * 035 * <p> 036 * An attempt is made to read up to <i>r</i> bytes from the input, where 037 * <i>r</i> is the number of bytes remaining in the buffer, that is, 038 * {@code dst.remaining()}, at the moment this method is invoked. 039 * 040 * <p> 041 * Suppose that a byte sequence of length <i>n</i> is read, where {@code 0} 042 * {@code <=} <i>n</i> {@code <=} <i>r</i>. 043 * This byte sequence will be transferred into the buffer so that the first 044 * byte in the sequence is at index <i>p</i> and the last byte is at index 045 * <i>p</i> {@code +} <i>n</i> {@code -} {@code 1}, 046 * where <i>p</i> is the buffer's position at the moment this method is 047 * invoked. Upon return the buffer's position will be equal to 048 * <i>p</i> {@code +} <i>n</i>; its limit will not have changed. 049 * 050 * @param dst The buffer into which bytes are to be transferred. 051 * @return the total number of bytes read into the buffer, or 052 * {@code -1} if there is no more data because the end of the 053 * stream has been reached. 054 * @throws IOException If some other I/O error occurs. 055 */ 056 int read(ByteBuffer dst) throws IOException; 057 058 /** 059 * Skips over and discards {@code n} bytes of data from this input The 060 * {@code skip} method may, for a variety of reasons, end up skipping 061 * over some smaller number of bytes, possibly {@code 0}. This may 062 * result from any of a number of conditions; reaching end of file before 063 * {@code n} bytes have been skipped is only one possibility. The 064 * actual number of bytes skipped is returned. If {@code n} is 065 * negative, no bytes are skipped. 066 * 067 * <p> 068 * The {@code skip} method of this class creates a byte array and then 069 * repeatedly reads into it until {@code n} bytes have been read or the 070 * end of the stream has been reached. Subclasses are encouraged to provide 071 * a more efficient implementation of this method. For instance, the 072 * implementation may depend on the ability to seek. 073 * 074 * @param n the number of bytes to be skipped. 075 * @return the actual number of bytes skipped. 076 * @throws IOException if the stream does not support seek, or if some 077 * other I/O error occurs. 078 */ 079 long skip(long n) throws IOException; 080 081 /** 082 * Returns an estimate of the number of bytes that can be read (or skipped 083 * over) from this input without blocking by the next invocation of a method 084 * for this input stream. The next invocation might be the same thread or 085 * another thread. A single read or skip of this many bytes will not block, 086 * but may read or skip fewer bytes. 087 * 088 * <p> 089 * It is never correct to use the return value of this method to allocate a 090 * buffer intended to hold all data in this stream. 091 * 092 * @return an estimate of the number of bytes that can be read (or skipped 093 * over) from this input stream without blocking or {@code 0} when 094 * it reaches the end of the input stream. 095 * @throws IOException if an I/O error occurs. 096 */ 097 int available() throws IOException; 098 099 /** 100 * Reads up to the specified number of bytes from a given position within a 101 * stream and return the number of bytes read. This does not change the 102 * current offset of the stream and is thread-safe. 103 * 104 * An implementation may not support positioned read. If the implementation 105 * doesn't support positioned read, it throws UnsupportedOperationException. 106 * 107 * @param position the given position within a stream. 108 * @param buffer the buffer into which the data is read. 109 * @param offset the start offset in array buffer. 110 * @param length the maximum number of bytes to read. 111 * @return the total number of bytes read into the buffer, or 112 * {@code -1} if there is no more data because the end of the 113 * stream has been reached. 114 * @throws IOException if an I/O error occurs. 115 */ 116 int read(long position, byte[] buffer, int offset, int length) 117 throws IOException; 118 119 /** 120 * Seeks to the given offset from the start of the stream. The next read() 121 * will be from that location. 122 * 123 * An implementation may not support seek. If the implementation doesn't 124 * support seek, it throws UnsupportedOperationException. 125 * 126 * @param position the offset from the start of the stream. 127 * @throws IOException if an I/O error occurs. 128 */ 129 void seek(long position) throws IOException; 130 131 /** 132 * Closes this input and releases any system resources associated with the 133 * under layer input. 134 * 135 * @throws IOException if an I/O error occurs. 136 */ 137 void close() throws IOException; 138}