You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@hc.apache.org by ol...@apache.org on 2008/12/14 15:55:27 UTC
svn commit: r726457 - in
/httpcomponents/httpcore/trunk/module-main/src/main/java/org/apache/http:
./ entity/
Author: olegk
Date: Sun Dec 14 06:55:26 2008
New Revision: 726457
URL: http://svn.apache.org/viewvc?rev=726457&view=rev
Log:
Javadoc updates
Modified:
httpcomponents/httpcore/trunk/module-main/src/main/java/org/apache/http/HttpClientConnection.java
httpcomponents/httpcore/trunk/module-main/src/main/java/org/apache/http/HttpServerConnection.java
httpcomponents/httpcore/trunk/module-main/src/main/java/org/apache/http/MethodNotSupportedException.java
httpcomponents/httpcore/trunk/module-main/src/main/java/org/apache/http/ParseException.java
httpcomponents/httpcore/trunk/module-main/src/main/java/org/apache/http/UnsupportedHttpVersionException.java
httpcomponents/httpcore/trunk/module-main/src/main/java/org/apache/http/entity/AbstractHttpEntity.java
httpcomponents/httpcore/trunk/module-main/src/main/java/org/apache/http/entity/BasicHttpEntity.java
httpcomponents/httpcore/trunk/module-main/src/main/java/org/apache/http/entity/ByteArrayEntity.java
httpcomponents/httpcore/trunk/module-main/src/main/java/org/apache/http/entity/ContentLengthStrategy.java
httpcomponents/httpcore/trunk/module-main/src/main/java/org/apache/http/entity/EntityTemplate.java
httpcomponents/httpcore/trunk/module-main/src/main/java/org/apache/http/entity/FileEntity.java
httpcomponents/httpcore/trunk/module-main/src/main/java/org/apache/http/entity/InputStreamEntity.java
httpcomponents/httpcore/trunk/module-main/src/main/java/org/apache/http/entity/SerializableEntity.java
httpcomponents/httpcore/trunk/module-main/src/main/java/org/apache/http/entity/StringEntity.java
httpcomponents/httpcore/trunk/module-main/src/main/java/org/apache/http/entity/package.html
Modified: httpcomponents/httpcore/trunk/module-main/src/main/java/org/apache/http/HttpClientConnection.java
URL: http://svn.apache.org/viewvc/httpcomponents/httpcore/trunk/module-main/src/main/java/org/apache/http/HttpClientConnection.java?rev=726457&r1=726456&r2=726457&view=diff
==============================================================================
--- httpcomponents/httpcore/trunk/module-main/src/main/java/org/apache/http/HttpClientConnection.java (original)
+++ httpcomponents/httpcore/trunk/module-main/src/main/java/org/apache/http/HttpClientConnection.java Sun Dec 14 06:55:26 2008
@@ -63,8 +63,8 @@
/**
* Sends the request line and all headers over the connection.
* @param request the request whose headers to send.
- * @throws HttpException
- * @throws IOException
+ * @throws HttpException in case of HTTP protocol violation
+ * @throws IOException in case of an I/O error
*/
void sendRequestHeader(HttpRequest request)
throws HttpException, IOException;
@@ -72,8 +72,8 @@
/**
* Sends the request entity over the connection.
* @param request the request whose entity to send.
- * @throws HttpException
- * @throws IOException
+ * @throws HttpException in case of HTTP protocol violation
+ * @throws IOException in case of an I/O error
*/
void sendRequestEntity(HttpEntityEnclosingRequest request)
throws HttpException, IOException;
@@ -85,8 +85,8 @@
*
* @return a new HttpResponse object with status line and headers
* initialized.
- * @throws HttpException
- * @throws IOException
+ * @throws HttpException in case of HTTP protocol violation
+ * @throws IOException in case of an I/O error
*/
HttpResponse receiveResponseHeader()
throws HttpException, IOException;
@@ -96,8 +96,8 @@
* attaches it to an existing HttpResponse object.
*
* @param response the response to attach the entity to
- * @throws HttpException
- * @throws IOException
+ * @throws HttpException in case of HTTP protocol violation
+ * @throws IOException in case of an I/O error
*/
void receiveResponseEntity(HttpResponse response)
throws HttpException, IOException;
@@ -105,7 +105,7 @@
/**
* Writes out all pending buffered data over the open connection.
*
- * @throws IOException
+ * @throws IOException in case of an I/O error
*/
void flush() throws IOException;
Modified: httpcomponents/httpcore/trunk/module-main/src/main/java/org/apache/http/HttpServerConnection.java
URL: http://svn.apache.org/viewvc/httpcomponents/httpcore/trunk/module-main/src/main/java/org/apache/http/HttpServerConnection.java?rev=726457&r1=726456&r2=726457&view=diff
==============================================================================
--- httpcomponents/httpcore/trunk/module-main/src/main/java/org/apache/http/HttpServerConnection.java (original)
+++ httpcomponents/httpcore/trunk/module-main/src/main/java/org/apache/http/HttpServerConnection.java Sun Dec 14 06:55:26 2008
@@ -52,8 +52,8 @@
*
* @return a new HttpRequest object whose request line and headers are
* initialized.
- * @throws HttpException
- * @throws IOException
+ * @throws HttpException in case of HTTP protocol violation
+ * @throws IOException in case of an I/O error
*/
HttpRequest receiveRequestHeader()
throws HttpException, IOException;
@@ -62,8 +62,8 @@
* Receives the next request entity available from this connection and attaches it to
* an existing request.
* @param request the request to attach the entity to.
- * @throws HttpException
- * @throws IOException
+ * @throws HttpException in case of HTTP protocol violation
+ * @throws IOException in case of an I/O error
*/
void receiveRequestEntity(HttpEntityEnclosingRequest request)
throws HttpException, IOException;
@@ -71,8 +71,8 @@
/**
* Sends the response line and headers of a response over this connection.
* @param response the response whose headers to send.
- * @throws HttpException
- * @throws IOException
+ * @throws HttpException in case of HTTP protocol violation
+ * @throws IOException in case of an I/O error
*/
void sendResponseHeader(HttpResponse response)
throws HttpException, IOException;
@@ -80,15 +80,15 @@
/**
* Sends the response entity of a response over this connection.
* @param response the response whose entity to send.
- * @throws HttpException
- * @throws IOException
+ * @throws HttpException in case of HTTP protocol violation
+ * @throws IOException in case of an I/O error
*/
void sendResponseEntity(HttpResponse response)
throws HttpException, IOException;
/**
* Sends all pending buffered data over this connection.
- * @throws IOException
+ * @throws IOException in case of an I/O error
*/
void flush()
throws IOException;
Modified: httpcomponents/httpcore/trunk/module-main/src/main/java/org/apache/http/MethodNotSupportedException.java
URL: http://svn.apache.org/viewvc/httpcomponents/httpcore/trunk/module-main/src/main/java/org/apache/http/MethodNotSupportedException.java?rev=726457&r1=726456&r2=726457&view=diff
==============================================================================
--- httpcomponents/httpcore/trunk/module-main/src/main/java/org/apache/http/MethodNotSupportedException.java (original)
+++ httpcomponents/httpcore/trunk/module-main/src/main/java/org/apache/http/MethodNotSupportedException.java Sun Dec 14 06:55:26 2008
@@ -33,7 +33,7 @@
/**
- * Indicates that an HTTP method is not supported.
+ * Signals that an HTTP method is not supported.
*
* @author <a href="mailto:oleg at ural.ru">Oleg Kalnichevski</a>
*
Modified: httpcomponents/httpcore/trunk/module-main/src/main/java/org/apache/http/ParseException.java
URL: http://svn.apache.org/viewvc/httpcomponents/httpcore/trunk/module-main/src/main/java/org/apache/http/ParseException.java?rev=726457&r1=726456&r2=726457&view=diff
==============================================================================
--- httpcomponents/httpcore/trunk/module-main/src/main/java/org/apache/http/ParseException.java (original)
+++ httpcomponents/httpcore/trunk/module-main/src/main/java/org/apache/http/ParseException.java Sun Dec 14 06:55:26 2008
@@ -32,7 +32,7 @@
package org.apache.http;
/**
- * Indicates a parse error.
+ * Signals a parse error.
* Parse errors when receiving a message will typically trigger
* {@link ProtocolException}. Parse errors that do not occur during
* protocol execution may be handled differently.
Modified: httpcomponents/httpcore/trunk/module-main/src/main/java/org/apache/http/UnsupportedHttpVersionException.java
URL: http://svn.apache.org/viewvc/httpcomponents/httpcore/trunk/module-main/src/main/java/org/apache/http/UnsupportedHttpVersionException.java?rev=726457&r1=726456&r2=726457&view=diff
==============================================================================
--- httpcomponents/httpcore/trunk/module-main/src/main/java/org/apache/http/UnsupportedHttpVersionException.java (original)
+++ httpcomponents/httpcore/trunk/module-main/src/main/java/org/apache/http/UnsupportedHttpVersionException.java Sun Dec 14 06:55:26 2008
@@ -34,7 +34,7 @@
import org.apache.http.ProtocolException;
/**
- * Indicates an unsupported version of the HTTP protocol.
+ * Signals an unsupported version of the HTTP protocol.
*
* @author <a href="mailto:oleg at ural.ru">Oleg Kalnichevski</a>
*
Modified: httpcomponents/httpcore/trunk/module-main/src/main/java/org/apache/http/entity/AbstractHttpEntity.java
URL: http://svn.apache.org/viewvc/httpcomponents/httpcore/trunk/module-main/src/main/java/org/apache/http/entity/AbstractHttpEntity.java?rev=726457&r1=726456&r2=726457&view=diff
==============================================================================
--- httpcomponents/httpcore/trunk/module-main/src/main/java/org/apache/http/entity/AbstractHttpEntity.java (original)
+++ httpcomponents/httpcore/trunk/module-main/src/main/java/org/apache/http/entity/AbstractHttpEntity.java Sun Dec 14 06:55:26 2008
@@ -51,28 +51,10 @@
*/
public abstract class AbstractHttpEntity implements HttpEntity {
- /**
- * The Content-Type header.
- * Returned by {@link #getContentType getContentType},
- * unless that method is overridden.
- */
protected Header contentType;
-
- /**
- * The Content-Encoding header.
- * Returned by {@link #getContentEncoding getContentEncoding},
- * unless that method is overridden.
- */
protected Header contentEncoding;
-
- /**
- * The 'chunked' flag.
- * Returned by {@link #isChunked isChunked},
- * unless that method is overridden.
- */
protected boolean chunked;
-
/**
* Protected default constructor.
* The attributes of the created object remain
Modified: httpcomponents/httpcore/trunk/module-main/src/main/java/org/apache/http/entity/BasicHttpEntity.java
URL: http://svn.apache.org/viewvc/httpcomponents/httpcore/trunk/module-main/src/main/java/org/apache/http/entity/BasicHttpEntity.java?rev=726457&r1=726456&r2=726457&view=diff
==============================================================================
--- httpcomponents/httpcore/trunk/module-main/src/main/java/org/apache/http/entity/BasicHttpEntity.java (original)
+++ httpcomponents/httpcore/trunk/module-main/src/main/java/org/apache/http/entity/BasicHttpEntity.java Sun Dec 14 06:55:26 2008
@@ -36,7 +36,8 @@
import java.io.OutputStream;
/**
- * A generic streamed entity being received on a connection.
+ * A generic streamed, non-repeatable entity that obtains its content
+ * from an {@link InputStream}.
*
* @author <a href="mailto:oleg at ural.ru">Oleg Kalnichevski</a>
*
Modified: httpcomponents/httpcore/trunk/module-main/src/main/java/org/apache/http/entity/ByteArrayEntity.java
URL: http://svn.apache.org/viewvc/httpcomponents/httpcore/trunk/module-main/src/main/java/org/apache/http/entity/ByteArrayEntity.java?rev=726457&r1=726456&r2=726457&view=diff
==============================================================================
--- httpcomponents/httpcore/trunk/module-main/src/main/java/org/apache/http/entity/ByteArrayEntity.java (original)
+++ httpcomponents/httpcore/trunk/module-main/src/main/java/org/apache/http/entity/ByteArrayEntity.java Sun Dec 14 06:55:26 2008
@@ -37,7 +37,7 @@
import java.io.OutputStream;
/**
- * An entity whose content is retrieved from a byte array.
+ * A self contained, repeatable entity that obtains its content from a byte array.
*
* @author <a href="mailto:oleg at ural.ru">Oleg Kalnichevski</a>
*
Modified: httpcomponents/httpcore/trunk/module-main/src/main/java/org/apache/http/entity/ContentLengthStrategy.java
URL: http://svn.apache.org/viewvc/httpcomponents/httpcore/trunk/module-main/src/main/java/org/apache/http/entity/ContentLengthStrategy.java?rev=726457&r1=726456&r2=726457&view=diff
==============================================================================
--- httpcomponents/httpcore/trunk/module-main/src/main/java/org/apache/http/entity/ContentLengthStrategy.java (original)
+++ httpcomponents/httpcore/trunk/module-main/src/main/java/org/apache/http/entity/ContentLengthStrategy.java Sun Dec 14 06:55:26 2008
@@ -35,8 +35,8 @@
import org.apache.http.HttpMessage;
/**
- * Represents a strategy to determine the content length based on the properties
- * of an HTTP message.
+ * Represents a strategy to determine length of the enclosed content entity
+ * based on properties of the HTTP message.
*
* @author <a href="mailto:oleg at ural.ru">Oleg Kalnichevski</a>
*
@@ -48,7 +48,18 @@
public static final int IDENTITY = -1;
public static final int CHUNKED = -2;
-
+
+ /**
+ * Returns length of the given message in bytes. The returned value
+ * must be a non-negative number, {@link #IDENTITY} if the end of the
+ * message will be delimited by the end of connection, or {@link #CHUNKED}
+ * if the message is chunk coded
+ *
+ * @param message
+ * @return content length, {@link #IDENTITY}, or {@link #CHUNKED}
+ *
+ * @throws HttpException in case of HTTP protocol violation
+ */
long determineLength(HttpMessage message) throws HttpException;
}
Modified: httpcomponents/httpcore/trunk/module-main/src/main/java/org/apache/http/entity/EntityTemplate.java
URL: http://svn.apache.org/viewvc/httpcomponents/httpcore/trunk/module-main/src/main/java/org/apache/http/entity/EntityTemplate.java?rev=726457&r1=726456&r2=726457&view=diff
==============================================================================
--- httpcomponents/httpcore/trunk/module-main/src/main/java/org/apache/http/entity/EntityTemplate.java (original)
+++ httpcomponents/httpcore/trunk/module-main/src/main/java/org/apache/http/entity/EntityTemplate.java Sun Dec 14 06:55:26 2008
@@ -36,8 +36,8 @@
import java.io.OutputStream;
/**
- * Entity that delegates the process of content generation to an abstract
- * content producer.
+ * Entity that delegates the process of content generation
+ * to a {@link ContentProducer}.
*
* @author <a href="mailto:oleg at ural.ru">Oleg Kalnichevski</a>
*
Modified: httpcomponents/httpcore/trunk/module-main/src/main/java/org/apache/http/entity/FileEntity.java
URL: http://svn.apache.org/viewvc/httpcomponents/httpcore/trunk/module-main/src/main/java/org/apache/http/entity/FileEntity.java?rev=726457&r1=726456&r2=726457&view=diff
==============================================================================
--- httpcomponents/httpcore/trunk/module-main/src/main/java/org/apache/http/entity/FileEntity.java (original)
+++ httpcomponents/httpcore/trunk/module-main/src/main/java/org/apache/http/entity/FileEntity.java Sun Dec 14 06:55:26 2008
@@ -38,7 +38,7 @@
import java.io.OutputStream;
/**
- * An entity whose content is retrieved from a file.
+ * A self contained, repeatable entity that obtains its content from a file.
*
* @author <a href="mailto:oleg at ural.ru">Oleg Kalnichevski</a>
*
Modified: httpcomponents/httpcore/trunk/module-main/src/main/java/org/apache/http/entity/InputStreamEntity.java
URL: http://svn.apache.org/viewvc/httpcomponents/httpcore/trunk/module-main/src/main/java/org/apache/http/entity/InputStreamEntity.java?rev=726457&r1=726456&r2=726457&view=diff
==============================================================================
--- httpcomponents/httpcore/trunk/module-main/src/main/java/org/apache/http/entity/InputStreamEntity.java (original)
+++ httpcomponents/httpcore/trunk/module-main/src/main/java/org/apache/http/entity/InputStreamEntity.java Sun Dec 14 06:55:26 2008
@@ -36,7 +36,8 @@
import java.io.OutputStream;
/**
- * A streamed entity obtaining content from an {@link InputStream InputStream}.
+ * A streamed, non-repeatable entity that obtains its content from
+ * an {@link InputStream}.
*
* @author <a href="mailto:oleg at ural.ru">Oleg Kalnichevski</a>
*
Modified: httpcomponents/httpcore/trunk/module-main/src/main/java/org/apache/http/entity/SerializableEntity.java
URL: http://svn.apache.org/viewvc/httpcomponents/httpcore/trunk/module-main/src/main/java/org/apache/http/entity/SerializableEntity.java?rev=726457&r1=726456&r2=726457&view=diff
==============================================================================
--- httpcomponents/httpcore/trunk/module-main/src/main/java/org/apache/http/entity/SerializableEntity.java (original)
+++ httpcomponents/httpcore/trunk/module-main/src/main/java/org/apache/http/entity/SerializableEntity.java Sun Dec 14 06:55:26 2008
@@ -1,7 +1,7 @@
/*
- * $HeadURL:$
- * $Revision:$
- * $Date:$
+ * $HeadURL$
+ * $Revision$
+ * $Date$
*
* ====================================================================
* Licensed to the Apache Software Foundation (ASF) under one
@@ -39,12 +39,32 @@
import java.io.OutputStream;
import java.io.Serializable;
+/**
+ * A streamed entity that obtains its content from a {@link Serializable}.
+ * The content obtained from the {@link Serializable} instance can
+ * optionally be buffered in a byte array in order to make the
+ * entity self-contained and repeatable.
+ *
+ * @author <a href="mailto:oleg at ural.ru">Oleg Kalnichevski</a>
+ *
+ * @version $Revision$
+ *
+ * @since 4.0
+ */
public class SerializableEntity extends AbstractHttpEntity {
private byte[] objSer;
private Serializable objRef;
+ /**
+ * Creates new instance of this class.
+ *
+ * @param ser input
+ * @param bufferize tells whether the content should be
+ * stored in an internal buffer
+ * @throws IOException in case of an I/O error
+ */
public SerializableEntity(Serializable ser, boolean bufferize) throws IOException {
super();
if (ser == null) {
Modified: httpcomponents/httpcore/trunk/module-main/src/main/java/org/apache/http/entity/StringEntity.java
URL: http://svn.apache.org/viewvc/httpcomponents/httpcore/trunk/module-main/src/main/java/org/apache/http/entity/StringEntity.java?rev=726457&r1=726456&r2=726457&view=diff
==============================================================================
--- httpcomponents/httpcore/trunk/module-main/src/main/java/org/apache/http/entity/StringEntity.java (original)
+++ httpcomponents/httpcore/trunk/module-main/src/main/java/org/apache/http/entity/StringEntity.java Sun Dec 14 06:55:26 2008
@@ -40,7 +40,8 @@
import org.apache.http.protocol.HTTP;
/**
- * An entity whose content is retrieved from a string.
+ * A self contained, repeatable entity that obtains its content from
+ * a {@link String}.
*
* @author <a href="mailto:oleg at ural.ru">Oleg Kalnichevski</a>
*
Modified: httpcomponents/httpcore/trunk/module-main/src/main/java/org/apache/http/entity/package.html
URL: http://svn.apache.org/viewvc/httpcomponents/httpcore/trunk/module-main/src/main/java/org/apache/http/entity/package.html?rev=726457&r1=726456&r2=726457&view=diff
==============================================================================
--- httpcomponents/httpcore/trunk/module-main/src/main/java/org/apache/http/entity/package.html (original)
+++ httpcomponents/httpcore/trunk/module-main/src/main/java/org/apache/http/entity/package.html Sun Dec 14 06:55:26 2008
@@ -38,14 +38,15 @@
An {@link org.apache.http.HttpEntity entity} is the optional content of a
{@link org.apache.http.HttpMessage message}.
-You'll find a basic selection of entity implementations here.
-If you need to send an entity, you can provide it for example as a
+This package provides a basic selection of entity implementations
+that can obtain content from
{@link org.apache.http.entity.ByteArrayEntity byte array},
{@link org.apache.http.entity.StringEntity string},
{@link org.apache.http.entity.FileEntity file}, or through an arbitrary
{@link org.apache.http.entity.InputStreamEntity input stream}.
-If you receive a message with an entity, you typically get that as a
-{@link org.apache.http.entity.BasicHttpEntity basic} entity.
+If a message is received from an open connection, usually it is
+represented by
+{@link org.apache.http.entity.BasicHttpEntity streamed} entity.
Entity implementations can be
{@link org.apache.http.entity.HttpEntityWrapper wrapped},
for example to