src/org/apache/http/HttpEntity.java - platform/external/apache-http - Git at Google

 /*
  * $HeadURL: http://svn.apache.org/repos/asf/httpcomponents/httpcore/trunk/module-main/src/main/java/org/apache/http/HttpEntity.java $
  * $Revision: 645824 $
  * $Date: 2008-04-08 03:12:41 -0700 (Tue, 08 Apr 2008) $
  *
  * ====================================================================
  * Licensed to the Apache Software Foundation (ASF) under one
  * or more contributor license agreements.  See the NOTICE file
  * distributed with this work for additional information
  * regarding copyright ownership.  The ASF licenses this file
  * to you 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.
  * ====================================================================
  *
  * This software consists of voluntary contributions made by many
  * individuals on behalf of the Apache Software Foundation.  For more
  * information on the Apache Software Foundation, please see
  * <http://www.apache.org/>.
  *
  */

 package org.apache.http;

 import java.io.IOException;
 import java.io.InputStream;
 import java.io.OutputStream;

 /**
  * An entity that can be sent or received with an HTTP message.
  * Entities can be found in some
  * {@link HttpEntityEnclosingRequest requests} and in
  * {@link HttpResponse responses}, where they are optional.
  * <p>
  * In some places, the JavaDoc distinguishes three kinds of entities,
  * depending on where their {@link #getContent content} originates:
  * <ul>
  * <li><b>streamed</b>: The content is received from a stream, or
  *     generated on the fly. In particular, this category includes
  *     entities being received from a {@link HttpConnection connection}.
  *     {@link #isStreaming Streamed} entities are generally not
  *      {@link #isRepeatable repeatable}.
  *     </li>
  * <li><b>self-contained</b>: The content is in memory or obtained by
  *     means that are independent from a connection or other entity.
  *     Self-contained entities are generally {@link #isRepeatable repeatable}.
  *     </li>
  * <li><b>wrapping</b>: The content is obtained from another entity.
  *     </li>
  * </ul>
  * This distinction is important for connection management with incoming
  * entities. For entities that are created by an application and only sent
  * using the HTTP components framework, the difference between streamed
  * and self-contained is of little importance. In that case, it is suggested
  * to consider non-repeatable entities as streamed, and those that are
  * repeatable (without a huge effort) as self-contained.
  *
  * @author <a href="mailto:oleg at ural.ru">Oleg Kalnichevski</a>
  *
  * @version $Revision: 645824 $
  *
  * @since 4.0
  */
 public interface HttpEntity {

     /**
      * Tells if the entity is capable to produce its data more than once.
      * A repeatable entity's getContent() and writeTo(OutputStream) methods
      * can be called more than once whereas a non-repeatable entity's can not.
      * @return true if the entity is repeatable, false otherwise.
      */
     boolean isRepeatable();

     /**
      * Tells about chunked encoding for this entity.
      * The primary purpose of this method is to indicate whether
      * chunked encoding should be used when the entity is sent.
      * For entities that are received, it can also indicate whether
      * the entity was received with chunked encoding.
      * <br/>
      * The behavior of wrapping entities is implementation dependent,
      * but should respect the primary purpose.
      *
      * @return  <code>true</code> if chunked encoding is preferred for this
      *          entity, or <code>false</code> if it is not
      */
     boolean isChunked();

     /**
      * Tells the length of the content, if known.
      *
      * @return  the number of bytes of the content, or
      *          a negative number if unknown. If the content length is known
      *          but exceeds {@link java.lang.Long#MAX_VALUE Long.MAX_VALUE},
      *          a negative number is returned.
      */
     long getContentLength();

     /**
      * Obtains the Content-Type header, if known.
      * This is the header that should be used when sending the entity,
      * or the one that was received with the entity. It can include a
      * charset attribute.
      *
      * @return  the Content-Type header for this entity, or
      *          <code>null</code> if the content type is unknown
      */
     Header getContentType();

     /**
      * Obtains the Content-Encoding header, if known.
      * This is the header that should be used when sending the entity,
      * or the one that was received with the entity.
      * Wrapping entities that modify the content encoding should
      * adjust this header accordingly.
      *
      * @return  the Content-Encoding header for this entity, or
      *          <code>null</code> if the content encoding is unknown
      */
     Header getContentEncoding();

     /**
      * Creates a new InputStream object of the entity.
      * It is a programming error
      * to return the same InputStream object more than once.
      * Entities that are not {@link #isRepeatable repeatable}
      * will throw an exception if this method is called multiple times.
      *
      * @return a new input stream that returns the entity data.
      *
      * @throws IOException if the stream could not be created
      * @throws IllegalStateException
      *  if this entity is not repeatable and the stream
      *  has already been obtained previously
      */
     InputStream getContent() throws IOException, IllegalStateException;

     /**
      * Writes the entity content to the output stream.
      *
      * @param outstream the output stream to write entity content to
      *
      * @throws IOException if an I/O error occurs
      */
     void writeTo(OutputStream outstream) throws IOException;

     /**
      * Tells whether this entity depends on an underlying stream.
      * Streamed entities should return <code>true</code> until the
      * content has been consumed, <code>false</code> afterwards.
      * Self-contained entities should return <code>false</code>.
      * Wrapping entities should delegate this call to the wrapped entity.
      * <br/>
      * The content of a streamed entity is consumed when the stream
      * returned by {@link #getContent getContent} has been read to EOF,
      * or after {@link #consumeContent consumeContent} has been called.
      * If a streamed entity can not detect whether the stream has been
      * read to EOF, it should return <code>true</code> until
      * {@link #consumeContent consumeContent} is called.
      *
      * @return  <code>true</code> if the entity content is streamed and
      *          not yet consumed, <code>false</code> otherwise
      */
     boolean isStreaming(); // don't expect an exception here

     /**
      * TODO: The name of this method is misnomer. It will be renamed to
      * #finish() in the next major release.
      * <br/>
      * This method is called to indicate that the content of this entity
      * is no longer required. All entity implementations are expected to
      * release all allocated resources as a result of this method
      * invocation. Content streaming entities are also expected to
      * dispose of the remaining content, if any. Wrapping entities should
      * delegate this call to the wrapped entity.
      * <br/>
      * This method is of particular importance for entities being
      * received from a {@link HttpConnection connection}. The entity
      * needs to be consumed completely in order to re-use the connection
      * with keep-alive.
      *
      * @throws IOException if an I/O error occurs.
      *          This indicates that connection keep-alive is not possible.
      */
     void consumeContent() throws IOException;

 } // interface HttpEntity
	/*
	* $HeadURL: http://svn.apache.org/repos/asf/httpcomponents/httpcore/trunk/module-main/src/main/java/org/apache/http/HttpEntity.java $
	* $Revision: 645824 $
	* $Date: 2008-04-08 03:12:41 -0700 (Tue, 08 Apr 2008) $
	*
	* ====================================================================
	* Licensed to the Apache Software Foundation (ASF) under one
	* or more contributor license agreements. See the NOTICE file
	* distributed with this work for additional information
	* regarding copyright ownership. The ASF licenses this file
	* to you 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.
	* ====================================================================
	*
	* This software consists of voluntary contributions made by many
	* individuals on behalf of the Apache Software Foundation. For more
	* information on the Apache Software Foundation, please see
	* <http://www.apache.org/>.
	*
	*/

	package org.apache.http;

	import java.io.IOException;
	import java.io.InputStream;
	import java.io.OutputStream;

	/**
	* An entity that can be sent or received with an HTTP message.
	* Entities can be found in some
	* {@link HttpEntityEnclosingRequest requests} and in
	* {@link HttpResponse responses}, where they are optional.
	* <p>
	* In some places, the JavaDoc distinguishes three kinds of entities,
	* depending on where their {@link #getContent content} originates:
	* <ul>
	* <li><b>streamed</b>: The content is received from a stream, or
	* generated on the fly. In particular, this category includes
	* entities being received from a {@link HttpConnection connection}.
	* {@link #isStreaming Streamed} entities are generally not
	* {@link #isRepeatable repeatable}.
	* </li>
	* <li><b>self-contained</b>: The content is in memory or obtained by
	* means that are independent from a connection or other entity.
	* Self-contained entities are generally {@link #isRepeatable repeatable}.
	* </li>
	* <li><b>wrapping</b>: The content is obtained from another entity.
	* </li>
	* </ul>
	* This distinction is important for connection management with incoming
	* entities. For entities that are created by an application and only sent
	* using the HTTP components framework, the difference between streamed
	* and self-contained is of little importance. In that case, it is suggested
	* to consider non-repeatable entities as streamed, and those that are
	* repeatable (without a huge effort) as self-contained.
	*
	* @author <a href="mailto:oleg at ural.ru">Oleg Kalnichevski</a>
	*
	* @version $Revision: 645824 $
	*
	* @since 4.0
	*/
	public interface HttpEntity {

	/**
	* Tells if the entity is capable to produce its data more than once.
	* A repeatable entity's getContent() and writeTo(OutputStream) methods
	* can be called more than once whereas a non-repeatable entity's can not.
	* @return true if the entity is repeatable, false otherwise.
	*/
	boolean isRepeatable();

	/**
	* Tells about chunked encoding for this entity.
	* The primary purpose of this method is to indicate whether
	* chunked encoding should be used when the entity is sent.
	* For entities that are received, it can also indicate whether
	* the entity was received with chunked encoding.
	* <br/>
	* The behavior of wrapping entities is implementation dependent,
	* but should respect the primary purpose.
	*
	* @return <code>true</code> if chunked encoding is preferred for this
	* entity, or <code>false</code> if it is not
	*/
	boolean isChunked();

	/**
	* Tells the length of the content, if known.
	*
	* @return the number of bytes of the content, or
	* a negative number if unknown. If the content length is known
	* but exceeds {@link java.lang.Long#MAX_VALUE Long.MAX_VALUE},
	* a negative number is returned.
	*/
	long getContentLength();

	/**
	* Obtains the Content-Type header, if known.
	* This is the header that should be used when sending the entity,
	* or the one that was received with the entity. It can include a
	* charset attribute.
	*
	* @return the Content-Type header for this entity, or
	* <code>null</code> if the content type is unknown
	*/
	Header getContentType();

	/**
	* Obtains the Content-Encoding header, if known.
	* This is the header that should be used when sending the entity,
	* or the one that was received with the entity.
	* Wrapping entities that modify the content encoding should
	* adjust this header accordingly.
	*
	* @return the Content-Encoding header for this entity, or
	* <code>null</code> if the content encoding is unknown
	*/
	Header getContentEncoding();

	/**
	* Creates a new InputStream object of the entity.
	* It is a programming error
	* to return the same InputStream object more than once.
	* Entities that are not {@link #isRepeatable repeatable}
	* will throw an exception if this method is called multiple times.
	*
	* @return a new input stream that returns the entity data.
	*
	* @throws IOException if the stream could not be created
	* @throws IllegalStateException
	* if this entity is not repeatable and the stream
	* has already been obtained previously
	*/
	InputStream getContent() throws IOException, IllegalStateException;

	/**
	* Writes the entity content to the output stream.
	*
	* @param outstream the output stream to write entity content to
	*
	* @throws IOException if an I/O error occurs
	*/
	void writeTo(OutputStream outstream) throws IOException;

	/**
	* Tells whether this entity depends on an underlying stream.
	* Streamed entities should return <code>true</code> until the
	* content has been consumed, <code>false</code> afterwards.
	* Self-contained entities should return <code>false</code>.
	* Wrapping entities should delegate this call to the wrapped entity.
	* <br/>
	* The content of a streamed entity is consumed when the stream
	* returned by {@link #getContent getContent} has been read to EOF,
	* or after {@link #consumeContent consumeContent} has been called.
	* If a streamed entity can not detect whether the stream has been
	* read to EOF, it should return <code>true</code> until
	* {@link #consumeContent consumeContent} is called.
	*
	* @return <code>true</code> if the entity content is streamed and
	* not yet consumed, <code>false</code> otherwise
	*/
	boolean isStreaming(); // don't expect an exception here

	/**
	* TODO: The name of this method is misnomer. It will be renamed to
	* #finish() in the next major release.
	* <br/>
	* This method is called to indicate that the content of this entity
	* is no longer required. All entity implementations are expected to
	* release all allocated resources as a result of this method
	* invocation. Content streaming entities are also expected to
	* dispose of the remaining content, if any. Wrapping entities should
	* delegate this call to the wrapped entity.
	* <br/>
	* This method is of particular importance for entities being
	* received from a {@link HttpConnection connection}. The entity
	* needs to be consumed completely in order to re-use the connection
	* with keep-alive.
	*
	* @throws IOException if an I/O error occurs.
	* This indicates that connection keep-alive is not possible.
	*/
	void consumeContent() throws IOException;

	} // interface HttpEntity