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.Beta;
020import com.google.common.annotations.GwtIncompatible;
021import com.google.errorprone.annotations.CanIgnoreReturnValue;
022import java.io.BufferedWriter;
023import java.io.IOException;
024import java.io.Reader;
025import java.io.Writer;
026import java.nio.charset.Charset;
027import java.util.Iterator;
028import java.util.stream.Stream;
029
030/**
031 * A destination to which characters can be written, such as a text file. Unlike a {@link Writer}, a
032 * {@code CharSink} is not an open, stateful stream that can be written to and closed. Instead, it
033 * is an immutable <i>supplier</i> of {@code Writer} instances.
034 *
035 * <p>{@code CharSink} provides two kinds of methods:
036 *
037 * <ul>
038 *   <li><b>Methods that return a writer:</b> These methods should return a <i>new</i>, independent
039 *       instance each time they are called. The caller is responsible for ensuring that the
040 *       returned writer is closed.
041 *   <li><b>Convenience methods:</b> These are implementations of common operations that are
042 *       typically implemented by opening a writer using one of the methods in the first category,
043 *       doing something and finally closing the writer that was opened.
044 * </ul>
045 *
046 * <p>Any {@link ByteSink} may be viewed as a {@code CharSink} with a specific {@linkplain Charset
047 * character encoding} using {@link ByteSink#asCharSink(Charset)}. Characters written to the
048 * resulting {@code CharSink} will written to the {@code ByteSink} as encoded bytes.
049 *
050 * @since 14.0
051 * @author Colin Decker
052 */
053@GwtIncompatible
054public abstract class CharSink implements OutputSupplier<Writer> {
055
056  /** Constructor for use by subclasses. */
057  protected CharSink() {}
058
059  /**
060   * Opens a new {@link Writer} for writing to this sink. This method returns a new, independent
061   * writer each time it is called.
062   *
063   * <p>The caller is responsible for ensuring that the returned writer is closed.
064   *
065   * @throws IOException if an I/O error occurs while opening the writer
066   */
067  public abstract Writer openStream() throws IOException;
068
069  /**
070   * This method is a temporary method provided for easing migration from suppliers to sources and
071   * sinks.
072   *
073   * @since 15.0
074   * @deprecated This method is only provided for temporary compatibility with the
075   *     {@link OutputSupplier} interface and should not be called directly. Use
076   *     {@link #openStream} instead. This method is scheduled for removal in Guava 18.0.
077   */
078  @Override
079  @Deprecated
080  public final Writer getOutput() throws IOException {
081    return openStream();
082  }
083
084  /**
085   * Opens a new buffered {@link Writer} for writing to this sink. The returned stream is not
086   * required to be a {@link BufferedWriter} in order to allow implementations to simply delegate to
087   * {@link #openStream()} when the stream returned by that method does not benefit from additional
088   * buffering. This method returns a new, independent writer each time it is called.
089   *
090   * <p>The caller is responsible for ensuring that the returned writer is closed.
091   *
092   * @throws IOException if an I/O error occurs while opening the writer
093   * @since 15.0 (in 14.0 with return type {@link BufferedWriter})
094   */
095  public Writer openBufferedStream() throws IOException {
096    Writer writer = openStream();
097    return (writer instanceof BufferedWriter)
098        ? (BufferedWriter) writer
099        : new BufferedWriter(writer);
100  }
101
102  /**
103   * Writes the given character sequence to this sink.
104   *
105   * @throws IOException if an I/O error while writing to this sink
106   */
107  public void write(CharSequence charSequence) throws IOException {
108    checkNotNull(charSequence);
109
110    Closer closer = Closer.create();
111    try {
112      Writer out = closer.register(openStream());
113      out.append(charSequence);
114      out.flush(); // https://code.google.com/p/guava-libraries/issues/detail?id=1330
115    } catch (Throwable e) {
116      throw closer.rethrow(e);
117    } finally {
118      closer.close();
119    }
120  }
121
122  /**
123   * Writes the given lines of text to this sink with each line (including the last) terminated with
124   * the operating system's default line separator. This method is equivalent to {@code
125   * writeLines(lines, System.getProperty("line.separator"))}.
126   *
127   * @throws IOException if an I/O error occurs while writing to this sink
128   */
129  public void writeLines(Iterable<? extends CharSequence> lines) throws IOException {
130    writeLines(lines, System.getProperty("line.separator"));
131  }
132
133  /**
134   * Writes the given lines of text to this sink with each line (including the last) terminated with
135   * the given line separator.
136   *
137   * @throws IOException if an I/O error occurs while writing to this sink
138   */
139  public void writeLines(Iterable<? extends CharSequence> lines, String lineSeparator)
140      throws IOException {
141    writeLines(lines.iterator(), lineSeparator);
142  }
143
144  /**
145   * Writes the given lines of text to this sink with each line (including the last) terminated with
146   * the operating system's default line separator. This method is equivalent to {@code
147   * writeLines(lines, System.getProperty("line.separator"))}.
148   *
149   * @throws IOException if an I/O error occurs while writing to this sink
150   * @since 22.0
151   */
152  @Beta
153  public void writeLines(Stream<? extends CharSequence> lines) throws IOException {
154    writeLines(lines, System.getProperty("line.separator"));
155  }
156
157  /**
158   * Writes the given lines of text to this sink with each line (including the last) terminated with
159   * the given line separator.
160   *
161   * @throws IOException if an I/O error occurs while writing to this sink
162   * @since 22.0
163   */
164  @Beta
165  public void writeLines(Stream<? extends CharSequence> lines, String lineSeparator)
166      throws IOException {
167    writeLines(lines.iterator(), lineSeparator);
168  }
169
170  private void writeLines(Iterator<? extends CharSequence> lines, String lineSeparator)
171      throws IOException {
172    checkNotNull(lineSeparator);
173
174    try (Writer out = openBufferedStream()) {
175      while (lines.hasNext()) {
176        out.append(lines.next()).append(lineSeparator);
177      }
178    }
179  }
180
181  /**
182   * Writes all the text from the given {@link Readable} (such as a {@link Reader}) to this sink.
183   * Does not close {@code readable} if it is {@code Closeable}.
184   *
185   * @return the number of characters written
186   * @throws IOException if an I/O error occurs while reading from {@code readable} or writing to
187   *     this sink
188   */
189  @CanIgnoreReturnValue
190  public long writeFrom(Readable readable) throws IOException {
191    checkNotNull(readable);
192
193    Closer closer = Closer.create();
194    try {
195      Writer out = closer.register(openStream());
196      long written = CharStreams.copy(readable, out);
197      out.flush(); // https://code.google.com/p/guava-libraries/issues/detail?id=1330
198      return written;
199    } catch (Throwable e) {
200      throw closer.rethrow(e);
201    } finally {
202      closer.close();
203    }
204  }
205}