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.nio.ByteBuffer;
023
024/**
025 * The Output interface abstract the output target of
026 * {@code CryptoOutputStream} so that different implementation of output
027 * can be used. The implementation Output interface will usually wraps an output
028 * mechanism such as {@code OutputStream} or
029 * {@code WritableByteChannel}.
030 */
031public interface Output extends Closeable {
032
033    /**
034     * Writes a sequence of bytes to this output from the given buffer.
035     *
036     * <p>
037     * An attempt is made to write up to <i>r</i> bytes to the channel, where
038     * <i>r</i> is the number of bytes remaining in the buffer, that is,
039     * {@code src.remaining()}, at the moment this method is invoked.
040     *
041     * <p>
042     * Suppose that a byte sequence of length <i>n</i> is written, where
043     * {@code 0}&nbsp;{@code <=}&nbsp;<i>n</i>&nbsp;{@code <=}
044     * &nbsp;<i>r</i>. This byte sequence will be transferred from the buffer
045     * starting at index <i>p</i>, where <i>p</i> is the buffer's position at
046     * the moment this method is invoked; the index of the last byte written
047     * will be <i>p</i>&nbsp;{@code +}&nbsp;<i>n</i>&nbsp;{@code -}&nbsp;
048     * {@code 1}. Upon return the buffer's position will be equal to
049     * <i>p</i>&nbsp;{@code +}&nbsp;<i>n</i>; its limit will not have changed.
050     *
051     * @param src The buffer from which bytes are to be retrieved.
052     *
053     * @return The number of bytes written, possibly zero.
054     *
055     * @throws IOException If some other I/O error occurs.
056     */
057    int write(ByteBuffer src) throws IOException;
058
059    /**
060     * Flushes this output and forces any buffered output bytes to be written
061     * out if the under layer output method support. The general contract of
062     * {@code flush} is that calling it is an indication that, if any bytes
063     * previously written have been buffered by the implementation of the output
064     * stream, such bytes should immediately be written to their intended
065     * destination.
066     *
067     * @throws IOException if an I/O error occurs.
068     */
069    void flush() throws IOException;
070
071    /**
072     * Closes this output and releases any system resources associated with the
073     * under layer output.
074     *
075     * @throws IOException if an I/O error occurs.
076     */
077    void close() throws IOException;
078}