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.common.annotations.J2ktIncompatible;
021import com.google.errorprone.annotations.CanIgnoreReturnValue;
022import java.io.BufferedOutputStream;
023import java.io.IOException;
024import java.io.InputStream;
025import java.io.OutputStream;
026import java.io.OutputStreamWriter;
027import java.io.Writer;
028import java.nio.charset.Charset;
029
030/**
031 * A destination to which bytes can be written, such as a file. Unlike an {@link OutputStream}, a
032 * {@code ByteSink} is not an open, stateful stream that can be written to and closed. Instead, it
033 * is an immutable <i>supplier</i> of {@code OutputStream} instances.
034 *
035 * <p>{@code ByteSink} provides two kinds of methods:
036 *
037 * <ul>
038 *   <li><b>Methods that return a stream:</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 stream is closed.
041 *   <li><b>Convenience methods:</b> These are implementations of common operations that are
042 *       typically implemented by opening a stream using one of the methods in the first category,
043 *       doing something and finally closing the stream or channel that was opened.
044 * </ul>
045 *
046 * @since 14.0
047 * @author Colin Decker
048 */
049@J2ktIncompatible
050@GwtIncompatible
051@ElementTypesAreNonnullByDefault
052public abstract class ByteSink {
053
054  /** Constructor for use by subclasses. */
055  protected ByteSink() {}
056
057  /**
058   * Returns a {@link CharSink} view of this {@code ByteSink} that writes characters to this sink as
059   * bytes encoded with the given {@link Charset charset}.
060   */
061  public CharSink asCharSink(Charset charset) {
062    return new AsCharSink(charset);
063  }
064
065  /**
066   * Opens a new {@link OutputStream} for writing to this sink. This method returns a new,
067   * independent stream each time it is called.
068   *
069   * <p>The caller is responsible for ensuring that the returned stream is closed.
070   *
071   * @throws IOException if an I/O error occurs while opening the stream
072   */
073  public abstract OutputStream openStream() throws IOException;
074
075  /**
076   * Opens a new buffered {@link OutputStream} for writing to this sink. The returned stream is not
077   * required to be a {@link BufferedOutputStream} in order to allow implementations to simply
078   * delegate to {@link #openStream()} when the stream returned by that method does not benefit from
079   * additional buffering (for example, a {@code ByteArrayOutputStream}). This method returns a new,
080   * independent stream each time it is called.
081   *
082   * <p>The caller is responsible for ensuring that the returned stream is closed.
083   *
084   * @throws IOException if an I/O error occurs while opening the stream
085   * @since 15.0 (in 14.0 with return type {@link BufferedOutputStream})
086   */
087  public OutputStream openBufferedStream() throws IOException {
088    OutputStream out = openStream();
089    return (out instanceof BufferedOutputStream)
090        ? (BufferedOutputStream) out
091        : new BufferedOutputStream(out);
092  }
093
094  /**
095   * Writes all the given bytes to this sink.
096   *
097   * @throws IOException if an I/O occurs while writing to this sink
098   */
099  public void write(byte[] bytes) throws IOException {
100    checkNotNull(bytes);
101
102    try (OutputStream out = openStream()) {
103      out.write(bytes);
104    }
105  }
106
107  /**
108   * Writes all the bytes from the given {@code InputStream} to this sink. Does not close {@code
109   * input}.
110   *
111   * @return the number of bytes written
112   * @throws IOException if an I/O occurs while reading from {@code input} or writing to this sink
113   */
114  @CanIgnoreReturnValue
115  public long writeFrom(InputStream input) throws IOException {
116    checkNotNull(input);
117
118    try (OutputStream out = openStream()) {
119      return ByteStreams.copy(input, out);
120    }
121  }
122
123  /**
124   * A char sink that encodes written characters with a charset and writes resulting bytes to this
125   * byte sink.
126   */
127  private final class AsCharSink extends CharSink {
128
129    private final Charset charset;
130
131    private AsCharSink(Charset charset) {
132      this.charset = checkNotNull(charset);
133    }
134
135    @Override
136    public Writer openStream() throws IOException {
137      return new OutputStreamWriter(ByteSink.this.openStream(), charset);
138    }
139
140    @Override
141    public String toString() {
142      return ByteSink.this.toString() + ".asCharSink(" + charset + ")";
143    }
144  }
145}