/*
* Producer.java February 2007
*
* Copyright (C) 2001, Niall Gallagher <niallg@users.sf.net>
*
* Licensed under the Apache License, Version 2.0 (the "License");
* you may not use this file except in compliance with the License.
* You may obtain a copy of the License at
*
* http://www.apache.org/licenses/LICENSE-2.0
*
* Unless required by applicable law or agreed to in writing, software
* distributed under the License is distributed on an "AS IS" BASIS,
* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
* implied. See the License for the specific language governing
* permissions and limitations under the License.
*/
package org.simpleframework.http.core;
import java.io.IOException;
import java.nio.ByteBuffer;
/**
* The <code>Producer</code> object is used to produce content from the HTTP
* response. This acts in much the same way as an output stream would. As a
* requirement of RFC 2616 any HTTP/1.1 compliant server must support a set of
* transfer types. These are fixed size, chunked encoded, and connection close.
* A producer implementation is required to implement one of this formats for
* delivery of the response message.
*
* @author Niall Gallagher
*
* @see org.simpleframework.http.core.Monitor
*/
interface Producer {
/**
* This method is used to encode the provided array of bytes in a HTTP/1.1
* compliant format and sent it to the client. Once the data has been
* encoded it is handed to the transport layer within the server, which may
* choose to buffer the data if the content is too small to send efficiently
* or if the socket is not write ready.
*
* @param array
* this is the array of bytes to send to the client
*/
void produce(byte[] array) throws IOException;
/**
* This method is used to encode the provided array of bytes in a HTTP/1.1
* compliant format and sent it to the client. Once the data has been
* encoded it is handed to the transport layer within the server, which may
* choose to buffer the data if the content is too small to send efficiently
* or if the socket is not write ready.
*
* @param array
* this is the array of bytes to send to the client
* @param off
* this is the offset within the array to send from
* @param size
* this is the number of bytes that are to be sent
*/
void produce(byte[] array, int off, int size) throws IOException;
/**
* This method is used to encode the provided buffer of bytes in a HTTP/1.1
* compliant format and sent it to the client. Once the data has been
* encoded it is handed to the transport layer within the server, which may
* choose to buffer the data if the content is too small to send efficiently
* or if the socket is not write ready.
*
* @param buffer
* this is the buffer of bytes to send to the client
*/
void produce(ByteBuffer buffer) throws IOException;
/**
* This method is used to encode the provided buffer of bytes in a HTTP/1.1
* compliant format and sent it to the client. Once the data has been
* encoded it is handed to the transport layer within the server, which may
* choose to buffer the data if the content is too small to send efficiently
* or if the socket is not write ready.
*
* @param buffer
* this is the buffer of bytes to send to the client
* @param off
* this is the offset within the buffer to send from
* @param size
* this is the number of bytes that are to be sent
*/
void produce(ByteBuffer buffer, int off, int size) throws IOException;
/**
* This method is used to flush the contents of the buffer to the client.
* This method will block until such time as all of the data has been sent
* to the client. If at any point there is an error sending the content an
* exception is thrown.
*/
void flush() throws IOException;
/**
* This is used to signal to the producer that all content has been written
* and the user no longer needs to write. This will either close the
* underlying transport or it will notify the monitor that the response has
* completed and the next request can begin. This ensures the content is
* flushed to the client.
*/
void close() throws IOException;
}