    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,
    013     * software distributed under the License is distributed on an
    014     * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
    015     * KIND, either express or implied.  See the License for the
    016     * specific language governing permissions and limitations
    017     * under the License.
    018     */
    019    package org.apache.commons.compress.archivers;
    020
    021    import java.io.IOException;
    022    import java.io.InputStream;
    023
    024    /**
    025     * Archive input streams <b>MUST</b> override the
    026     * {@link #read(byte[], int, int)} - or {@link #read()} -
    027     * method so that reading from the stream generates EOF for the end of
    028     * data in each entry as well as at the end of the file proper.
    029     * <p>
    030     * The {@link #getNextEntry()} method is used to reset the input stream
    031     * ready for reading the data from the next entry.
    032     * <p>
    033     * The input stream classes must also implement a method with the signature:
    034     * <pre>
    035     * public static boolean matches(byte[] signature, int length)
    036     * </pre>
    037     * which is used by the {@link ArchiveStreamFactory} to autodetect
    038     * the archive type from the first few bytes of a stream.
    039     */
    040    public abstract class ArchiveInputStream extends InputStream {
    041
    042        private byte[] SINGLE = new byte[1];
    043        private static final int BYTE_MASK = 0xFF;
    044
    045        /** holds the number of bytes read in this stream */
    046        private long bytesRead = 0;
    047
    048        /**
    049         * Returns the next Archive Entry in this Stream.
    050         *
    051         * @return the next entry,
    052         *         or <code>null</code> if there are no more entries
    053         * @throws IOException if the next entry could not be read
    054         */
    055        public abstract ArchiveEntry getNextEntry() throws IOException;
    056
    057        /*
    058         * Note that subclasses also implement specific get() methods which
    059         * return the appropriate class without need for a cast.
    060         * See SVN revision r743259
    061         * @return
    062         * @throws IOException
    063         */
    064        // public abstract XXXArchiveEntry getNextXXXEntry() throws IOException;
    065
    066        /**
    067         * Reads a byte of data. This method will block until enough input is
    068         * available.
    069         *
    070         * Simply calls the {@link #read(byte[], int, int)} method.
    071         *
    072         * MUST be overridden if the {@link #read(byte[], int, int)} method
    073         * is not overridden; may be overridden otherwise.
    074         *
    075         * @return the byte read, or -1 if end of input is reached
    076         * @throws IOException
    077         *             if an I/O error has occurred
    078         */
    079        @Override
    080        public int read() throws IOException {
    081            int num = read(SINGLE, 0, 1);
    082            return num == -1 ? -1 : SINGLE[0] & BYTE_MASK;
    083        }
    084
    085        /**
    086         * Increments the counter of already read bytes.
    087         * Doesn't increment if the EOF has been hit (read == -1)
    088         *
    089         * @param read the number of bytes read
    090         */
    091        protected void count(int read) {
    092            count((long) read);
    093        }
    094
    095        /**
    096         * Increments the counter of already read bytes.
    097         * Doesn't increment if the EOF has been hit (read == -1)
    098         *
    099         * @param read the number of bytes read
    100         * @since Apache Commons Compress 1.1
    101         */
    102        protected void count(long read) {
    103            if (read != -1) {
    104                bytesRead = bytesRead + read;
    105            }
    106        }
    107
    108        /**
    109         * Decrements the counter of already read bytes.
    110         *
    111         * @param pushedBack the number of bytes pushed back.
    112         * @since Apache Commons Compress 1.1
    113         */
    114        protected void pushedBackBytes(long pushedBack) {
    115            bytesRead -= pushedBack;
    116        }
    117
    118        /**
    119         * Returns the current number of bytes read from this stream.
    120         * @return the number of read bytes
    121         * @deprecated this method may yield wrong results for large
    122         * archives, use #getBytesRead instead
    123         */
    124        @Deprecated
    125        public int getCount() {
    126            return (int) bytesRead;
    127        }
    128
    129        /**
    130         * Returns the current number of bytes read from this stream.
    131         * @return the number of read bytes
    132         * @since Apache Commons Compress 1.1
    133         */
    134        public long getBytesRead() {
    135            return bytesRead;
    136        }
    137
    138        /**
    139         * Whether this stream is able to read the given entry.
    140         *
    141         * <p>Some archive formats support variants or details that are
    142         * not supported (yet).</p>
    143         *
    144         * <p>This implementation always returns true.
    145         *
    146         * @since Apache Commons Compress 1.1
    147         */
    148        public boolean canReadEntryData(ArchiveEntry ae) {
    149            return true;
    150        }
    151
    152    }