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}