From 3a189ab2547b980693de2fb9f186ebca22a29972 Mon Sep 17 00:00:00 2001 From: olivier lamy Date: Mon, 18 Dec 2017 14:27:55 +1100 Subject: [PATCH] #2056 javadoc warning fixes WIP Signed-off-by: olivier lamy --- .../jetty/http/GZIPContentDecoder.java | 3 ++- .../java/org/eclipse/jetty/http/MetaData.java | 1 + .../eclipse/jetty/server/ConnectionLimit.java | 4 ++-- .../server/ForwardedRequestCustomizer.java | 8 +++---- .../jetty/server/HttpChannelState.java | 3 ++- .../org/eclipse/jetty/server/HttpInput.java | 21 ++++++++++++------- .../eclipse/jetty/server/ServerConnector.java | 10 +++++++-- .../jetty/util/MultiReleaseJarFile.java | 1 + .../org/eclipse/jetty/util/thread/Locker.java | 1 + .../util/thread/ReservedThreadExecutor.java | 5 +++-- 10 files changed, 37 insertions(+), 20 deletions(-) diff --git a/jetty-http/src/main/java/org/eclipse/jetty/http/GZIPContentDecoder.java b/jetty-http/src/main/java/org/eclipse/jetty/http/GZIPContentDecoder.java index 24955bc6c5f..8ffaa5d81e6 100644 --- a/jetty-http/src/main/java/org/eclipse/jetty/http/GZIPContentDecoder.java +++ b/jetty-http/src/main/java/org/eclipse/jetty/http/GZIPContentDecoder.java @@ -400,7 +400,8 @@ public class GZIPContentDecoder implements Destroyable } /** - * @return An indirect buffer of the configured buffersize either from the pool or freshly allocated. + * @param capacity capacity capacity of the allocated ByteBuffer + * @return An indirect buffer of the configured buffersize either from the pool or freshly allocated. */ public ByteBuffer acquire(int capacity) { diff --git a/jetty-http/src/main/java/org/eclipse/jetty/http/MetaData.java b/jetty-http/src/main/java/org/eclipse/jetty/http/MetaData.java index 7fb2d4dde96..c40b015fadc 100644 --- a/jetty-http/src/main/java/org/eclipse/jetty/http/MetaData.java +++ b/jetty-http/src/main/java/org/eclipse/jetty/http/MetaData.java @@ -61,6 +61,7 @@ public class MetaData implements Iterable /** * @deprecated use {@link #getHttpVersion()} instead + * @return the HTTP version of this MetaData object */ @Deprecated public HttpVersion getVersion() diff --git a/jetty-server/src/main/java/org/eclipse/jetty/server/ConnectionLimit.java b/jetty-server/src/main/java/org/eclipse/jetty/server/ConnectionLimit.java index 2e4cd3ab4f7..fb3fc71ea15 100644 --- a/jetty-server/src/main/java/org/eclipse/jetty/server/ConnectionLimit.java +++ b/jetty-server/src/main/java/org/eclipse/jetty/server/ConnectionLimit.java @@ -30,12 +30,12 @@ import org.eclipse.jetty.util.log.Log; import org.eclipse.jetty.util.log.Logger; /** - * A Connection Listener that limits the number of Connections. + *

A Connection Listener that limits the number of Connections.

*

