Package org.apache.commons.net.io

Class DotTerminatedMessageReader

java.lang.Object
java.io.Reader
java.io.BufferedReader
org.apache.commons.net.io.DotTerminatedMessageReader
All Implemented Interfaces:
Closeable, AutoCloseable, Readable
public final class DotTerminatedMessageReader extends BufferedReader
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.

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.

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.

  • Field Summary

    Fields inherited from class java.io.Reader

    lock

  • Constructor Summary

    Constructors
    Constructor
    Description
    DotTerminatedMessageReader(Reader reader)
    Creates a DotTerminatedMessageReader that wraps an existing Reader input source.

  • Method Summary

    Modifier and Type
    Method
    Description
    void
    close()
    Closes the message for reading.
    int
    read()
    Reads and returns the next character in the message.
    int
    read(char[] buffer)
    Reads the next characters from the message into an array and returns the number of characters read.
    int
    read(char[] buffer, int offset, int length)
    Reads the next characters from the message into an array and returns the number of characters read.
    String
    readLine()
    Read a line of text.

    Methods inherited from class java.io.BufferedReader

    lines, mark, markSupported, ready, reset, skip

    Methods inherited from class java.io.Reader

    read

    Methods inherited from class java.lang.Object

    clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

  • Constructor Details

    • DotTerminatedMessageReader

      public DotTerminatedMessageReader(Reader reader)
      Creates a DotTerminatedMessageReader that wraps an existing Reader input source.
      Parameters:
      reader - The Reader input source containing the message.

  • Method Details

    • close

      public void close() throws IOException
      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.

      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.

      Specified by:
      close in interface AutoCloseable
      Specified by:
      close in interface Closeable
      Overrides:
      close in class BufferedReader
      Throws:
      IOException - If an error occurs while reading the underlying stream.

    • read

      public int read() throws IOException
      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.
      Overrides:
      read in class BufferedReader
      Returns:
      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.

    • read

      public int read(char[] buffer) throws IOException
      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.
      Overrides:
      read in class Reader
      Parameters:
      buffer - The character array in which to store the characters.
      Returns:
      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.

    • read

      public int read(char[] buffer, int offset, int length) throws IOException
      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.
      Overrides:
      read in class BufferedReader
      Parameters:
      buffer - The character array in which to store the characters.
      offset - The offset into the array at which to start storing characters.
      length - The number of characters to read.
      Returns:
      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.

    • readLine

      public String readLine() throws IOException
      Read 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.
      Overrides:
      readLine in class BufferedReader
      Throws:
      IOException
      Since:
      3.0