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