001 /*
002 * Licensed to the Apache Software Foundation (ASF) under one
003 * or more contributor license agreements.  See the NOTICE file
004 * distributed with this work for additional information
005 * regarding copyright ownership.  The ASF licenses this file
006 * to you under the Apache License, Version 2.0 (the
007 * "License"); you may not use this file except in compliance
008 * with the License.  You may obtain a copy of the License at
009 *
010 *     http://www.apache.org/licenses/LICENSE-2.0
011 *
012 * Unless required by applicable law or agreed to in writing, software
013 * distributed under the License is distributed on an "AS IS" BASIS,
014 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
015 * See the License for the specific language governing permissions and
016 * limitations under the License.
017 */
018package org.apache.commons.crypto.stream.output;
019
020import java.io.Closeable;
021import java.io.IOException;
022import java.io.OutputStream;
023import java.nio.ByteBuffer;
024import java.nio.channels.WritableByteChannel;
025
026import org.apache.commons.crypto.stream.CryptoOutputStream;
027
028/**
029 * The Output interface abstract the output target of
030 * {@link CryptoOutputStream} so that different implementation of output
031 * can be used. The implementation Output interface will usually wraps an output
032 * mechanism such as {@link OutputStream} or
033 * {@link WritableByteChannel}.
034 */
035public interface Output extends Closeable {
036
037    /**
038     * Closes this output and releases any system resources associated with the
039     * under layer output.
040     *
041     * @throws IOException if an I/O error occurs.
042     */
043    @Override
044    void close() throws IOException;
045
046    /**
047     * Flushes this output and forces any buffered output bytes to be written
048     * out if the under layer output method support. The general contract of
049     * {@code flush} is that calling it is an indication that, if any bytes
050     * previously written have been buffered by the implementation of the output
051     * stream, such bytes should immediately be written to their intended
052     * destination.
053     *
054     * @throws IOException if an I/O error occurs.
055     */
056    void flush() throws IOException;
057
058    /**
059     * Writes a sequence of bytes to this output from the given buffer.
060     *
061     * <p>
062     * An attempt is made to write up to <i>r</i> bytes to the channel, where
063     * <i>r</i> is the number of bytes remaining in the buffer, that is,
064     * {@code src.remaining()}, at the moment this method is invoked.
065     *
066     * <p>
067     * Suppose that a byte sequence of length <i>n</i> is written, where
068     * {@code 0}&nbsp;{@code <=}&nbsp;<i>n</i>&nbsp;{@code <=}
069     * &nbsp;<i>r</i>. This byte sequence will be transferred from the buffer
070     * starting at index <i>p</i>, where <i>p</i> is the buffer's position at
071     * the moment this method is invoked; the index of the last byte written
072     * will be <i>p</i>&nbsp;{@code +}&nbsp;<i>n</i>&nbsp;{@code -}&nbsp;
073     * {@code 1}. Upon return the buffer's position will be equal to
074     * <i>p</i>&nbsp;{@code +}&nbsp;<i>n</i>; its limit will not have changed.
075     *
076     * @param src The buffer from which bytes are to be retrieved.
077     *
078     * @return The number of bytes written, possibly zero.
079     *
080     * @throws IOException If some other I/O error occurs.
081     */
082    int write(ByteBuffer src) throws IOException;
083}