View Javadoc

1   /*
2    * ====================================================================
3    * Licensed to the Apache Software Foundation (ASF) under one
4    * or more contributor license agreements.  See the NOTICE file
5    * distributed with this work for additional information
6    * regarding copyright ownership.  The ASF licenses this file
7    * to you under the Apache License, Version 2.0 (the
8    * "License"); you may not use this file except in compliance
9    * with the License.  You may obtain a copy of the License at
10   *
11   *   http://www.apache.org/licenses/LICENSE-2.0
12   *
13   * Unless required by applicable law or agreed to in writing,
14   * software distributed under the License is distributed on an
15   * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
16   * KIND, either express or implied.  See the License for the
17   * specific language governing permissions and limitations
18   * under the License.
19   * ====================================================================
20   *
21   * This software consists of voluntary contributions made by many
22   * individuals on behalf of the Apache Software Foundation.  For more
23   * information on the Apache Software Foundation, please see
24   * <http://www.apache.org/>.
25   *
26   */
27  
28  package org.apache.http.io;
29  
30  import java.io.IOException;
31  
32  import org.apache.http.util.CharArrayBuffer;
33  
34  /**
35   * Session output buffer for blocking connections. This interface is similar to
36   * OutputStream class, but it also provides methods for writing lines of text.
37   * <p>
38   * Implementing classes are also expected to manage intermediate data buffering
39   * for optimal output performance.
40   *
41   * @since 4.0
42   */
43  public interface SessionOutputBuffer {
44  
45      /**
46       * Writes <code>len</code> bytes from the specified byte array
47       * starting at offset <code>off</code> to this session buffer.
48       * <p>
49       * If <code>off</code> is negative, or <code>len</code> is negative, or
50       * <code>off+len</code> is greater than the length of the array
51       * <code>b</code>, then an <tt>IndexOutOfBoundsException</tt> is thrown.
52       *
53       * @param      b     the data.
54       * @param      off   the start offset in the data.
55       * @param      len   the number of bytes to write.
56       * @exception  IOException  if an I/O error occurs.
57       */
58      void write(byte[] b, int off, int len) throws IOException;
59  
60      /**
61       * Writes <code>b.length</code> bytes from the specified byte array
62       * to this session buffer.
63       *
64       * @param      b   the data.
65       * @exception  IOException  if an I/O error occurs.
66       */
67      void write(byte[] b) throws IOException;
68  
69      /**
70       * Writes the specified byte to this session buffer.
71       *
72       * @param      b   the <code>byte</code>.
73       * @exception  IOException  if an I/O error occurs.
74       */
75      void write(int b) throws IOException;
76  
77      /**
78       * Writes characters from the specified string followed by a line delimiter
79       * to this session buffer.
80       * <p>
81       * The choice of a char encoding and line delimiter sequence is up to the
82       * specific implementations of this interface.
83       *
84       * @param      s   the line.
85       * @exception  IOException  if an I/O error occurs.
86       */
87      void writeLine(String s) throws IOException;
88  
89      /**
90       * Writes characters from the specified char array followed by a line
91       * delimiter to this session buffer.
92       * <p>
93       * The choice of a char encoding and line delimiter sequence is up to the
94       * specific implementations of this interface.
95       *
96       * @param      buffer   the buffer containing chars of the line.
97       * @exception  IOException  if an I/O error occurs.
98       */
99      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</code> 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      * @exception  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 }