1 /*
2 * Licensed to the Apache Software Foundation (ASF) under one
3 * or more contributor license agreements. See the NOTICE file
4 * distributed with this work for additional information
5 * regarding copyright ownership. The ASF licenses this file
6 * to you under the Apache License, Version 2.0 (the
7 * "License"); you may not use this file except in compliance
8 * with the License. You may obtain a copy of the License at
9 *
10 * http://www.apache.org/licenses/LICENSE-2.0
11 *
12 * Unless required by applicable law or agreed to in writing, software
13 * distributed under the License is distributed on an "AS IS" BASIS,
14 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
15 * See the License for the specific language governing permissions and
16 * limitations under the License.
17 */
18 package org.apache.commons.crypto.stream.output;
19
20 import java.io.Closeable;
21 import java.io.IOException;
22 import java.io.OutputStream;
23 import java.nio.ByteBuffer;
24 import java.nio.channels.WritableByteChannel;
25
26 import org.apache.commons.crypto.stream.CryptoOutputStream;
27
28 /**
29 * The Output interface abstract the output target of
30 * {@link CryptoOutputStream} so that different implementation of output
31 * can be used. The implementation Output interface will usually wraps an output
32 * mechanism such as {@link OutputStream} or
33 * {@link WritableByteChannel}.
34 */
35 public interface Output extends Closeable {
36
37 /**
38 * Closes this output and releases any system resources associated with the
39 * under layer output.
40 *
41 * @throws IOException if an I/O error occurs.
42 */
43 @Override
44 void close() throws IOException;
45
46 /**
47 * Flushes this output and forces any buffered output bytes to be written
48 * out if the under layer output method support. The general contract of
49 * {@code flush} is that calling it is an indication that, if any bytes
50 * previously written have been buffered by the implementation of the output
51 * stream, such bytes should immediately be written to their intended
52 * destination.
53 *
54 * @throws IOException if an I/O error occurs.
55 */
56 void flush() throws IOException;
57
58 /**
59 * Writes a sequence of bytes to this output from the given buffer.
60 *
61 * <p>
62 * An attempt is made to write up to <i>r</i> bytes to the channel, where
63 * <i>r</i> is the number of bytes remaining in the buffer, that is,
64 * {@code src.remaining()}, at the moment this method is invoked.
65 *
66 * <p>
67 * Suppose that a byte sequence of length <i>n</i> is written, where
68 * {@code 0} {@code <=} <i>n</i> {@code <=}
69 * <i>r</i>. This byte sequence will be transferred from the buffer
70 * starting at index <i>p</i>, where <i>p</i> is the buffer's position at
71 * the moment this method is invoked; the index of the last byte written
72 * will be <i>p</i> {@code +} <i>n</i> {@code -}
73 * {@code 1}. Upon return the buffer's position will be equal to
74 * <i>p</i> {@code +} <i>n</i>; its limit will not have changed.
75 *
76 * @param src The buffer from which bytes are to be retrieved.
77 *
78 * @return The number of bytes written, possibly zero.
79 *
80 * @throws IOException If some other I/O error occurs.
81 */
82 int write(ByteBuffer src) throws IOException;
83 }