001/*
002 * Copyright (C) 2012 The Guava Authors
003 *
004 * Licensed under the Apache License, Version 2.0 (the "License"); you may not use this file except
005 * in compliance with the License. You may obtain a copy of the License at
006 *
007 * http://www.apache.org/licenses/LICENSE-2.0
008 *
009 * Unless required by applicable law or agreed to in writing, software distributed under the License
010 * is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express
011 * or implied. See the License for the specific language governing permissions and limitations under
012 * the License.
013 */
014
015package com.google.common.io;
016
017import static com.google.common.base.Preconditions.checkNotNull;
018
019import com.google.common.annotations.GwtIncompatible;
020import com.google.errorprone.annotations.CanIgnoreReturnValue;
021import java.io.BufferedWriter;
022import java.io.IOException;
023import java.io.Reader;
024import java.io.Writer;
025import java.nio.charset.Charset;
026
027/**
028 * A destination to which characters can be written, such as a text file. Unlike a {@link Writer}, a
029 * {@code CharSink} is not an open, stateful stream that can be written to and closed. Instead, it
030 * is an immutable <i>supplier</i> of {@code Writer} instances.
031 *
032 * <p>{@code CharSink} provides two kinds of methods:
033 *
034 * <ul>
035 *   <li><b>Methods that return a writer:</b> These methods should return a <i>new</i>, independent
036 *       instance each time they are called. The caller is responsible for ensuring that the
037 *       returned writer is closed.
038 *   <li><b>Convenience methods:</b> These are implementations of common operations that are
039 *       typically implemented by opening a writer using one of the methods in the first category,
040 *       doing something and finally closing the writer that was opened.
041 * </ul>
042 *
043 * <p>Any {@link ByteSink} may be viewed as a {@code CharSink} with a specific {@linkplain Charset
044 * character encoding} using {@link ByteSink#asCharSink(Charset)}. Characters written to the
045 * resulting {@code CharSink} will written to the {@code ByteSink} as encoded bytes.
046 *
047 * @since 14.0
048 * @author Colin Decker
049 */
050@GwtIncompatible
051@ElementTypesAreNonnullByDefault
052public abstract class CharSink {
053
054  /** Constructor for use by subclasses. */
055  protected CharSink() {}
056
057  /**
058   * Opens a new {@link Writer} for writing to this sink. This method returns a new, independent
059   * writer each time it is called.
060   *
061   * <p>The caller is responsible for ensuring that the returned writer is closed.
062   *
063   * @throws IOException if an I/O error occurs while opening the writer
064   */
065  public abstract Writer openStream() throws IOException;
066
067  /**
068   * Opens a new buffered {@link Writer} for writing to this sink. The returned stream is not
069   * required to be a {@link BufferedWriter} in order to allow implementations to simply delegate to
070   * {@link #openStream()} when the stream returned by that method does not benefit from additional
071   * buffering. This method returns a new, independent writer each time it is called.
072   *
073   * <p>The caller is responsible for ensuring that the returned writer is closed.
074   *
075   * @throws IOException if an I/O error occurs while opening the writer
076   * @since 15.0 (in 14.0 with return type {@link BufferedWriter})
077   */
078  public Writer openBufferedStream() throws IOException {
079    Writer writer = openStream();
080    return (writer instanceof BufferedWriter)
081        ? (BufferedWriter) writer
082        : new BufferedWriter(writer);
083  }
084
085  /**
086   * Writes the given character sequence to this sink.
087   *
088   * @throws IOException if an I/O error while writing to this sink
089   */
090  public void write(CharSequence charSequence) throws IOException {
091    checkNotNull(charSequence);
092
093    Closer closer = Closer.create();
094    try {
095      Writer out = closer.register(openStream());
096      out.append(charSequence);
097      out.flush(); // https://code.google.com/p/guava-libraries/issues/detail?id=1330
098    } catch (Throwable e) {
099      throw closer.rethrow(e);
100    } finally {
101      closer.close();
102    }
103  }
104
105  /**
106   * Writes the given lines of text to this sink with each line (including the last) terminated with
107   * the operating system's default line separator. This method is equivalent to {@code
108   * writeLines(lines, System.getProperty("line.separator"))}.
109   *
110   * @throws IOException if an I/O error occurs while writing to this sink
111   */
112  public void writeLines(Iterable<? extends CharSequence> lines) throws IOException {
113    writeLines(lines, System.getProperty("line.separator"));
114  }
115
116  /**
117   * Writes the given lines of text to this sink with each line (including the last) terminated with
118   * the given line separator.
119   *
120   * @throws IOException if an I/O error occurs while writing to this sink
121   */
122  public void writeLines(Iterable<? extends CharSequence> lines, String lineSeparator)
123      throws IOException {
124    checkNotNull(lines);
125    checkNotNull(lineSeparator);
126
127    Closer closer = Closer.create();
128    try {
129      Writer out = closer.register(openBufferedStream());
130      for (CharSequence line : lines) {
131        out.append(line).append(lineSeparator);
132      }
133      out.flush(); // https://code.google.com/p/guava-libraries/issues/detail?id=1330
134    } catch (Throwable e) {
135      throw closer.rethrow(e);
136    } finally {
137      closer.close();
138    }
139  }
140
141  /**
142   * Writes all the text from the given {@link Readable} (such as a {@link Reader}) to this sink.
143   * Does not close {@code readable} if it is {@code Closeable}.
144   *
145   * @return the number of characters written
146   * @throws IOException if an I/O error occurs while reading from {@code readable} or writing to
147   *     this sink
148   */
149  @CanIgnoreReturnValue
150  public long writeFrom(Readable readable) throws IOException {
151    checkNotNull(readable);
152
153    Closer closer = Closer.create();
154    try {
155      Writer out = closer.register(openStream());
156      long written = CharStreams.copy(readable, out);
157      out.flush(); // https://code.google.com/p/guava-libraries/issues/detail?id=1330
158      return written;
159    } catch (Throwable e) {
160      throw closer.rethrow(e);
161    } finally {
162      closer.close();
163    }
164  }
165}