DotTerminatedMessageReader.java

  1. /*
  2.  * Licensed to the Apache Software Foundation (ASF) under one or more
  3.  * contributor license agreements.  See the NOTICE file distributed with
  4.  * this work for additional information regarding copyright ownership.
  5.  * The ASF licenses this file to You under the Apache License, Version 2.0
  6.  * (the "License"); you may not use this file except in compliance with
  7.  * the License.  You may obtain a copy of the License at
  8.  *
  9.  *      http://www.apache.org/licenses/LICENSE-2.0
  10.  *
  11.  * Unless required by applicable law or agreed to in writing, software
  12.  * distributed under the License is distributed on an "AS IS" BASIS,
  13.  * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
  14.  * See the License for the specific language governing permissions and
  15.  * limitations under the License.
  16.  */

  18. package org.apache.commons.net.io;

  20. import java.io.BufferedReader;
  21. import java.io.IOException;
  22. import java.io.Reader;

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

  26. /**
  27.  * 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
  28.  * 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
  29.  * NNTP and POP3 produce messages of this type.
  30.  * <p>
  31.  * 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
  32.  * message.
  33.  * <p>
  34.  * 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.
  35.  */
  36. public final class DotTerminatedMessageReader extends BufferedReader {
  37.     private static final char LF = '\n';
  38.     private static final char CR = '\r';
  39.     private static final int DOT = '.';

  41.     private boolean atBeginning;
  42.     private boolean eof;
  43.     private boolean seenCR; // was last character CR?

  45.     /**
  46.      * Creates a DotTerminatedMessageReader that wraps an existing Reader input source.
  47.      *
  48.      * @param reader The Reader input source containing the message.
  49.      */
  50.     public DotTerminatedMessageReader(final Reader reader) {
  51.         super(reader);
  52.         // Assumes input is at start of message
  53.         atBeginning = true;
  54.         eof = false;
  55.     }

  57.     /**
  58.      * Closes the message for reading. This doesn't actually close the underlying stream. The underlying stream may still be used for communicating with the
  59.      * server and therefore is not closed.
  60.      * <p>
  61.      * 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
  62.      * 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
  63.      * will likely hang or behave improperly.
  64.      *
  65.      * @throws IOException If an error occurs while reading the underlying stream.
  66.      */
  67.     @Override
  68.     public void close() throws IOException {
  69.         synchronized (lock) {
  70.             if (!eof) {
  71.                 while (read() != -1) {
  72.                     // read to EOF
  73.                 }
  74.             }
  75.             eof = true;
  76.             atBeginning = false;
  77.         }
  78.     }

  80.     /**
  81.      * 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
  82.      * 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
  83.      * programmer and is only mentioned for completeness.
  84.      *
  85.      * @return The next character in the message. Returns -1 if the end of the message has been reached.
  86.      * @throws IOException If an error occurs while reading the underlying stream.
  87.      */
  88.     @Override
  89.     public int read() throws IOException {
  90.         synchronized (lock) {
  91.             if (eof) {
  92.                 return NetConstants.EOS; // Don't allow read past EOF
  93.             }
  94.             int chint = super.read();
  95.             if (chint == NetConstants.EOS) { // True EOF
  96.                 eof = true;
  97.                 return NetConstants.EOS;
  98.             }
  99.             if (atBeginning) {
  100.                 atBeginning = false;
  101.                 if (chint == DOT) { // Have DOT
  102.                     mark(2); // need to check for CR LF or DOT
  103.                     chint = super.read();
  104.                     switch (chint) {
  105.                     case NetConstants.EOS:
  106.                         // new Throwable("Trailing DOT").printStackTrace();
  107.                         eof = true;
  108.                         return DOT; // return the trailing DOT
  109.                     case DOT:
  110.                         // no need to reset as we want to lose the first DOT
  111.                         return chint; // i.e. DOT
  112.                     case CR:
  113.                         chint = super.read();
  114.                         if (chint == NetConstants.EOS) { // Still only DOT CR - should not happen
  115.                             // new Throwable("Trailing DOT CR").printStackTrace();
  116.                             reset(); // So CR is picked up next time
  117.                             return DOT; // return the trailing DOT
  118.                         }
  119.                         if (chint == LF) { // DOT CR LF
  120.                             atBeginning = true;
  121.                             eof = true;
  122.                             // Do we need to clear the mark somehow?
  123.                             return NetConstants.EOS;
  124.                         }
  125.                         break;
  126.                     default:
  127.                         break;
  128.                     }
  129.                     // Should not happen - lone DOT at beginning
  130.                     // new Throwable("Lone DOT followed by "+(char)chint).printStackTrace();
  131.                     reset();
  132.                     return DOT;
  133.                 } // have DOT
  134.             } // atBeginning

  136.             // Handle CRLF in normal flow
  137.             if (seenCR) {
  138.                 seenCR = false;
  139.                 if (chint == LF) {
  140.                     atBeginning = true;
  141.                 }
  142.             }
  143.             if (chint == CR) {
  144.                 seenCR = true;
  145.             }
  146.             return chint;
  147.         }
  148.     }

  150.     /**
  151.      * 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
  152.      * reached.
  153.      *
  154.      * @param buffer The character array in which to store the characters.
  155.      * @return The number of characters read. Returns -1 if the end of the message has been reached.
  156.      * @throws IOException If an error occurs in reading the underlying stream.
  157.      */
  158.     @Override
  159.     public int read(final char[] buffer) throws IOException {
  160.         return read(buffer, 0, buffer.length);
  161.     }

  163.     /**
  164.      * 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
  165.      * reached. The characters are stored in the array starting from the given offset and up to the length specified.
  166.      *
  167.      * @param buffer The character array in which to store the characters.
  168.      * @param offset The offset into the array at which to start storing characters.
  169.      * @param length The number of characters to read.
  170.      * @return The number of characters read. Returns -1 if the end of the message has been reached.
  171.      * @throws IOException If an error occurs in reading the underlying stream.
  172.      */
  173.     @Override
  174.     public int read(final char[] buffer, int offset, int length) throws IOException {
  175.         if (length < 1) {
  176.             return 0;
  177.         }
  178.         int ch;
  179.         synchronized (lock) {
  180.             if ((ch = read()) == -1) {
  181.                 return NetConstants.EOS;
  182.             }

  184.             final int off = offset;

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

  190.             return offset - off;
  191.         }
  192.     }

  194.     /**
  195.      * Read a line of text. A line is considered to be terminated by carriage return followed immediately by a linefeed. This contrasts with BufferedReader
  196.      * which also allows other combinations.
  197.      *
  198.      * @since 3.0
  199.      */
  200.     @Override
  201.     public String readLine() throws IOException {
  202.         final StringBuilder sb = new StringBuilder();
  203.         int intch;
  204.         synchronized (lock) { // make thread-safe (hopefully!)
  205.             while ((intch = read()) != NetConstants.EOS) {
  206.                 if (intch == LF && atBeginning) {
  207.                     return sb.substring(0, sb.length() - 1);
  208.                 }
  209.                 sb.append((char) intch);
  210.             }
  211.         }
  212.         final String string = sb.toString();
  213.         if (string.isEmpty()) { // immediate EOF
  214.             return null;
  215.         }
  216.         // Should not happen - EOF without CRLF
  217.         // new Throwable(string).printStackTrace();
  218.         return string;
  219.     }
  220. }
Created with JaCoCo 0.8.12.202403310830