Package com.google.common.io

Class CharSource

  • All Implemented Interfaces:
    InputSupplier<java.io.Reader>
    public abstract class CharSource
extends java.lang.Object
implements InputSupplier<java.io.Reader>
    A readable source of characters, such as a text file. Unlike a Reader, a CharSource is not an open, stateful stream of characters that can be read and closed. Instead, it is an immutable supplier of Reader instances.

    CharSource provides two kinds of methods:

    • Methods that return a reader: These methods should return a new, independent instance each time they are called. The caller is responsible for ensuring that the returned reader is closed.
    • Convenience methods: These are implementations of common operations that are typically implemented by opening a reader using one of the methods in the first category, doing something and finally closing the reader that was opened.

    Several methods in this class, such as readLines(), break the contents of the source into lines. Like BufferedReader, these methods break lines on any of \n, \r or \r\n, do not include the line separator in each line and do not consider there to be an empty line at the end if the contents are terminated with a line separator.

    Any ByteSource containing text encoded with a specific character encoding may be viewed as a CharSource using ByteSource.asCharSource(Charset).

    Since:
    14.0

    • Constructor Summary

      Constructors 
      Constructor Description
      CharSource()  

    • Method Summary

      All Methods Static Methods Instance Methods Abstract Methods Concrete Methods Deprecated Methods 
      Modifier and Type Method Description
      static CharSource concat​(CharSource... sources)
      Concatenates multiple CharSource instances into a single source.
      static CharSource concat​(java.lang.Iterable<? extends CharSource> sources)
      Concatenates multiple CharSource instances into a single source.
      static CharSource concat​(java.util.Iterator<? extends CharSource> sources)
      Concatenates multiple CharSource instances into a single source.
      long copyTo​(CharSink sink)
      Copies the contents of this source to the given sink.
      long copyTo​(java.lang.Appendable appendable)
      Appends the contents of this source to the given Appendable (such as a Writer).
      static CharSource empty()
      Returns an immutable CharSource that contains no characters.
      java.io.Reader getInput()
      Deprecated.
      This method is only provided for temporary compatibility with the InputSupplier interface and should not be called directly.
      boolean isEmpty()
      Returns whether the source has zero chars.
      java.io.BufferedReader openBufferedStream()
      Opens a new BufferedReader for reading from this source.
      abstract java.io.Reader openStream()
      Opens a new Reader for reading from this source.
      java.lang.String read()
      Reads the contents of this source as a string.
      java.lang.String readFirstLine()
      Reads the first link of this source as a string.
      ImmutableList<java.lang.String> readLines()
      Reads all the lines of this source as a list of strings.
      static CharSource wrap​(java.lang.CharSequence charSequence)
      Returns a view of the given character sequence as a CharSource.

      • Methods inherited from class java.lang.Object

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

    • Constructor Detail

      • CharSource

        public CharSource()

    • Method Detail

      • openStream

        public abstract java.io.Reader openStream()
                                   throws java.io.IOException
        Opens a new Reader for reading from this source. This method should return a new, independent reader each time it is called.

        The caller is responsible for ensuring that the returned reader is closed.

        Throws:
        java.io.IOException - if an I/O error occurs in the process of opening the reader

      • getInput

        @Deprecated
public final java.io.Reader getInput()
                              throws java.io.IOException
        Deprecated.
        This method is only provided for temporary compatibility with the InputSupplier interface and should not be called directly. Use openStream() instead.
        This method is a temporary method provided for easing migration from suppliers to sources and sinks.
        Specified by:
        getInput in interface InputSupplier<java.io.Reader>
        Throws:
        java.io.IOException
        Since:
        15.0

      • openBufferedStream

        public java.io.BufferedReader openBufferedStream()
                                          throws java.io.IOException
        Opens a new BufferedReader for reading from this source. This method should return a new, independent reader each time it is called.

        The caller is responsible for ensuring that the returned reader is closed.

        Throws:
        java.io.IOException - if an I/O error occurs in the process of opening the reader

      • copyTo

        public long copyTo​(java.lang.Appendable appendable)
            throws java.io.IOException
        Appends the contents of this source to the given Appendable (such as a Writer). Does not close appendable if it is Closeable.
        Throws:
        java.io.IOException - if an I/O error occurs in the process of reading from this source or writing to appendable

      • copyTo

        public long copyTo​(CharSink sink)
            throws java.io.IOException
        Copies the contents of this source to the given sink.
        Throws:
        java.io.IOException - if an I/O error occurs in the process of reading from this source or writing to sink

      • read

        public java.lang.String read()
                      throws java.io.IOException
        Reads the contents of this source as a string.
        Throws:
        java.io.IOException - if an I/O error occurs in the process of reading from this source

      • readFirstLine

        @Nullable