This listener applies a limit to the number of connections, which when * exceeded results in a call to {@link AbstractConnector#setAccepting(boolean)} * to prevent further connections being received. It can be applied to an * entire server or to a specific connector. - *

+ *

* @see Connection.Listener */ @ManagedObject diff --git a/jetty-server/src/main/java/org/eclipse/jetty/server/ForwardedRequestCustomizer.java b/jetty-server/src/main/java/org/eclipse/jetty/server/ForwardedRequestCustomizer.java index 650b585621d..2640732bd7a 100644 --- a/jetty-server/src/main/java/org/eclipse/jetty/server/ForwardedRequestCustomizer.java +++ b/jetty-server/src/main/java/org/eclipse/jetty/server/ForwardedRequestCustomizer.java @@ -86,10 +86,10 @@ public class ForwardedRequestCustomizer implements Customizer } /** - * Configure to only support the RFC7239 Forwarded header and to - * not support any {@code X-Forwarded-} headers. This convenience method - * clears all the non RFC headers if passed true and sets them to - * the default values (if not already set) if passed false. + * @param rfc7239only Configure to only support the RFC7239 Forwarded header and to + * not support any {@code X-Forwarded-} headers. This convenience method + * clears all the non RFC headers if passed true and sets them to + * the default values (if not already set) if passed false. */ public void setForwardedOnly(boolean rfc7239only) { diff --git a/jetty-server/src/main/java/org/eclipse/jetty/server/HttpChannelState.java b/jetty-server/src/main/java/org/eclipse/jetty/server/HttpChannelState.java index 3abddd890d0..81d3db14d5b 100644 --- a/jetty-server/src/main/java/org/eclipse/jetty/server/HttpChannelState.java +++ b/jetty-server/src/main/java/org/eclipse/jetty/server/HttpChannelState.java @@ -1249,6 +1249,7 @@ public class HttpChannelState * Called to indicate that more content may be available, * but that a handling thread may need to produce (fill/parse) * it. Typically called by the async read success callback. + * @return true if more content may be available */ public boolean onReadPossible() { @@ -1279,7 +1280,7 @@ public class HttpChannelState /** * Called to signal that a read has read -1. * Will wake if the read was called while in ASYNC_WAIT state - * @return true if woken + * @return true if woken */ public boolean onReadEof() { diff --git a/jetty-server/src/main/java/org/eclipse/jetty/server/HttpInput.java b/jetty-server/src/main/java/org/eclipse/jetty/server/HttpInput.java index 47f9655430d..4a8a88eeb5e 100644 --- a/jetty-server/src/main/java/org/eclipse/jetty/server/HttpInput.java +++ b/jetty-server/src/main/java/org/eclipse/jetty/server/HttpInput.java @@ -44,23 +44,27 @@ import org.eclipse.jetty.util.log.Logger; /** * {@link HttpInput} provides an implementation of {@link ServletInputStream} for {@link HttpChannel}. *

- * Content may arrive in patterns such as [content(), content(), messageComplete()] so that this class maintains two states: the content state that tells - * whether there is content to consume and the EOF state that tells whether an EOF has arrived. Only once the content has been consumed the content state is - * moved to the EOF state. + * Content may arrive in patterns such as [content(), content(), messageComplete()] + * so that this class maintains two states: the content state that tells + * whether there is content to consume and the EOF state that tells whether an EOF has arrived. + * Only once the content has been consumed the content state is moved to the EOF state. + *

*/ public class HttpInput extends ServletInputStream implements Runnable { /** * An interceptor for HTTP Request input. *

- * Unlike inputstream wrappers that can be applied by filters, an interceptor + * Unlike InputStream wrappers that can be applied by filters, an interceptor * is entirely transparent and works with async IO APIs. + *

*

* An Interceptor may consume data from the passed content and the interceptor * will continue to be called for the same content until the interceptor returns - * null or an empty content. Thus even if the passed content is completely consumed + * null or an empty content. Thus even if the passed content is completely consumed * the interceptor will be called with the same content until it can no longer - * produce more content. + * produce more content. + *

* @see HttpInput#setInterceptor(Interceptor) * @see HttpInput#addInterceptor(Interceptor) */ @@ -77,8 +81,8 @@ public class HttpInput extends ServletInputStream implements Runnable /** * An {@link Interceptor} that chains two other {@link Interceptor}s together. - * The {@link #readFrom(Content)} calls the previous {@link Interceptor}'s - * {@link #readFrom(Content)} and then passes any {@link Content} returned + * The {@link Interceptor#readFrom(Content)} calls the previous {@link Interceptor}'s + * {@link Interceptor#readFrom(Content)} and then passes any {@link Content} returned * to the next {@link Interceptor}. */ public static class ChainedInterceptor implements Interceptor, Destroyable @@ -335,6 +339,7 @@ public class HttpInput extends ServletInputStream implements Runnable /** * Called by channel when asynchronous IO needs to produce more content * @throws IOException + * if unable to produce content */ public void asyncReadProduce() throws IOException { diff --git a/jetty-server/src/main/java/org/eclipse/jetty/server/ServerConnector.java b/jetty-server/src/main/java/org/eclipse/jetty/server/ServerConnector.java index 72b1c26175e..2e441a6eb62 100644 --- a/jetty-server/src/main/java/org/eclipse/jetty/server/ServerConnector.java +++ b/jetty-server/src/main/java/org/eclipse/jetty/server/ServerConnector.java @@ -57,14 +57,18 @@ import org.eclipse.jetty.util.thread.Scheduler; * use all the commons services (eg {@link Executor}, {@link Scheduler}) of the * passed {@link Server} instance, but all services may also be constructor injected * into the connector so that it may operate with dedicated or otherwise shared services. + *

*

Connection Factories

+ *

* Various convenience constructors are provided to assist with common configurations of * ConnectionFactories, whose generic use is described in {@link AbstractConnector}. * If no connection factories are passed, then the connector will * default to use a {@link HttpConnectionFactory}. If an non null {@link SslContextFactory} * instance is passed, then this used to instantiate a {@link SslConnectionFactory} which is * prepended to the other passed or default factories. + *

*

Selectors

+ *

* The connector will use the {@link Executor} service to execute a number of Selector Tasks, * which are implemented to each use a NIO {@link Selector} instance to asynchronously * schedule a set of accepted connections. It is the selector thread that will call the @@ -72,10 +76,12 @@ import org.eclipse.jetty.util.thread.Scheduler; * {@link EndPoint#write(Callback, java.nio.ByteBuffer...)} methods. It is expected * that these callbacks may do some non-blocking IO work, but will always dispatch to the * {@link Executor} service any blocking, long running or application tasks. + *

*

* The default number of selectors is equal to half of the number of processors available to the JVM, * which should allow optimal performance even if all the connections used are performing * significant non-blocking work in the callback tasks. + *

*/ @ManagedObject("HTTP connector using NIO ByteChannels and Selectors") public class ServerConnector extends AbstractNetworkConnector @@ -281,7 +287,7 @@ public class ServerConnector extends AbstractNetworkConnector * This open method can be called before starting the connector to pass it a ServerSocketChannel * that will be used instead of one returned from {@link #openAcceptChannel()} * @param acceptChannel the channel to use - * @throws IOException + * @throws IOException if the server channel cannot be bound */ public void open(ServerSocketChannel acceptChannel) throws IOException { @@ -311,7 +317,7 @@ public class ServerConnector extends AbstractNetworkConnector /** * Called by {@link #open()} to obtain the accepting channel. * @return ServerSocketChannel used to accept connections. - * @throws IOException + * @throws IOException if unable to obtain or configure the server channel */ protected ServerSocketChannel openAcceptChannel() throws IOException { diff --git a/jetty-util/src/main/java/org/eclipse/jetty/util/MultiReleaseJarFile.java b/jetty-util/src/main/java/org/eclipse/jetty/util/MultiReleaseJarFile.java index 3a9c0759e50..a6226f423d0 100644 --- a/jetty-util/src/main/java/org/eclipse/jetty/util/MultiReleaseJarFile.java +++ b/jetty-util/src/main/java/org/eclipse/jetty/util/MultiReleaseJarFile.java @@ -49,6 +49,7 @@ public class MultiReleaseJarFile implements Closeable /** * Construct a multi release jar file for the current JVM version, ignoring directories. * @param file The file to open + * @throws IOException if the jar file cannot be read */ public MultiReleaseJarFile(File file) throws IOException { diff --git a/jetty-util/src/main/java/org/eclipse/jetty/util/thread/Locker.java b/jetty-util/src/main/java/org/eclipse/jetty/util/thread/Locker.java index ccbbd175876..0de518af955 100644 --- a/jetty-util/src/main/java/org/eclipse/jetty/util/thread/Locker.java +++ b/jetty-util/src/main/java/org/eclipse/jetty/util/thread/Locker.java @@ -49,6 +49,7 @@ public class Locker /** * @deprecated use {@link #lock()} instead + * @return the lock to unlock */ @Deprecated public Lock lockIfNotHeld() diff --git a/jetty-util/src/main/java/org/eclipse/jetty/util/thread/ReservedThreadExecutor.java b/jetty-util/src/main/java/org/eclipse/jetty/util/thread/ReservedThreadExecutor.java index 5303ab5785f..7b6c1b0c39e 100644 --- a/jetty-util/src/main/java/org/eclipse/jetty/util/thread/ReservedThreadExecutor.java +++ b/jetty-util/src/main/java/org/eclipse/jetty/util/thread/ReservedThreadExecutor.java @@ -89,8 +89,9 @@ public class ReservedThreadExecutor extends AbstractLifeCycle implements Executo /** * @param executor The executor to use to obtain threads * @param capacity The number of threads to preallocate. If less than 0 then capacity - * is calculated based on a heuristic from the number of available processors and - * thread pool size. + * is calculated based on a heuristic from the number of available processors and + * thread pool size. + * @param owner the owner of the instance. Only used for debugging purpose withing the {@link #toString()} method */ public ReservedThreadExecutor(Executor executor,int capacity, Object owner) {