Javadoc improvements
- Javadoc: Add missing comments
- Javadoc: Add missing tags
- Javadoc: Sentences end in a period
- Javadoc: Reduce whitespace
diff --git a/httpcore5-h2/src/main/java/org/apache/hc/core5/http2/ssl/ApplicationProtocol.java b/httpcore5-h2/src/main/java/org/apache/hc/core5/http2/ssl/ApplicationProtocol.java
index c4f55ab..d55cf61 100644
--- a/httpcore5-h2/src/main/java/org/apache/hc/core5/http2/ssl/ApplicationProtocol.java
+++ b/httpcore5-h2/src/main/java/org/apache/hc/core5/http2/ssl/ApplicationProtocol.java
@@ -34,8 +34,19 @@
*/
public enum ApplicationProtocol {
- HTTP_2("h2"), HTTP_1_1("http/1.1");
+ /**
+ * The HTTP/2 application protocol.
+ */
+ HTTP_2("h2"),
+ /**
+ * The HTTP/1.1 application protocol.
+ */
+ HTTP_1_1("http/1.1");
+
+ /**
+ * The application protocol ID.
+ */
public final String id;
ApplicationProtocol(final String id) {
diff --git a/httpcore5/src/main/java/org/apache/hc/core5/annotation/Contract.java b/httpcore5/src/main/java/org/apache/hc/core5/annotation/Contract.java
index 8a87a25..20177c4 100644
--- a/httpcore5/src/main/java/org/apache/hc/core5/annotation/Contract.java
+++ b/httpcore5/src/main/java/org/apache/hc/core5/annotation/Contract.java
@@ -33,13 +33,21 @@
import java.lang.annotation.Target;
/**
- * This annotation defines behavioral contract enforced at runtime by instances of annotated classes.
+ * Defines behavioral contract enforced at runtime by instances of annotated classes.
*/
@Documented
@Target(ElementType.TYPE)
@Retention(RetentionPolicy.CLASS)
public @interface Contract {
+ /**
+ * Gets the threading behavior for annotated type.
+ * <p>
+ * The default value is {@link ThreadingBehavior#UNSAFE}.
+ * </p>
+ *
+ * @return the threading behavior for annotated type.
+ */
ThreadingBehavior threading() default ThreadingBehavior.UNSAFE;
}
diff --git a/httpcore5/src/main/java/org/apache/hc/core5/concurrent/BasicFuture.java b/httpcore5/src/main/java/org/apache/hc/core5/concurrent/BasicFuture.java
index 3cfe544..6304b2f 100644
--- a/httpcore5/src/main/java/org/apache/hc/core5/concurrent/BasicFuture.java
+++ b/httpcore5/src/main/java/org/apache/hc/core5/concurrent/BasicFuture.java
@@ -57,6 +57,11 @@ public class BasicFuture<T> implements Future<T>, Cancellable {
private final ReentrantLock lock;
private final Condition condition;
+ /**
+ * Constructs a new instance for a FutureCallback.
+ *
+ * @param callback the FutureCallback, may be {@code null}.
+ */
public BasicFuture(final FutureCallback<T> callback) {
super();
this.callback = callback;
diff --git a/httpcore5/src/main/java/org/apache/hc/core5/concurrent/CallbackContribution.java b/httpcore5/src/main/java/org/apache/hc/core5/concurrent/CallbackContribution.java
index 4dc602f..90e3f1a 100644
--- a/httpcore5/src/main/java/org/apache/hc/core5/concurrent/CallbackContribution.java
+++ b/httpcore5/src/main/java/org/apache/hc/core5/concurrent/CallbackContribution.java
@@ -27,7 +27,7 @@
package org.apache.hc.core5.concurrent;
/**
- * Convenience base class for {@link FutureCallback}s that contribute a result
+ * Abstracts implementations of {@link FutureCallback}s that contribute a result
* of the operation to another {@link FutureCallback}.
*
* @param <T> the future result type of an asynchronous operation.
@@ -37,6 +37,11 @@ public abstract class CallbackContribution<T> implements FutureCallback<T> {
private final FutureCallback<?> callback;
+ /**
+ * Constructs a new instance for a FutureCallback.
+ *
+ * @param callback the FutureCallback, may be {@code null}.
+ */
public CallbackContribution(final FutureCallback<?> callback) {
this.callback = callback;
}
diff --git a/httpcore5/src/main/java/org/apache/hc/core5/http/config/Lookup.java b/httpcore5/src/main/java/org/apache/hc/core5/http/config/Lookup.java
index 3fcc660..28fc9c0 100644
--- a/httpcore5/src/main/java/org/apache/hc/core5/http/config/Lookup.java
+++ b/httpcore5/src/main/java/org/apache/hc/core5/http/config/Lookup.java
@@ -36,6 +36,12 @@
*/
public interface Lookup<I> {
+ /**
+ * Looks up a value using a lower-case string ID.
+ *
+ * @param name The lookup name.
+ * @return The matching value.
+ */
I lookup(String name);
}
diff --git a/httpcore5/src/main/java/org/apache/hc/core5/http/config/RegistryBuilder.java b/httpcore5/src/main/java/org/apache/hc/core5/http/config/RegistryBuilder.java
index af31c76..ee65c44 100644
--- a/httpcore5/src/main/java/org/apache/hc/core5/http/config/RegistryBuilder.java
+++ b/httpcore5/src/main/java/org/apache/hc/core5/http/config/RegistryBuilder.java
@@ -43,6 +43,12 @@ public final class RegistryBuilder<I> {
private final Map<String, I> items;
+ /**
+ * Creates a new RegistryBuilder.
+ *
+ * @param <I> the type of Registry values.
+ * @return a new RegistryBuilder.
+ */
public static <I> RegistryBuilder<I> create() {
return new RegistryBuilder<>();
}
@@ -52,6 +58,13 @@ public static <I> RegistryBuilder<I> create() {
this.items = new HashMap<>();
}
+ /**
+ * Registers the given item for the given ID.
+ *
+ * @param id The ID key, converted to lower-case.
+ * @param item The item to register.
+ * @return this instance.
+ */
public RegistryBuilder<I> register(final String id, final I item) {
Args.notEmpty(id, "ID");
Args.notNull(item, "Item");
@@ -59,6 +72,11 @@ public RegistryBuilder<I> register(final String id, final I item) {
return this;
}
+ /**
+ * Creates a new Registry with the registered items.
+ *
+ * @return a new Registry with the registered items.
+ */
public Registry<I> build() {
return new Registry<>(items);
}
diff --git a/httpcore5/src/main/java/org/apache/hc/core5/http/impl/bootstrap/AsyncServerBootstrap.java b/httpcore5/src/main/java/org/apache/hc/core5/http/impl/bootstrap/AsyncServerBootstrap.java
index 185a17d..a47d041 100644
--- a/httpcore5/src/main/java/org/apache/hc/core5/http/impl/bootstrap/AsyncServerBootstrap.java
+++ b/httpcore5/src/main/java/org/apache/hc/core5/http/impl/bootstrap/AsyncServerBootstrap.java
@@ -59,6 +59,7 @@
import org.apache.hc.core5.http.nio.support.DefaultAsyncResponseExchangeHandlerFactory;
import org.apache.hc.core5.http.nio.support.TerminalAsyncServerFilter;
import org.apache.hc.core5.http.protocol.HttpProcessor;
+import org.apache.hc.core5.http.protocol.LookupRegistry;
import org.apache.hc.core5.http.protocol.UriPatternType;
import org.apache.hc.core5.net.InetAddressUtils;
import org.apache.hc.core5.net.URIAuthority;
@@ -99,6 +100,11 @@ private AsyncServerBootstrap() {
this.filters = new ArrayList<>();
}
+ /**
+ * Creates a new AsyncServerBootstrap instance.
+ *
+ * @return a new AsyncServerBootstrap instance.
+ */
public static AsyncServerBootstrap bootstrap() {
return new AsyncServerBootstrap();
}
@@ -106,6 +112,7 @@ public static AsyncServerBootstrap bootstrap() {
/**
* Sets canonical name (fully qualified domain name) of the server.
*
+ * @param canonicalHostName canonical name (fully qualified domain name) of the server.
* @return this instance.
*/
public final AsyncServerBootstrap setCanonicalHostName(final String canonicalHostName) {
@@ -116,6 +123,7 @@ public final AsyncServerBootstrap setCanonicalHostName(final String canonicalHos
/**
* Sets I/O reactor configuration.
*
+ * @param ioReactorConfig I/O reactor configuration.
* @return this instance.
*/
public final AsyncServerBootstrap setIOReactorConfig(final IOReactorConfig ioReactorConfig) {
@@ -126,6 +134,7 @@ public final AsyncServerBootstrap setIOReactorConfig(final IOReactorConfig ioRea
/**
* Sets HTTP/1.1 protocol parameters.
*
+ * @param http1Config HTTP/1.1 protocol parameters.
* @return this instance.
*/
public final AsyncServerBootstrap setHttp1Config(final Http1Config http1Config) {
@@ -134,8 +143,9 @@ public final AsyncServerBootstrap setHttp1Config(final Http1Config http1Config)
}
/**
- * Sets connection configuration.
+ * Sets char coding configuration.
*
+ * @param charCodingConfig char coding configuration.
* @return this instance.
*/
public final AsyncServerBootstrap setCharCodingConfig(final CharCodingConfig charCodingConfig) {
@@ -144,8 +154,9 @@ public final AsyncServerBootstrap setCharCodingConfig(final CharCodingConfig cha
}
/**
- * Sets {@link org.apache.hc.core5.http.protocol.HttpProcessor} instance.
+ * Sets {@link HttpProcessor} instance.
*
+ * @param httpProcessor {@link HttpProcessor} instance.
* @return this instance.
*/
public final AsyncServerBootstrap setHttpProcessor(final HttpProcessor httpProcessor) {
@@ -154,8 +165,9 @@ public final AsyncServerBootstrap setHttpProcessor(final HttpProcessor httpProce
}
/**
- * Sets {@link org.apache.hc.core5.http.ConnectionReuseStrategy} instance.
+ * Sets {@link ConnectionReuseStrategy} instance.
*
+ * @param connStrategy {@link ConnectionReuseStrategy} instance.
* @return this instance.
*/
public final AsyncServerBootstrap setConnectionReuseStrategy(final ConnectionReuseStrategy connStrategy) {
@@ -166,6 +178,7 @@ public final AsyncServerBootstrap setConnectionReuseStrategy(final ConnectionReu
/**
* Sets {@link TlsStrategy} instance.
*
+ * @param tlsStrategy {@link TlsStrategy} instance.
* @return this instance.
*/
public final AsyncServerBootstrap setTlsStrategy(final TlsStrategy tlsStrategy) {
@@ -176,6 +189,7 @@ public final AsyncServerBootstrap setTlsStrategy(final TlsStrategy tlsStrategy)
/**
* Sets TLS handshake {@link Timeout}.
*
+ * @param handshakeTimeout TLS handshake {@link Timeout}.
* @return this instance.
*/
public final AsyncServerBootstrap setTlsHandshakeTimeout(final Timeout handshakeTimeout) {
@@ -186,6 +200,7 @@ public final AsyncServerBootstrap setTlsHandshakeTimeout(final Timeout handshake
/**
* Sets {@link IOSession} {@link Decorator} instance.
*
+ * @param ioSessionDecorator {@link IOSession} {@link Decorator} instance.
* @return this instance.
*/
public final AsyncServerBootstrap setIOSessionDecorator(final Decorator<IOSession> ioSessionDecorator) {
@@ -196,6 +211,7 @@ public final AsyncServerBootstrap setIOSessionDecorator(final Decorator<IOSessio
/**
* Sets {@link Exception} {@link Callback} instance.
*
+ * @param exceptionCallback {@link Exception} {@link Callback} instance.
* @return this instance.
*/
public final AsyncServerBootstrap setExceptionCallback(final Callback<Exception> exceptionCallback) {
@@ -206,6 +222,7 @@ public final AsyncServerBootstrap setExceptionCallback(final Callback<Exception>
/**
* Sets {@link IOSessionListener} instance.
*
+ * @param sessionListener {@link IOSessionListener} instance.
* @return this instance.
*/
public final AsyncServerBootstrap setIOSessionListener(final IOSessionListener sessionListener) {
@@ -214,11 +231,14 @@ public final AsyncServerBootstrap setIOSessionListener(final IOSessionListener s
}
/**
+ * Sets a LookupRegistry for Suppliers of AsyncServerExchangeHandler.
+ *
+ * @param lookupRegistry LookupRegistry for Suppliers of AsyncServerExchangeHandler.
* @return this instance.
* @deprecated Use {@link RequestRouter}.
*/
@Deprecated
- public final AsyncServerBootstrap setLookupRegistry(final org.apache.hc.core5.http.protocol.LookupRegistry<Supplier<AsyncServerExchangeHandler>> lookupRegistry) {
+ public final AsyncServerBootstrap setLookupRegistry(final LookupRegistry<Supplier<AsyncServerExchangeHandler>> lookupRegistry) {
this.lookupRegistry = lookupRegistry;
return this;
}
@@ -226,6 +246,7 @@ public final AsyncServerBootstrap setLookupRegistry(final org.apache.hc.core5.ht
/**
* Sets {@link HttpRequestMapper} instance.
*
+ * @param requestRouter {@link HttpRequestMapper} instance.
* @return this instance.
* @see org.apache.hc.core5.http.impl.routing.RequestRouter
* @since 5.3
@@ -238,6 +259,7 @@ public final AsyncServerBootstrap setRequestRouter(final HttpRequestMapper<Suppl
/**
* Sets {@link Http1StreamListener} instance.
*
+ * @param streamListener {@link Http1StreamListener} instance.
* @return this instance.
* @since 5.0
*/
@@ -250,8 +272,8 @@ public final AsyncServerBootstrap setStreamListener(final Http1StreamListener st
* Registers the given {@link AsyncServerExchangeHandler} {@link Supplier} as a default handler for URIs
* matching the given pattern.
*
- * @param uriPattern the pattern to register the handler for.
- * @param supplier the handler supplier.
+ * @param uriPattern the non-null pattern to register the handler for.
+ * @param supplier the non-null handler supplier.
* @return this instance.
*/
public final AsyncServerBootstrap register(final String uriPattern, final Supplier<AsyncServerExchangeHandler> supplier) {
@@ -263,11 +285,11 @@ public final AsyncServerBootstrap register(final String uriPattern, final Suppli
/**
* Registers the given {@link AsyncServerExchangeHandler} {@link Supplier} as a handler for URIs
- * matching the given host and the pattern.
+ * matching the given host and pattern.
*
- * @param hostname the host name
- * @param uriPattern the pattern to register the handler for.
- * @param supplier the handler supplier.
+ * @param hostname the non-null host name.
+ * @param uriPattern the non-null pattern to register the handler for.
+ * @param supplier the non-null handler supplier.
* @return this instance.
* @since 5.3
*/
@@ -280,9 +302,14 @@ public final AsyncServerBootstrap register(final String hostname, final String u
}
/**
- * @deprecated use {@link #register(String, String, Supplier)}.
+ * Registers the given {@link AsyncServerExchangeHandler} {@link Supplier} as a handler for URIs
+ * matching the given host and pattern.
*
+ * @param hostname the host name.
+ * @param uriPattern the pattern to register the handler for.
+ * @param supplier the handler supplier.
* @return this instance.
+ * @deprecated use {@link #register(String, String, Supplier)}.
*/
@Deprecated
public final AsyncServerBootstrap registerVirtual(final String hostname, final String uriPattern, final Supplier<AsyncServerExchangeHandler> supplier) {
@@ -307,8 +334,9 @@ public final <T> AsyncServerBootstrap register(
/**
* Registers the given {@link AsyncServerRequestHandler} as a handler for URIs
- * matching the given host and the pattern.
+ * matching the given host and pattern.
*
+ * @param <T> the request type.
* @param hostname the host name
* @param uriPattern the pattern to register the handler for.
* @param requestHandler the handler.
@@ -321,6 +349,7 @@ public final <T> AsyncServerBootstrap register(final String hostname, final Stri
}
/**
+ * @param <T> the request type.
* @return this instance.
* @deprecated Use {@link #register(String, String, AsyncServerRequestHandler)}.
*/
diff --git a/httpcore5/src/main/java/org/apache/hc/core5/http/io/HttpConnectionFactory.java b/httpcore5/src/main/java/org/apache/hc/core5/http/io/HttpConnectionFactory.java
index b6319c8..8ecab21 100644
--- a/httpcore5/src/main/java/org/apache/hc/core5/http/io/HttpConnectionFactory.java
+++ b/httpcore5/src/main/java/org/apache/hc/core5/http/io/HttpConnectionFactory.java
@@ -42,6 +42,13 @@
*/
public interface HttpConnectionFactory<T extends HttpConnection> {
+ /**
+ * Creates TLS connection with a {@link SSLSocket} layered over a plain {@link Socket}.
+ *
+ * @param socket the plain socket SSL socket has been layered over.
+ * @return a new HttpConnection.
+ * @throws IOException in case of an I/O error.
+ */
T createConnection(Socket socket) throws IOException;
/**
@@ -49,6 +56,7 @@ public interface HttpConnectionFactory<T extends HttpConnection> {
*
* @param sslSocket the SSL socket. May be {@code null}.
* @param socket the plain socket SSL socket has been layered over.
+ * @return a new HttpConnection.
* @throws IOException in case of an I/O error.
* @since 5.3
*/
diff --git a/httpcore5/src/main/java/org/apache/hc/core5/http/io/HttpTransportMetrics.java b/httpcore5/src/main/java/org/apache/hc/core5/http/io/HttpTransportMetrics.java
index 947d0d0..a32ff0e 100644
--- a/httpcore5/src/main/java/org/apache/hc/core5/http/io/HttpTransportMetrics.java
+++ b/httpcore5/src/main/java/org/apache/hc/core5/http/io/HttpTransportMetrics.java
@@ -35,7 +35,9 @@
public interface HttpTransportMetrics {
/**
- * Returns the number of bytes transferred.
+ * Gets the number of bytes transferred.
+ *
+ * @return the number of bytes transferred.
*/
long getBytesTransferred();
diff --git a/httpcore5/src/main/java/org/apache/hc/core5/http/io/SessionOutputBuffer.java b/httpcore5/src/main/java/org/apache/hc/core5/http/io/SessionOutputBuffer.java
index 3245bd4..03fdf8a 100644
--- a/httpcore5/src/main/java/org/apache/hc/core5/http/io/SessionOutputBuffer.java
+++ b/httpcore5/src/main/java/org/apache/hc/core5/http/io/SessionOutputBuffer.java
@@ -74,6 +74,7 @@ public interface SessionOutputBuffer {
* @param b the data.
* @param off the start offset in the data.
* @param len the number of bytes to write.
+ * @param outputStream the target OutputStream.
* @throws IOException if an I/O error occurs.
*/
void write(byte[] b, int off, int len, OutputStream outputStream) throws IOException;
@@ -83,6 +84,7 @@ public interface SessionOutputBuffer {
* to this session buffer.
*
* @param b the data.
+ * @param outputStream the target OutputStream.
* @throws IOException if an I/O error occurs.
*/
void write(byte[] b, OutputStream outputStream) throws IOException;
@@ -91,6 +93,7 @@ public interface SessionOutputBuffer {
* Writes the specified byte to this session buffer.
*
* @param b the {@code byte}.
+ * @param outputStream the target OutputStream.
* @throws IOException if an I/O error occurs.
*/
void write(int b, OutputStream outputStream) throws IOException;
@@ -103,6 +106,7 @@ public interface SessionOutputBuffer {
* specific implementations of this interface.
*
* @param buffer the buffer containing chars of the line.
+ * @param outputStream the target OutputStream.
* @throws IOException if an I/O error occurs.
*/
void writeLine(CharArrayBuffer buffer, OutputStream outputStream) throws IOException;
@@ -115,6 +119,7 @@ public interface SessionOutputBuffer {
* stream, such bytes should immediately be written to their
* intended destination.
*
+ * @param outputStream the target OutputStream.
* @throws IOException if an I/O error occurs.
*/
void flush(OutputStream outputStream) throws IOException;
diff --git a/httpcore5/src/main/java/org/apache/hc/core5/http/protocol/HttpProcessor.java b/httpcore5/src/main/java/org/apache/hc/core5/http/protocol/HttpProcessor.java
index b5f84fa..e4f688e 100644
--- a/httpcore5/src/main/java/org/apache/hc/core5/http/protocol/HttpProcessor.java
+++ b/httpcore5/src/main/java/org/apache/hc/core5/http/protocol/HttpProcessor.java
@@ -33,7 +33,7 @@
import org.apache.hc.core5.http.HttpResponseInterceptor;
/**
- * HTTP protocol processor is a collection of protocol interceptors that
+ * Collects protocol interceptors that
* implements the 'Chain of Responsibility' pattern, where each individual
* protocol interceptor is expected to work on a particular aspect of the HTTP
* protocol the interceptor is responsible for.
diff --git a/httpcore5/src/main/java/org/apache/hc/core5/reactor/MultiCoreIOReactor.java b/httpcore5/src/main/java/org/apache/hc/core5/reactor/MultiCoreIOReactor.java
index 7be8764..957a772 100644
--- a/httpcore5/src/main/java/org/apache/hc/core5/reactor/MultiCoreIOReactor.java
+++ b/httpcore5/src/main/java/org/apache/hc/core5/reactor/MultiCoreIOReactor.java
@@ -59,10 +59,12 @@ public IOReactorStatus getStatus() {
/**
* Activates all worker I/O reactors.
+ * <p>
* The I/O main reactor will start reacting to I/O events and triggering
* notification methods. The worker I/O reactor in their turn will start
* reacting to I/O events and dispatch I/O event notifications to the
* {@link IOEventHandler} associated with the given I/O session.
+ * </p>
*/
public final void start() {
if (this.status.compareAndSet(IOReactorStatus.INACTIVE, IOReactorStatus.ACTIVE)) {
diff --git a/httpcore5/src/main/java/org/apache/hc/core5/util/TextUtils.java b/httpcore5/src/main/java/org/apache/hc/core5/util/TextUtils.java
index e6955b4..73864f0 100644
--- a/httpcore5/src/main/java/org/apache/hc/core5/util/TextUtils.java
+++ b/httpcore5/src/main/java/org/apache/hc/core5/util/TextUtils.java
@@ -32,6 +32,8 @@
import org.apache.hc.core5.annotation.Internal;
/**
+ * Tests and converts Strings and CharSequence.
+ *
* @since 4.3
*/
public final class TextUtils {
@@ -41,7 +43,10 @@ private TextUtils() {
}
/**
- * Returns true if the parameter is null or of zero length
+ * Tests whether the parameter is null or of zero length.
+ *
+ * @param s The CharSequence to test.
+ * @return whether the parameter is null or of zero length.
*/
public static boolean isEmpty(final CharSequence s) {
return length(s) == 0;
@@ -91,6 +96,10 @@ public static int length(final CharSequence cs) {
}
/**
+ * Tests whether a CharSequence contains any whitespace.
+ *
+ * @param s The CharSequence to test.
+ * @return whether a CharSequence contains any whitespace.
* @since 4.4
*/
public static boolean containsBlanks(final CharSequence s) {
@@ -120,8 +129,8 @@ public static String toHexString(final byte[] bytes) {
return null;
}
final StringBuilder buffer = new StringBuilder(bytes.length * 2);
- for (int i = 0; i < bytes.length; i++) {
- final int unsignedB = bytes[i] & 0xff;
+ for (final byte element : bytes) {
+ final int unsignedB = element & 0xff;
if (unsignedB < 16) {
buffer.append('0');
}
@@ -131,9 +140,10 @@ public static String toHexString(final byte[] bytes) {
}
/**
- * Returns lower case representation of the given string
- * using {@link Locale#ROOT}.
+ * Converts a String to its lower case representation using {@link Locale#ROOT}.
*
+ * @param s The String to convert
+ * @return The converted String.
* @since 5.2
*/
public static String toLowerCase(final String s) {
@@ -163,9 +173,10 @@ public static boolean isAllASCII(final CharSequence s) {
}
/**
- * Casts character to byte filtering non-visible and non-ASCII characters
- * before conversion
+ * Casts character to byte filtering non-visible and non-ASCII characters before conversion.
*
+ * @param c The character to cast.
+ * @return The given character or {@code '?'}.
* @since 5.2
*/
@Internal
@@ -174,9 +185,8 @@ public static byte castAsByte(final int c) {
(c >= 0xA0 && c <= 0xFF) || // Visible ISO-8859-1
c == 0x09) { // TAB
return (byte) c;
- } else {
- return '?';
}
+ return '?';
}
}
