You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@hc.apache.org by gg...@apache.org on 2024/06/10 14:35:57 UTC
(httpcomponents-core) branch master updated: Javadoc
This is an automated email from the ASF dual-hosted git repository.
ggregory pushed a commit to branch master
in repository https://gitbox.apache.org/repos/asf/httpcomponents-core.git
The following commit(s) were added to refs/heads/master by this push:
new 2c8aebea6 Javadoc
2c8aebea6 is described below
commit 2c8aebea6764f998788a46fe238b3312dd07c565
Author: Gary Gregory <ga...@gmail.com>
AuthorDate: Mon Jun 10 10:35:53 2024 -0400
Javadoc
---
.../org/apache/hc/core5/http/EntityDetails.java | 19 ++++--
.../java/org/apache/hc/core5/http/HttpEntity.java | 8 +--
.../core5/http/io/entity/AbstractHttpEntity.java | 68 ++++++++++++++++++++++
3 files changed, 86 insertions(+), 9 deletions(-)
diff --git a/httpcore5/src/main/java/org/apache/hc/core5/http/EntityDetails.java b/httpcore5/src/main/java/org/apache/hc/core5/http/EntityDetails.java
index d46325c2c..69399dc1b 100644
--- a/httpcore5/src/main/java/org/apache/hc/core5/http/EntityDetails.java
+++ b/httpcore5/src/main/java/org/apache/hc/core5/http/EntityDetails.java
@@ -37,31 +37,40 @@ import java.util.Set;
public interface EntityDetails {
/**
- * Returns length of the entity, if known.
+ * Gets length of this entity, if known.
+ *
+ * @return the length of this entity, may be {@code 0}.
*/
long getContentLength();
/**
- * Returns content type of the entity, if known.
+ * Gets content type of this entity, if known.
+ *
+ * @return the content type of this entity, may be {@code null}.
*/
String getContentType();
/**
- * Returns content encoding of the entity, if known.
+ * Gets content encoding of this entity, if known.
+ *
+ * @return the content encoding of this entity, may be {@code null}.
*/
String getContentEncoding();
/**
- * Returns chunked transfer hint for this entity.
+ * Tests the chunked transfer hint for this entity.
* <p>
* The behavior of wrapping entities is implementation dependent,
* but should respect the primary purpose.
* </p>
+ * @return the chunked transfer hint for this entity.
*/
boolean isChunked();
/**
- * Preliminary declaration of trailing headers.
+ * Gets the preliminary declaration of trailing headers.
+ *
+ * @return the preliminary declaration of trailing headers.
*/
Set<String> getTrailerNames();
diff --git a/httpcore5/src/main/java/org/apache/hc/core5/http/HttpEntity.java b/httpcore5/src/main/java/org/apache/hc/core5/http/HttpEntity.java
index 331aff586..74aa587bc 100644
--- a/httpcore5/src/main/java/org/apache/hc/core5/http/HttpEntity.java
+++ b/httpcore5/src/main/java/org/apache/hc/core5/http/HttpEntity.java
@@ -69,7 +69,7 @@ import org.apache.hc.core5.function.Supplier;
public interface HttpEntity extends EntityDetails, Closeable {
/**
- * Tells if the entity is capable of producing its data more than once.
+ * Tests if the entity is capable of producing 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.
@@ -77,7 +77,7 @@ public interface HttpEntity extends EntityDetails, Closeable {
boolean isRepeatable();
/**
- * Returns a content stream of the entity.
+ * Gets a content stream of the entity.
* {@link #isRepeatable Repeatable} entities are expected
* to create a new instance of {@link InputStream} for each invocation
* of this method and therefore can be consumed multiple times.
@@ -123,7 +123,7 @@ public interface HttpEntity extends EntityDetails, Closeable {
void writeTo(OutputStream outStream) throws IOException;
/**
- * Tells whether this entity depends on an underlying stream.
+ * Tests whether this entity depends on an underlying stream.
* Streamed entities that read data directly from the socket should
* return {@code true}. Self-contained entities should return
* {@code false}. Wrapping entities should delegate this call
@@ -135,7 +135,7 @@ public interface HttpEntity extends EntityDetails, Closeable {
boolean isStreaming(); // don't expect an exception here
/**
- * Returns supplier of message trailers - headers sent after message body.
+ * Gets supplier of message trailers - headers sent after message body.
* May return {@code null} if trailers are not available.
*
* @since 5.0
diff --git a/httpcore5/src/main/java/org/apache/hc/core5/http/io/entity/AbstractHttpEntity.java b/httpcore5/src/main/java/org/apache/hc/core5/http/io/entity/AbstractHttpEntity.java
index c757e284f..1a4b75cfd 100644
--- a/httpcore5/src/main/java/org/apache/hc/core5/http/io/entity/AbstractHttpEntity.java
+++ b/httpcore5/src/main/java/org/apache/hc/core5/http/io/entity/AbstractHttpEntity.java
@@ -43,6 +43,9 @@ import org.apache.hc.core5.util.Args;
/**
* Abstract base class for mutable entities. Provides the commonly used attributes for streamed and
* self-contained implementations.
+ * <p>
+ * This class contains immutable attributes but subclasses may contain additional immutable or mutable attributes.
+ * </p>
*
* @since 4.0
*/
@@ -54,26 +57,60 @@ public abstract class AbstractHttpEntity implements HttpEntity {
private final String contentEncoding;
private final boolean chunked;
+ /**
+ * Constructs a new instance with the given attributes kept as immutable.
+ *
+ * @param contentType The content-type string, may be null.
+ * @param contentEncoding The content encoding string, may be null.
+ * @param chunked Whether this entity should be chunked.
+ */
protected AbstractHttpEntity(final String contentType, final String contentEncoding, final boolean chunked) {
this.contentType = contentType;
this.contentEncoding = contentEncoding;
this.chunked = chunked;
}
+ /**
+ * Constructs a new instance with the given attributes kept as immutable.
+ *
+ * @param contentType The content-type, may be null.
+ * @param contentEncoding The content encoding string, may be null.
+ * @param chunked Whether this entity should be chunked.
+ */
protected AbstractHttpEntity(final ContentType contentType, final String contentEncoding, final boolean chunked) {
this.contentType = contentType != null ? contentType.toString() : null;
this.contentEncoding = contentEncoding;
this.chunked = chunked;
}
+ /**
+ * Constructs a new instance with the given attributes kept as immutable.
+ *
+ * @param contentType The content-type string, may be null.
+ * @param contentEncoding The content encoding string, may be null.
+ */
protected AbstractHttpEntity(final String contentType, final String contentEncoding) {
this(contentType, contentEncoding, false);
}
+ /**
+ * Constructs a new instance with the given attributes kept as immutable.
+ *
+ * @param contentType The content-type, may be null.
+ * @param contentEncoding The content encoding string, may be null.
+ */
protected AbstractHttpEntity(final ContentType contentType, final String contentEncoding) {
this(contentType, contentEncoding, false);
}
+ /**
+ * Writes an entity to an OutputStream.
+ *
+ * @param entity The entity to write, never null.
+ * @param outStream Where to write the entity, never null.
+ * @throws IOException if the entity cannot generate its content stream; also thrown if the output stream is closed.
+ * @throws UnsupportedOperationException if entity content cannot be represented as {@link java.io.InputStream}.
+ */
public static void writeTo(final HttpEntity entity, final OutputStream outStream) throws IOException {
Args.notNull(entity, "Entity");
Args.notNull(outStream, "Output stream");
@@ -88,6 +125,13 @@ public abstract class AbstractHttpEntity implements HttpEntity {
}
}
+ /**
+ * Writes this entity to an OutputStream.
+ *
+ * @param outStream Where to write the entity, never null.
+ * @throws IOException if the entity cannot generate its content stream; also thrown if the output stream is closed.
+ * @throws UnsupportedOperationException if entity content cannot be represented as {@link java.io.InputStream}.
+ */
@Override
public void writeTo(final OutputStream outStream) throws IOException {
writeTo(this, outStream);
@@ -103,21 +147,45 @@ public abstract class AbstractHttpEntity implements HttpEntity {
return contentEncoding;
}
+ /**
+ * {@inheritDoc}
+ * <p>
+ * This implementation always returns {@code false}.
+ * </p>
+ */
@Override
public final boolean isChunked() {
return chunked;
}
+ /**
+ * {@inheritDoc}
+ * <p>
+ * This implementation always returns {@code false}.
+ * </p>
+ */
@Override
public boolean isRepeatable() {
return false;
}
+ /**
+ * {@inheritDoc}
+ * <p>
+ * This implementation always returns {@code null}.
+ * </p>
+ */
@Override
public Supplier<List<? extends Header>> getTrailers() {
return null;
}
+ /**
+ * {@inheritDoc}
+ * <p>
+ * This implementation always returns an immutable empty set.
+ * </p>
+ */
@Override
public Set<String> getTrailerNames() {
return Collections.emptySet();