001/**
002 * Java Web Archive Toolkit - Software to read and validate ARC, WARC
003 * and GZip files. (http://jwat.org/)
004 * Copyright 2011-2012 Netarkivet.dk (http://netarkivet.dk/)
005 *
006 * Licensed under the Apache License, Version 2.0 (the "License");
007 * you may not use this file except in compliance with the License.
008 * 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.jwat.arc;
019
020import java.io.BufferedInputStream;
021import java.io.IOException;
022import java.io.InputStream;
023import java.util.Arrays;
024
025import org.jwat.archive.common.ReaderFactoryAbstract;
026import org.jwat.common.ByteCountingPushBackInputStream;
027import org.jwat.common.Scheme;
028import org.jwat.gzip.GzipReader;
029
030/**
031 * Factory used for creating <code>ArcReader</code> instances.
032 * The general <code>getReader</code> methods will auto-detect Gzip'ed data
033 * and return the appropriate <code>ArcReader</code> instances.
034 * The other factory methods can be used to return specific
035 * <code>ArcReader</code> instances for compressed or uncompressed records.
036 * Readers are available for both sequential and random reading of records.
037 * Use of buffered methods and/or buffering speeds up the reader considerably.
038 *
039 * @author nicl
040 */
041public class ArcReaderFactory extends ReaderFactoryAbstract {
042
043    /** Buffer size used by <code>PushbackInputStream</code>. */
044    public static final int PUSHBACK_BUFFER_SIZE = 32;
045
046    /**
047     * Private constructor to enforce factory methods.
048     */
049    protected ArcReaderFactory() {
050    }
051
052    /**
053     * Check head of <code>PushBackInputStream</code> for an ARC file identifier.
054     * The identifier for ARC files is "filedesc:" in the beginning.
055     * @param pbin <code>PushBackInputStream</code> with an ARC version block
056     * @return boolean indicating presence of an ARC file identifier
057     * @throws IOException if an I/O error occurs while examining head of stream
058     */
059    public static boolean isArcFile(ByteCountingPushBackInputStream pbin) throws IOException {
060        byte[] streamBytes = new byte[ArcConstants.ARC_MAGIC_HEADER.length()];
061        byte[] arcBytes = ArcConstants.ARC_MAGIC_HEADER.getBytes();
062        // Look for an ARC file identifier in the beginning of the stream.
063        pbin.peek(streamBytes);
064        return (Arrays.equals(arcBytes, streamBytes));
065    }
066
067    /**
068     * Check head of <code>PushBackInputStream</code> for an ARC record identifier.
069     * The identifier for ARC files is "filedesc:" in the beginning.
070     * @param pbin <code>PushBackInputStream</code> with an ARC version block
071     * @return boolean indicating presence of an ARC file identifier
072     * @throws IOException if an I/O error occurs while examining head of stream
073     */
074    public static boolean isArcRecord(ByteCountingPushBackInputStream pbin) throws IOException {
075        byte[] streamBytes = new byte[32];
076        // Look for a valid scheme in the beginning of the stream.
077        pbin.peek(streamBytes);
078        return Scheme.startsWithScheme(streamBytes);
079    }
080
081    /**
082     * Creates a new <code>ArcReader</code> from an <code>InputStream</code>
083     * wrapped by a <code>BufferedInputStream</code>.
084     * The <code>WarcReader</code> implementation returned is chosen based on
085     * GZip auto detection.
086     * @param in ARC File represented as <code>InputStream</code>
087     * @param buffer_size buffer size to use
088     * @return appropriate <code>ArcReader</code> based on data read from
089     * <code>InputStream</code>
090     * @throws IOException if an I/O exception occurs during initialization
091     */
092    public static ArcReader getReader(InputStream in, int buffer_size)
093                                                        throws IOException {
094        if (in == null) {
095            throw new IllegalArgumentException(
096                    "The inputstream 'in' is null");
097        }
098        if (buffer_size <= 0) {
099            throw new IllegalArgumentException(
100                    "The 'buffer_size' is less than or equal to zero: "
101                    + buffer_size);
102        }
103        ByteCountingPushBackInputStream pbin =
104                new ByteCountingPushBackInputStream(
105                        new BufferedInputStream(in, buffer_size),
106                                                PUSHBACK_BUFFER_SIZE);
107        if (GzipReader.isGzipped(pbin)) {
108            return new ArcReaderCompressed(new GzipReader(pbin),
109                                           buffer_size);
110        }
111        return new ArcReaderUncompressed(pbin);
112    }
113
114    /**
115     * Creates a new <code>ArcReader</code> from an <code>InputStream</code>.
116     * The <code>WarcReader</code> implementation returned is chosen based on
117     * GZip auto detection.
118     * @param in ARC File represented as <code>InputStream</code>
119     * @return appropriate <code>ArcReader</code> based on data read from
120     * <code>InputStream</code>
121     * @throws IOException if an I/O exception occurs during initialization
122     */
123    public static ArcReader getReader(InputStream in) throws IOException {
124        if (in == null) {
125            throw new IllegalArgumentException(
126                    "The inputstream 'in' is null");
127        }
128        ByteCountingPushBackInputStream pbin =
129                new ByteCountingPushBackInputStream(in, PUSHBACK_BUFFER_SIZE);
130        if (GzipReader.isGzipped(pbin)) {
131            return new ArcReaderCompressed(new GzipReader(pbin));
132        }
133        return new ArcReaderUncompressed(pbin);
134    }
135
136    /**
137     * Creates a new <code>ArcReader</code> without any associated
138     * <code>InputStream</code> for random access to uncompressed records.
139     * @return <code>ArcReader</code> for uncompressed records read from
140     * <code>InputStream</code>
141     */
142    public static ArcReaderUncompressed getReaderUncompressed() {
143        return new ArcReaderUncompressed();
144    }
145
146    /**
147     * Creates a new <code>ArcReader</code> from an <code>InputStream</code>
148     * primarily for random access to uncompressed records.
149     * @param in ARC File represented as <code>InputStream</code>
150     * @return <code>ArcReader</code> for uncompressed records read from
151     * <code>InputStream</code>
152     * @throws IOException I/O exception while initializing reader
153     */
154    public static ArcReaderUncompressed getReaderUncompressed(InputStream in)
155                                                        throws IOException {
156        if (in == null) {
157            throw new IllegalArgumentException(
158                    "The inputstream 'in' is null");
159        }
160        ByteCountingPushBackInputStream pbin =
161                new ByteCountingPushBackInputStream(in, PUSHBACK_BUFFER_SIZE);
162        return new ArcReaderUncompressed(pbin);
163    }
164
165    /**
166     * Creates a new <code>ArcReader</code> from an <code>InputStream</code>
167     * wrapped by a <code>BufferedInputStream</code> primarily for random
168     * access to uncompressed records.
169     * @param in ARC File represented as <code>InputStream</code>
170     * @param buffer_size buffer size to use
171     * @return <code>ArcReader</code> for uncompressed records read from
172     * <code>InputStream</code>
173     * @throws IOException I/O exception while initializing reader
174     */
175    public static ArcReaderUncompressed getReaderUncompressed(InputStream in,
176                                        int buffer_size) throws IOException {
177        if (in == null) {
178            throw new IllegalArgumentException(
179                    "The inputstream 'in' is null");
180        }
181        if (buffer_size <= 0) {
182            throw new IllegalArgumentException(
183                    "The 'buffer_size' is less than or equal to zero: "
184                    + buffer_size);
185        }
186        ByteCountingPushBackInputStream pbin =
187                new ByteCountingPushBackInputStream(
188                        new BufferedInputStream(in, buffer_size),
189                        PUSHBACK_BUFFER_SIZE);
190        return new ArcReaderUncompressed(pbin);
191    }
192
193    /**
194     * Creates a new <code>ArcReader</code> without any associated
195     * <code>InputStream</code> for random access to GZip compressed records.
196     * @return <code>ArcReader</code> for GZip compressed records read from
197     * <code>InputStream</code>
198     */
199    public static ArcReaderCompressed getReaderCompressed() {
200        return new ArcReaderCompressed();
201    }
202
203    /**
204     * Creates a new <code>ArcReader</code> from an <code>InputStream</code>
205     * primarily for random access to GZip compressed records.
206     * @param in ARC File represented as <code>InputStream</code>
207     * @return <code>ArcReader</code> for GZip compressed records read from
208     * <code>InputStream</code>
209     * @throws IOException I/O exception while initializing reader
210     */
211    public static ArcReaderCompressed getReaderCompressed(InputStream in)
212                                                        throws IOException {
213        if (in == null) {
214            throw new IllegalArgumentException(
215                    "The inputstream 'in' is null");
216        }
217        return new ArcReaderCompressed(new GzipReader(in));
218    }
219
220    /**
221     * Creates a new <code>ArcReader</code> from an <code>InputStream</code>
222     * wrapped by a <code>BufferedInputStream</code> primarily for random
223     * access to GZip compressed records.
224     * @param in ARC File represented as <code>InputStream</code>
225     * @param buffer_size buffer size to use
226     * @return <code>ArcReader</code> for GZip compressed records read from
227     * <code>InputStream</code>
228     * @throws IOException I/O exception while initializing reader
229     */
230    public static ArcReaderCompressed getReaderCompressed(InputStream in,
231                                        int buffer_size) throws IOException {
232        if (in == null) {
233            throw new IllegalArgumentException(
234                    "The inputstream 'in' is null");
235        }
236        if (buffer_size <= 0) {
237            throw new IllegalArgumentException(
238                    "The 'buffer_size' is less than or equal to zero: "
239                    + buffer_size);
240        }
241        return new ArcReaderCompressed(new GzipReader(
242                                new BufferedInputStream(in, buffer_size)));
243    }
244
245}