001    /*
002     * This file is part of muCommander, http://www.mucommander.com
003     * Copyright (C) 2002-2008 Maxence Bernard
004     *
005     * muCommander is free software; you can redistribute it and/or modify
006     * it under the terms of the GNU General Public License as published by
007     * the Free Software Foundation; either version 3 of the License, or
008     * (at your option) any later version.
009     *
010     * muCommander is distributed in the hope that it will be useful,
011     * but WITHOUT ANY WARRANTY; without even the implied warranty of
012     * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
013     * GNU General Public License for more details.
014     *
015     * You should have received a copy of the GNU General Public License
016     * along with this program.  If not, see <http://www.gnu.org/licenses/>.
017     */
018    
019    package com.mucommander.io.bom;
020    
021    import java.io.IOException;
022    import java.io.InputStream;
023    import java.io.InputStreamReader;
024    import java.io.UnsupportedEncodingException;
025    
026    /**
027     * <code>BOMReader</code> is a <code>Reader</code> which provides support for Byte-Order Marks (BOM).
028     * A BOM is a byte sequence found at the beginning of a Unicode text stream which indicates the encoding of the text
029     * that follows.
030     *
031     * <p>
032     * This class uses a {@link BOMInputStream} for BOM handling and serves a dual purpose:<br>
033     * 1) it allows to auto-detect the encoding when a BOM is present in the underlying stream and use it.<br>
034     * 2) it allows to discard the BOM from a Unicode stream: the leading bytes corresponding to the BOM are swallowed by
035     * the stream and never returned by the <code>read</code> methods.
036     * </p>
037     *
038     * @see BOMInputStream
039     * @author Maxence Bernard
040     */
041    public class BOMReader extends InputStreamReader {
042    
043        /**
044         * Creates a new <code>BOMReader</code>. A {@link BOMInputStream} is created on top of the specified
045         * <code>InputStream</code> to auto-detect a potential {@link BOM} and use the associated encoding.
046         * If no BOM is found at the beginning of the stream, <code>UTF-8</code> encoding is assumed.
047         *
048         * @param in the underlying InputStream
049         * @throws IOException if an error occurred while detecting the BOM or initializing this reader.
050         */
051        public BOMReader(InputStream in) throws IOException {
052            this(new BOMInputStream(in), "UTF-8");
053        }
054    
055        /**
056         * Creates a new <code>BOMReader</code>. A {@link BOMInputStream} is created on top of the specified
057         * <code>InputStream</code> to auto-detect a potential {@link BOM} and use the associated encoding.
058         * If no BOM is found at the beginning of the stream, the specified default encoding is assumed.
059         *
060         * @param in the underlying InputStream
061         * @param defaultEncoding the encoding used if the stream doesn't contain a BOM
062         * @throws IOException if an error occurred while detecting the BOM or initializing this reader.
063         */
064        public BOMReader(InputStream in, String defaultEncoding) throws IOException {
065            this(new BOMInputStream(in), defaultEncoding);
066        }
067    
068        /**
069         * Creates a new <code>BOMReader</code> using the given {@link BOMInputStream}. If the <code>BOMInputStream</code>
070         * does not contain a {@link BOM}, the specified default encoding is assumed.
071         *
072         * @param bomIn the underlying BOMInputStream
073         * @param defaultEncoding the encoding used if the stream doesn't contain a BOM
074         * @throws UnsupportedEncodingException if the encoding associated with the BOM or the default encoding is not
075         * supported by the Java runtime 
076         */
077        public BOMReader(BOMInputStream bomIn, String defaultEncoding) throws UnsupportedEncodingException {
078            super(bomIn, bomIn.getBOM()==null?defaultEncoding:bomIn.getBOM().getEncoding());
079        }
080    }