001/*
002 * ====================================================================
003 * Licensed to the Apache Software Foundation (ASF) under one
004 * or more contributor license agreements.  See the NOTICE file
005 * distributed with this work for additional information
006 * regarding copyright ownership.  The ASF licenses this file
007 * to you under the Apache License, Version 2.0 (the
008 * "License"); you may not use this file except in compliance
009 * with the License.  You may obtain a copy of the License at
010 *
011 *   http://www.apache.org/licenses/LICENSE-2.0
012 *
013 * Unless required by applicable law or agreed to in writing,
014 * software distributed under the License is distributed on an
015 * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
016 * KIND, either express or implied.  See the License for the
017 * specific language governing permissions and limitations
018 * under the License.
019 * ====================================================================
020 *
021 * This software consists of voluntary contributions made by many
022 * individuals on behalf of the Apache Software Foundation.  For more
023 * information on the Apache Software Foundation, please see
024 * <http://www.apache.org/>.
025 *
026 */
027
028package org.apache.http.nio.reactor;
029
030import java.io.IOException;
031import java.nio.ByteBuffer;
032import java.nio.channels.ReadableByteChannel;
033import java.nio.channels.WritableByteChannel;
034import java.nio.charset.CharacterCodingException;
035
036import org.apache.http.util.CharArrayBuffer;
037
038/**
039 * Session output buffer for non-blocking connections. This interface
040 * facilitates intermediate buffering of output data streamed out to
041 * a destination channel and writing data to the buffer from a source, usually
042 * {@link ByteBuffer} or {@link ReadableByteChannel}. This interface also
043 * provides methods for writing lines of text.
044 *
045 * @since 4.0
046 */
047public interface SessionOutputBuffer {
048
049    /**
050     * Determines if the buffer contains data.
051     *
052     * @return {@code true} if there is data in the buffer,
053     *   {@code false} otherwise.
054     */
055    boolean hasData();
056
057    /**
058     * Returns the length of this buffer.
059     *
060     * @return buffer length.
061     */
062    int length();
063
064    /**
065     * Makes an attempt to flush the content of this buffer to the given
066     * destination {@link WritableByteChannel}.
067     *
068     * @param channel the destination channel.
069     * @return The number of bytes written, possibly zero.
070     * @throws IOException in case of an I/O error.
071     */
072    int flush(WritableByteChannel channel)
073        throws IOException;
074
075    /**
076     * Copies content of the source buffer into this buffer. The capacity of
077     * the destination will be expanded in order to accommodate the entire
078     * content of the source buffer.
079     *
080     * @param src the source buffer.
081     */
082    void write(ByteBuffer src);
083
084    /**
085     * Reads a sequence of bytes from the source channel into this buffer.
086     *
087     * @param src the source channel.
088     */
089    void write(ReadableByteChannel src)
090        throws IOException;
091
092    /**
093     * Copies content of the source buffer into this buffer as one line of text
094     * including a line delimiter. The capacity of the destination will be
095     * expanded in order to accommodate the entire content of the source buffer.
096     * <p>
097     * The choice of a char encoding and line delimiter sequence is up to the
098     * specific implementations of this interface.
099     *
100     * @param src the source buffer.
101     */
102    void writeLine(CharArrayBuffer src)
103        throws CharacterCodingException;
104
105    /**
106     * Copies content of the given string into this buffer as one line of text
107     * including a line delimiter.
108     * The capacity of the destination will be expanded in order to accommodate
109     * the entire string.
110     * <p>
111     * The choice of a char encoding and line delimiter sequence is up to the
112     * specific implementations of this interface.
113     *
114     * @param s the string.
115     */
116    void writeLine(String s)
117        throws IOException;
118
119}