From 401642887b2dd2da9e9e4c67936cd92d34b5327e Mon Sep 17 00:00:00 2001 From: Gary Gregory Date: Fri, 30 Aug 2024 20:27:41 +0200 Subject: [PATCH] Javadoc improvements - Javadoc: Add missing comments - Javadoc: Add missing tags - Javadoc: Sentences end in a period - Javadoc: Reduce whitespace --- .../core5/http2/ssl/ApplicationProtocol.java | 13 ++++- .../apache/hc/core5/annotation/Contract.java | 10 +++- .../hc/core5/concurrent/BasicFuture.java | 5 ++ .../concurrent/CallbackContribution.java | 7 ++- .../apache/hc/core5/http/config/Lookup.java | 6 +++ .../hc/core5/http/config/RegistryBuilder.java | 18 +++++++ .../impl/bootstrap/AsyncServerBootstrap.java | 53 ++++++++++++++----- .../core5/http/io/HttpConnectionFactory.java | 8 +++ .../core5/http/io/HttpTransportMetrics.java | 4 +- .../hc/core5/http/io/SessionOutputBuffer.java | 5 ++ .../hc/core5/http/protocol/HttpProcessor.java | 2 +- .../hc/core5/reactor/MultiCoreIOReactor.java | 2 + .../org/apache/hc/core5/util/TextUtils.java | 28 ++++++---- 13 files changed, 135 insertions(+), 26 deletions(-) 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 c4f55ab7bb..d55cf6128e 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 8a87a25852..20177c4e55 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. + *

+ * The default value is {@link ThreadingBehavior#UNSAFE}. + *

+ * + * @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 3cfe544173..6304b2f6e3 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 implements Future, 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 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 4dc602f838..90e3f1a1ea 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 the future result type of an asynchronous operation. @@ -37,6 +37,11 @@ public abstract class CallbackContribution implements FutureCallback { 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 3fcc66082c..28fc9c0427 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 { + /** + * 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 af31c76821..ee65c44911 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 { private final Map items; + /** + * Creates a new RegistryBuilder. + * + * @param the type of Registry values. + * @return a new RegistryBuilder. + */ public static RegistryBuilder create() { return new RegistryBuilder<>(); } @@ -52,6 +58,13 @@ public static RegistryBuilder 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 register(final String id, final I item) { Args.notEmpty(id, "ID"); Args.notNull(item, "Item"); @@ -59,6 +72,11 @@ public RegistryBuilder 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 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 185a17d4d4..a47d041112 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 ioSessionDecorator) { @@ -196,6 +211,7 @@ public final AsyncServerBootstrap setIOSessionDecorator(final Decorator exceptionCallback) { @@ -206,6 +222,7 @@ public final AsyncServerBootstrap setExceptionCallback(final Callback /** * 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> lookupRegistry) { + public final AsyncServerBootstrap setLookupRegistry(final LookupRegistry> 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 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 supplier) { @@ -307,8 +334,9 @@ public final 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 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 AsyncServerBootstrap register(final String hostname, final Stri } /** + * @param 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 b6319c8716..8ecab21157 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 { + /** + * 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 { * * @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 947d0d034a..a32ff0e994 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 3245bd446c..03fdf8aae2 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 b5f84fa66f..e4f688eb7f 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 7be876463f..957a772eb4 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. + *

* 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. + *

*/ 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 e6955b4b68..73864f0a05 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 '?'; } }