public java.lang.String readFirstLine()
                               throws java.io.IOException
        Reads the first link of this source as a string. Returns null if this source is empty.

        Like BufferedReader, this method breaks lines on any of \n, \r or \r\n, does not include the line separator in the returned line and does not consider there to be an extra empty line at the end if the content is terminated with a line separator.

        Throws:
        java.io.IOException - if an I/O error occurs in the process of reading from this source

      • readLines

        public ImmutableList<java.lang.String> readLines()
                                          throws java.io.IOException
        Reads all the lines of this source as a list of strings. The returned list will be empty if this source is empty.

        Like BufferedReader, this method breaks lines on any of \n, \r or \r\n, does not include the line separator in the returned lines and does not consider there to be an extra empty line at the end if the content is terminated with a line separator.

        Throws:
        java.io.IOException - if an I/O error occurs in the process of reading from this source

      • isEmpty

        public boolean isEmpty()
                throws java.io.IOException
        Returns whether the source has zero chars. The default implementation is to open a stream and check for EOF.
        Throws:
        java.io.IOException - if an I/O error occurs
        Since:
        15.0

      • concat

        public static CharSource concat​(java.lang.Iterable<? extends CharSource> sources)
        Concatenates multiple CharSource instances into a single source. Streams returned from the source will contain the concatenated data from the streams of the underlying sources.

        Only one underlying stream will be open at a time. Closing the concatenated stream will close the open underlying stream.

        Parameters:
        sources - the sources to concatenate
        Returns:
        a CharSource containing the concatenated data
        Since:
        15.0

      • concat

        public static CharSource concat​(java.util.Iterator<? extends CharSource> sources)
        Concatenates multiple CharSource instances into a single source. Streams returned from the source will contain the concatenated data from the streams of the underlying sources.

        Only one underlying stream will be open at a time. Closing the concatenated stream will close the open underlying stream.

        Note: The input Iterator will be copied to an ImmutableList when this method is called. This will fail if the iterator is infinite and may cause problems if the iterator eagerly fetches data for each source when iterated (rather than producing sources that only load data through their streams). Prefer using the concat(Iterable) overload if possible.

        Parameters:
        sources - the sources to concatenate
        Returns:
        a CharSource containing the concatenated data
        Throws:
        java.lang.NullPointerException - if any of sources is null
        Since:
        15.0

      • concat

        public static CharSource concat​(CharSource... sources)
        Concatenates multiple CharSource instances into a single source. Streams returned from the source will contain the concatenated data from the streams of the underlying sources.

        Only one underlying stream will be open at a time. Closing the concatenated stream will close the open underlying stream.

        Parameters:
        sources - the sources to concatenate
        Returns:
        a CharSource containing the concatenated data
        Throws:
        java.lang.NullPointerException - if any of sources is null
        Since:
        15.0

      • wrap

        public static CharSource wrap​(java.lang.CharSequence charSequence)
        Returns a view of the given character sequence as a CharSource. The behavior of the returned CharSource and any Reader instances created by it is unspecified if the charSequence is mutated while it is being read, so don't do that.
        Since:
        15.0 (since 14.0 as CharStreams.asCharSource(String))

      • empty

        public static CharSource empty()
        Returns an immutable CharSource that contains no characters.
        Since:
        15.0