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.io;
029
030import java.io.IOException;
031
032import org.apache.http.util.CharArrayBuffer;
033
034/**
035 * Session output buffer for blocking connections. This interface is similar to
036 * OutputStream class, but it also provides methods for writing lines of text.
037 * <p>
038 * Implementing classes are also expected to manage intermediate data buffering
039 * for optimal output performance.
040 *
041 * @since 4.0
042 */
043public interface SessionOutputBuffer {
044
045    /**
046     * Writes {@code len} bytes from the specified byte array
047     * starting at offset {@code off} to this session buffer.
048     * <p>
049     * If {@code off} is negative, or {@code len} is negative, or
050     * {@code off+len} is greater than the length of the array
051     * {@code b}, then an {@code IndexOutOfBoundsException} is thrown.
052     *
053     * @param      b     the data.
054     * @param      off   the start offset in the data.
055     * @param      len   the number of bytes to write.
056     * @throws  IOException  if an I/O error occurs.
057     */
058    void write(byte[] b, int off, int len) throws IOException;
059
060    /**
061     * Writes {@code b.length} bytes from the specified byte array
062     * to this session buffer.
063     *
064     * @param      b   the data.
065     * @throws  IOException  if an I/O error occurs.
066     */
067    void write(byte[] b) throws IOException;
068
069    /**
070     * Writes the specified byte to this session buffer.
071     *
072     * @param      b   the {@code byte}.
073     * @throws  IOException  if an I/O error occurs.
074     */
075    void write(int b) throws IOException;
076
077    /**
078     * Writes characters from the specified string followed by a line delimiter
079     * to this session buffer.
080     * <p>
081     * The choice of a char encoding and line delimiter sequence is up to the
082     * specific implementations of this interface.
083     *
084     * @param      s   the line.
085     * @throws  IOException  if an I/O error occurs.
086     */
087    void writeLine(String s) throws IOException;
088
089    /**
090     * Writes characters from the specified char array followed by a line
091     * delimiter to this session buffer.
092     * <p>
093     * The choice of a char encoding and line delimiter sequence is up to the
094     * specific implementations of this interface.
095     *
096     * @param      buffer   the buffer containing chars of the line.
097     * @throws  IOException  if an I/O error occurs.
098     */
099    void writeLine(CharArrayBuffer buffer) throws IOException;
100
101    /**
102     * Flushes this session buffer and forces any buffered output bytes
103     * to be written out. The general contract of {@code flush} is
104     * that calling it is an indication that, if any bytes previously
105     * written have been buffered by the implementation of the output
106     * stream, such bytes should immediately be written to their
107     * intended destination.
108     *
109     * @throws  IOException  if an I/O error occurs.
110     */
111    void flush() throws IOException;
112
113    /**
114     * Returns {@link HttpTransportMetrics} for this session buffer.
115     *
116     * @return transport metrics.
117     */
118    HttpTransportMetrics getMetrics();
119
120}