1 /*
2 * Copyright (C) 2005-2015 Schlichtherle IT Services.
3 * All rights reserved. Use is subject to license terms.
4 */
5 package net.java.truecommons.io;
6
7 import edu.umd.cs.findbugs.annotations.CreatesObligation;
8 import java.io.IOException;
9 import java.io.OutputStream;
10 import java.nio.channels.NonReadableChannelException;
11 import java.nio.channels.SeekableByteChannel;
12
13 /**
14 * A provider for output streams or seekable byte channels.
15 *
16 * @see Source
17 * @author Christian Schlichtherle
18 */
19 public interface Sink {
20
21 /**
22 * Returns an output stream for writing bytes.
23 * The returned output stream should <em>not</em> be buffered.
24 * Buffering should get addressed by the caller instead.
25 *
26 * @return An output stream for writing bytes.
27 * @throws IOException on any I/O error.
28 * @throws IllegalStateException if another output stream is not available.
29 */
30 @CreatesObligation
31 OutputStream stream() throws IOException;
32
33 /**
34 * <b>Optional operation:</b> Returns a seekable byte channel for
35 * writing bytes.
36 * If this method is supported, then the returned seekable byte channel
37 * should <em>not</em> be buffered.
38 * Buffering should get addressed by the caller instead.
39 * <p>
40 * Because the intention of this interface is output, the returned channel
41 * does not need to be able to position the file pointer or read data and
42 * any attempt to do so may fail with a {@link NonReadableChannelException}.
43 *
44 * @return A seekable byte channel for writing bytes.
45 * @throws IOException on any I/O error.
46 * @throws UnsupportedOperationException if this operation is not supported.
47 * @throws IllegalStateException if another seekable byte channel is not
48 * available.
49 */
50 @CreatesObligation
51 SeekableByteChannel channel() throws IOException;
52 }