1   /*
    2    * $HeadURL: https://svn.apache.org/repos/asf/httpcomponents/httpcore/tags/4.0.1/httpcore/src/main/java/org/apache/http/io/SessionOutputBuffer.java $
    3    * $Revision: 744527 $
    4    * $Date: 2009-02-14 18:06:25 +0100 (Sat, 14 Feb 2009) $
    5    *
    6    * ====================================================================
    7    * Licensed to the Apache Software Foundation (ASF) under one
    8    * or more contributor license agreements.  See the NOTICE file
    9    * distributed with this work for additional information
   10    * regarding copyright ownership.  The ASF licenses this file
   11    * to you under the Apache License, Version 2.0 (the
   12    * "License"); you may not use this file except in compliance
   13    * with the License.  You may obtain a copy of the License at
   14    *
   15    *   http://www.apache.org/licenses/LICENSE-2.0
   16    *
   17    * Unless required by applicable law or agreed to in writing,
   18    * software distributed under the License is distributed on an
   19    * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
   20    * KIND, either express or implied.  See the License for the
   21    * specific language governing permissions and limitations
   22    * under the License.
   23    * ====================================================================
   24    *
   25    * This software consists of voluntary contributions made by many
   26    * individuals on behalf of the Apache Software Foundation.  For more
   27    * information on the Apache Software Foundation, please see
   28    * <http://www.apache.org/>.
   29    *
   30    */
   31   
   32   package org.apache.http.io;
   33   
   34   import java.io.IOException;
   35   
   36   import org.apache.http.util.CharArrayBuffer;
   37   
   38   /**
   39    * Session output buffer for blocking connections. This interface is similar to 
   40    * OutputStream class, but it also provides methods for writing lines of text. 
   41    * <p>
   42    * Implementing classes are also expected to manage intermediate data buffering
   43    * for optimal output performance.  
   44    *
   45    *
   46    * @version $Revision: 744527 $
   47    * 
   48    * @since 4.0
   49    */
   50   public interface SessionOutputBuffer {
   51   
   52       /**
   53        * Writes <code>len</code> bytes from the specified byte array 
   54        * starting at offset <code>off</code> to this session buffer.
   55        * <p>
   56        * If <code>off</code> is negative, or <code>len</code> is negative, or 
   57        * <code>off+len</code> is greater than the length of the array 
   58        * <code>b</code>, then an <tt>IndexOutOfBoundsException</tt> is thrown.
   59        *
   60        * @param      b     the data.
   61        * @param      off   the start offset in the data.
   62        * @param      len   the number of bytes to write.
   63        * @exception  IOException  if an I/O error occurs.
   64        */
   65       void write(byte[] b, int off, int len) throws IOException;
   66       
   67       /**
   68        * Writes <code>b.length</code> bytes from the specified byte array 
   69        * to this session buffer.
   70        *
   71        * @param      b   the data.
   72        * @exception  IOException  if an I/O error occurs.
   73        */
   74       void write(byte[] b) throws IOException;
   75       
   76       /**
   77        * Writes the specified byte to this session buffer.
   78        *
   79        * @param      b   the <code>byte</code>.
   80        * @exception  IOException  if an I/O error occurs.
   81        */
   82       void write(int b) throws IOException;
   83       
   84       /**
   85        * Writes characters from the specified string followed by a line delimiter 
   86        * to this session buffer.
   87        * <p>
   88        * The choice of a char encoding and line delimiter sequence is up to the 
   89        * specific implementations of this interface. 
   90        *
   91        * @param      s   the line.
   92        * @exception  IOException  if an I/O error occurs.
   93        */
   94       void writeLine(String s) throws IOException;
   95       
   96       /**
   97        * Writes characters from the specified char array followed by a line 
   98        * delimiter to this session buffer.
   99        * <p>
  100        * The choice of a char encoding and line delimiter sequence is up to the 
  101        * specific implementations of this interface. 
  102        *
  103        * @param      buffer   the buffer containing chars of the line.
  104        * @exception  IOException  if an I/O error occurs.
  105        */
  106       void writeLine(CharArrayBuffer buffer) throws IOException;
  107       
  108       /**
  109        * Flushes this session buffer and forces any buffered output bytes 
  110        * to be written out. The general contract of <code>flush</code> is 
  111        * that calling it is an indication that, if any bytes previously 
  112        * written have been buffered by the implementation of the output 
  113        * stream, such bytes should immediately be written to their 
  114        * intended destination.
  115        *
  116        * @exception  IOException  if an I/O error occurs.
  117        */
  118       void flush() throws IOException;
  119       
  120       /**
  121        * Returns {@link HttpTransportMetrics} for this session buffer.
  122        * 
  123        * @return transport metrics.
  124        */
  125       HttpTransportMetrics getMetrics();
  126       
  127   }