DotTerminatedMessageReader.java

/*
 * 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
 *
 *      https://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 org.apache.commons.net.io;

import java.io.BufferedReader;
import java.io.IOException;
import java.io.Reader;

import org.apache.commons.net.util.NetConstants;

/**
 * DotTerminatedMessageReader is a class used to read messages from a server that are terminated by a single dot followed by a <CR><LF> sequence and
 * with double dots appearing at the beginning of lines which do not signal end of message yet start with a dot. Various Internet protocols such as
 * NNTP and POP3 produce messages of this type.
 * <p>
 * This class handles stripping of the duplicate period at the beginning of lines starting with a period, and ensures you cannot read past the end of the
 * message.
 * </p>
 * <p>
 * Note: versions since 3.0 extend BufferedReader rather than Reader, and no longer change the CRLF into the local EOL. Also, only DOT CR LF acts as EOF.
 * </p>
 */
public final class DotTerminatedMessageReader extends BufferedReader {
    private static final char LF = '\n';
    private static final char CR = '\r';
    private static final int DOT = '.';

    private boolean atBeginning;
    private boolean eof;
    private boolean seenCR; // was last character CR?

    /**
     * Creates a DotTerminatedMessageReader that wraps an existing Reader input source.
     *
     * @param reader The Reader input source containing the message.
     */
    public DotTerminatedMessageReader(final Reader reader) {
        super(reader);
        // Assumes input is at start of message
        atBeginning = true;
        eof = false;
    }

    /**
     * Closes the message for reading. This doesn't actually close the underlying stream. The underlying stream may still be used for communicating with the
     * server and therefore is not closed.
     * <p>
     * If the end of the message has not yet been reached, this method will read the remainder of the message until it reaches the end, so that the underlying
     * stream may continue to be used properly for communicating with the server. If you do not fully read a message, you MUST close it, otherwise your program
     * will likely hang or behave improperly.
     * </p>
     *
     * @throws IOException If an error occurs while reading the underlying stream.
     */
    @Override
    public void close() throws IOException {
        synchronized (lock) {
            if (!eof) {
                while (read() != -1) {
                    // read to EOF
                }
            }
            eof = true;
            atBeginning = false;
        }
    }

    /**
     * Reads and returns the next character in the message. If the end of the message has been reached, returns -1. Note that a call to this method may result
     * in multiple reads from the underlying input stream to decode the message properly (removing doubled dots and so on). All of this is transparent to the
     * programmer and is only mentioned for completeness.
     *
     * @return The next character in the message. Returns -1 if the end of the message has been reached.
     * @throws IOException If an error occurs while reading the underlying stream.
     */
    @Override
    public int read() throws IOException {
        synchronized (lock) {
            if (eof) {
                return NetConstants.EOS; // Don't allow read past EOF
            }
            int chint = super.read();
            if (chint == NetConstants.EOS) { // True EOF
                eof = true;
                return NetConstants.EOS;
            }
            if (atBeginning) {
                atBeginning = false;
                if (chint == DOT) { // Have DOT
                    mark(2); // need to check for CR LF or DOT
                    chint = super.read();
                    switch (chint) {
                    case NetConstants.EOS:
                        // new Throwable("Trailing DOT").printStackTrace();
                        eof = true;
                        return DOT; // return the trailing DOT
                    case DOT:
                        // no need to reset as we want to lose the first DOT
                        return chint; // i.e. DOT
                    case CR:
                        chint = super.read();
                        if (chint == NetConstants.EOS) { // Still only DOT CR - should not happen
                            // new Throwable("Trailing DOT CR").printStackTrace();
                            reset(); // So CR is picked up next time
                            return DOT; // return the trailing DOT
                        }
                        if (chint == LF) { // DOT CR LF
                            atBeginning = true;
                            eof = true;
                            // Do we need to clear the mark somehow?
                            return NetConstants.EOS;
                        }
                        break;
                    default:
                        break;
                    }
                    // Should not happen - lone DOT at beginning
                    // new Throwable("Lone DOT followed by "+(char)chint).printStackTrace();
                    reset();
                    return DOT;
                } // have DOT
            } // atBeginning

            // Handle CRLF in normal flow
            if (seenCR) {
                seenCR = false;
                if (chint == LF) {
                    atBeginning = true;
                }
            }
            if (chint == CR) {
                seenCR = true;
            }
            return chint;
        }
    }

    /**
     * Reads the next characters from the message into an array and returns the number of characters read. Returns -1 if the end of the message has been
     * reached.
     *
     * @param buffer The character array in which to store the characters.
     * @return The number of characters read. Returns -1 if the end of the message has been reached.
     * @throws IOException If an error occurs in reading the underlying stream.
     */
    @Override
    public int read(final char[] buffer) throws IOException {
        return read(buffer, 0, buffer.length);
    }

    /**
     * Reads the next characters from the message into an array and returns the number of characters read. Returns -1 if the end of the message has been
     * reached. The characters are stored in the array starting from the given offset and up to the length specified.
     *
     * @param buffer The character array in which to store the characters.
     * @param offset The offset into the array at which to start storing characters.
     * @param length The number of characters to read.
     * @return The number of characters read. Returns -1 if the end of the message has been reached.
     * @throws IOException If an error occurs in reading the underlying stream.
     */
    @Override
    public int read(final char[] buffer, int offset, int length) throws IOException {
        if (length < 1) {
            return 0;
        }
        int ch;
        synchronized (lock) {
            if ((ch = read()) == -1) {
                return NetConstants.EOS;
            }

            final int off = offset;

            do {
                buffer[offset++] = (char) ch;
            } while (--length > 0 && (ch = read()) != -1);

            return offset - off;
        }
    }

    /**
     * Reads a line of text. A line is considered to be terminated by carriage return followed immediately by a linefeed. This contrasts with BufferedReader
     * which also allows other combinations.
     *
     * @since 3.0
     */
    @Override
    public String readLine() throws IOException {
        final StringBuilder sb = new StringBuilder();
        int intch;
        synchronized (lock) { // make thread-safe (hopefully!)
            while ((intch = read()) != NetConstants.EOS) {
                if (intch == LF && atBeginning) {
                    return sb.substring(0, sb.length() - 1);
                }
                sb.append((char) intch);
            }
        }
        final String string = sb.toString();
        if (string.isEmpty()) { // immediate EOF
            return null;
        }
        // Should not happen - EOF without CRLF
        // new Throwable(string).printStackTrace();
        return string;
    }
}