This is an automated email from the ASF dual-hosted git repository. remm pushed a commit to branch main in repository https://gitbox.apache.org/repos/asf/tomcat.git
The following commit(s) were added to refs/heads/main by this push: new 6bd2cad423 Javadoc cleanup for Coyote 6bd2cad423 is described below commit 6bd2cad4231a7ecd429b86005efe005cf9532d5b Author: remm <r...@apache.org> AuthorDate: Thu May 2 14:46:37 2024 +0200 Javadoc cleanup for Coyote --- java/org/apache/coyote/AbstractProcessor.java | 43 ++++++++++++++++++++++ java/org/apache/coyote/AbstractProcessorLight.java | 9 +++++ java/org/apache/coyote/AbstractProtocol.java | 3 -- java/org/apache/coyote/ActionCode.java | 12 ++++++ java/org/apache/coyote/Adapter.java | 16 +++++++- java/org/apache/coyote/Processor.java | 3 ++ java/org/apache/coyote/ajp/AjpProcessor.java | 6 --- .../apache/coyote/http11/Http11InputBuffer.java | 4 ++ .../apache/coyote/http11/Http11OutputBuffer.java | 9 +---- java/org/apache/coyote/http11/Http11Processor.java | 3 -- .../coyote/http11/filters/ChunkedInputFilter.java | 15 -------- .../coyote/http11/filters/GzipOutputFilter.java | 6 +-- .../coyote/http11/filters/IdentityInputFilter.java | 14 +------ .../http11/filters/SavedRequestInputFilter.java | 11 ++---- .../coyote/http11/filters/VoidInputFilter.java | 22 ----------- .../http11/upgrade/InternalHttpUpgradeHandler.java | 26 +++++++++++++ .../apache/coyote/http2/AbstractNonZeroStream.java | 13 +++++++ java/org/apache/coyote/http2/AbstractStream.java | 38 +++++++++++++++++++ .../tomcat/util/net/ApplicationBufferHandler.java | 11 ++++++ 19 files changed, 182 insertions(+), 82 deletions(-) diff --git a/java/org/apache/coyote/AbstractProcessor.java b/java/org/apache/coyote/AbstractProcessor.java index 31d2cd7fd3..21a7ef2304 100644 --- a/java/org/apache/coyote/AbstractProcessor.java +++ b/java/org/apache/coyote/AbstractProcessor.java @@ -713,27 +713,60 @@ public abstract class AbstractProcessor extends AbstractProcessorLight implement } + /** + * When committing the response, we have to validate the set of headers, as well as setup the response filters. + * @throws IOException IO exception during commit + */ protected abstract void prepareResponse() throws IOException; + /** + * Finish the current response. + * @throws IOException IO exception during the write + */ protected abstract void finishResponse() throws IOException; + /** + * Process acknowledgment of the request. + * @param continueResponseTiming specifies when an acknowledgment should be sent + */ protected abstract void ack(ContinueResponseTiming continueResponseTiming); + /** + * Callback to write data from the buffer. + * @throws IOException IO exception during the write + */ protected abstract void flush() throws IOException; + /** + * Queries if bytes are available in buffers. + * @param doRead {@code true} to perform a read when no bytes are availble + * @return the amount of bytes that are known to be available + */ protected abstract int available(boolean doRead); + /** + * Set the specified byte chunk as the request body that will be read. This allows saving and + * processing requests. + * @param body the byte chunk containing all the request bytes + */ protected abstract void setRequestBody(ByteChunk body); + /** + * The response is finished and no additional bytes need to be sent to the client. + */ protected abstract void setSwallowResponse(); + /** + * Swallowing bytes is required for pipelining requests, so this allows to avoid doing extra operations + * in case an error occurs and the connection is to be closed instead. + */ protected abstract void disableSwallowRequest(); @@ -838,12 +871,22 @@ public abstract class AbstractProcessor extends AbstractProcessorLight implement } + /** + * @return {@code true} if it is known that the request body has been fully read + */ protected abstract boolean isRequestBodyFullyRead(); + /** + * When using non blocking IO, register to get a callback when polling determines that bytes + * are available for reading. + */ protected abstract void registerReadInterest(); + /** + * @return {@code true} if bytes can be written without blocking + */ protected abstract boolean isReadyForWrite(); diff --git a/java/org/apache/coyote/AbstractProcessorLight.java b/java/org/apache/coyote/AbstractProcessorLight.java index 2a429e7b1b..4a371c1f53 100644 --- a/java/org/apache/coyote/AbstractProcessorLight.java +++ b/java/org/apache/coyote/AbstractProcessorLight.java @@ -185,7 +185,16 @@ public abstract class AbstractProcessorLight implements Processor { */ protected abstract SocketState dispatch(SocketEvent status) throws IOException; + /** + * Calls the post process of the async state machine. + * + * @return The state the caller should put the socket in when this method returns + * @throws IOException If an I/O error occurs during the processing of the request + */ protected abstract SocketState asyncPostProcess() throws IOException; + /** + * @return the logger associated with this processor type + */ protected abstract Log getLog(); } diff --git a/java/org/apache/coyote/AbstractProtocol.java b/java/org/apache/coyote/AbstractProtocol.java index 832eafee56..878718938e 100644 --- a/java/org/apache/coyote/AbstractProtocol.java +++ b/java/org/apache/coyote/AbstractProtocol.java @@ -1107,9 +1107,6 @@ public abstract class AbstractProtocol<S> implements ProtocolHandler, MBeanRegis } - /** - * Expected to be used by the Endpoint to release resources on socket close, errors etc. - */ @Override public void release(SocketWrapperBase<S> socketWrapper) { Processor processor = (Processor) socketWrapper.takeCurrentProcessor(); diff --git a/java/org/apache/coyote/ActionCode.java b/java/org/apache/coyote/ActionCode.java index 94c2933353..15531f7c39 100644 --- a/java/org/apache/coyote/ActionCode.java +++ b/java/org/apache/coyote/ActionCode.java @@ -26,8 +26,20 @@ package org.apache.coyote; * @author Remy Maucherat */ public enum ActionCode { + + /** + * Acknowledge request, most often used for HTTP expectations. + */ ACK, + + /** + * Regular close. + */ CLOSE, + + /** + * Response commit, which means any initial bytes part of the response are going to be sent. + */ COMMIT, /** diff --git a/java/org/apache/coyote/Adapter.java b/java/org/apache/coyote/Adapter.java index f85b1f2e8e..93c7657326 100644 --- a/java/org/apache/coyote/Adapter.java +++ b/java/org/apache/coyote/Adapter.java @@ -28,7 +28,7 @@ import org.apache.tomcat.util.net.SocketEvent; public interface Adapter { /** - * Call the service method, and notify all listeners + * Call the service method, and notify all listeners. * * @param req The request object * @param res The response object @@ -59,8 +59,22 @@ public interface Adapter { */ boolean prepare(Request req, Response res) throws Exception; + /** + * Dispatch asynchronous event. + * @param req the request object + * @param res the response object + * @param status the event being processed + * @return {@code true} if the dispatch was successful + * @throws Exception If the processing fails unexpectedly + */ boolean asyncDispatch(Request req, Response res, SocketEvent status) throws Exception; + /** + * Callback to allow logging access outside of the execution of the regular service. + * @param req the request object + * @param res the response object + * @param time time taken to process the request/response in milliseconds (use 0 if not known) + */ void log(Request req, Response res, long time); /** diff --git a/java/org/apache/coyote/Processor.java b/java/org/apache/coyote/Processor.java index ad41bc4880..64192f474d 100644 --- a/java/org/apache/coyote/Processor.java +++ b/java/org/apache/coyote/Processor.java @@ -56,6 +56,9 @@ public interface Processor { */ boolean isUpgrade(); + /** + * @return {@code true} if the Processor state is async, otherwise {@code false} + */ boolean isAsync(); /** diff --git a/java/org/apache/coyote/ajp/AjpProcessor.java b/java/org/apache/coyote/ajp/AjpProcessor.java index e7dc122827..20795b18a3 100644 --- a/java/org/apache/coyote/ajp/AjpProcessor.java +++ b/java/org/apache/coyote/ajp/AjpProcessor.java @@ -1013,9 +1013,6 @@ public class AjpProcessor extends AbstractProcessor { } - /** - * Callback to write data from the buffer. - */ @Override protected final void flush() throws IOException { // Calling code should ensure that there is no data in the buffers for @@ -1031,9 +1028,6 @@ public class AjpProcessor extends AbstractProcessor { } - /** - * Finish AJP response. - */ @Override protected final void finishResponse() throws IOException { if (responseFinished) { diff --git a/java/org/apache/coyote/http11/Http11InputBuffer.java b/java/org/apache/coyote/http11/Http11InputBuffer.java index c047a26701..1a3eb5072c 100644 --- a/java/org/apache/coyote/http11/Http11InputBuffer.java +++ b/java/org/apache/coyote/http11/Http11InputBuffer.java @@ -568,6 +568,8 @@ public class Http11InputBuffer implements InputBuffer, ApplicationBufferHandler, /** * Parse the HTTP headers. + * + * @throws IOException an underlying I/O error occurred */ boolean parseHeaders() throws IOException { if (!parsingHeader) { @@ -645,6 +647,7 @@ public class Http11InputBuffer implements InputBuffer, ApplicationBufferHandler, /** * Available bytes in the buffers for the current request. Note that when requests are pipelined, the data in * byteBuffer may relate to the next request rather than this one. + * @return the amount of bytes available, 0 if none, and 1 if there was an IO error to trigger a read */ int available(boolean read) { int available; @@ -687,6 +690,7 @@ public class Http11InputBuffer implements InputBuffer, ApplicationBufferHandler, /** * Has all of the request body been read? There are subtle differences between this and available() > 0 primarily * because of having to handle faking non-blocking reads with the blocking IO connector. + * @return {@code true} if the request has been fully read */ boolean isFinished() { // The active filters have the definitive information on whether or not diff --git a/java/org/apache/coyote/http11/Http11OutputBuffer.java b/java/org/apache/coyote/http11/Http11OutputBuffer.java index 3916a8843b..627d86e87e 100644 --- a/java/org/apache/coyote/http11/Http11OutputBuffer.java +++ b/java/org/apache/coyote/http11/Http11OutputBuffer.java @@ -207,11 +207,7 @@ public class Http11OutputBuffer implements HttpOutputBuffer { // ----------------------------------------------- HttpOutputBuffer Methods - /** - * Flush the response. - * - * @throws IOException an underlying I/O error occurred - */ + @Override public void flush() throws IOException { if (lastActiveFilter == -1) { @@ -528,9 +524,6 @@ public class Http11OutputBuffer implements HttpOutputBuffer { */ protected class SocketOutputBuffer implements HttpOutputBuffer { - /** - * Write chunk. - */ @Override public int doWrite(ByteBuffer chunk) throws IOException { try { diff --git a/java/org/apache/coyote/http11/Http11Processor.java b/java/org/apache/coyote/http11/Http11Processor.java index b2fac4af8c..dc5d96c870 100644 --- a/java/org/apache/coyote/http11/Http11Processor.java +++ b/java/org/apache/coyote/http11/Http11Processor.java @@ -855,9 +855,6 @@ public class Http11Processor extends AbstractProcessor { } - /** - * When committing the response, we have to validate the set of headers, as well as setup the response filters. - */ @Override protected final void prepareResponse() throws IOException { diff --git a/java/org/apache/coyote/http11/filters/ChunkedInputFilter.java b/java/org/apache/coyote/http11/filters/ChunkedInputFilter.java index f350487771..0f988328ec 100644 --- a/java/org/apache/coyote/http11/filters/ChunkedInputFilter.java +++ b/java/org/apache/coyote/http11/filters/ChunkedInputFilter.java @@ -167,18 +167,12 @@ public class ChunkedInputFilter implements InputFilter, ApplicationBufferHandler // ---------------------------------------------------- InputFilter Methods - /** - * Read the content length from the request. - */ @Override public void setRequest(Request request) { // NO-OP - Request is fixed and passed to constructor. } - /** - * End the current request. - */ @Override public long end() throws IOException { long swallowed = 0; @@ -199,9 +193,6 @@ public class ChunkedInputFilter implements InputFilter, ApplicationBufferHandler } - /** - * Amount of bytes still available in a buffer. - */ @Override public int available() { int available = 0; @@ -217,18 +208,12 @@ public class ChunkedInputFilter implements InputFilter, ApplicationBufferHandler } - /** - * Set the next buffer in the filter pipeline. - */ @Override public void setBuffer(InputBuffer buffer) { this.buffer = buffer; } - /** - * Make the filter ready to process the next request. - */ @Override public void recycle() { remaining = 0; diff --git a/java/org/apache/coyote/http11/filters/GzipOutputFilter.java b/java/org/apache/coyote/http11/filters/GzipOutputFilter.java index 14c68db9a5..16243b0cf2 100644 --- a/java/org/apache/coyote/http11/filters/GzipOutputFilter.java +++ b/java/org/apache/coyote/http11/filters/GzipOutputFilter.java @@ -88,7 +88,8 @@ public class GzipOutputFilter implements OutputFilter { // --------------------------------------------------- OutputFilter Methods /** - * Added to allow flushing to happen for the gzip'ed outputstream + * {@inheritDoc} + * Added to allow flushing to happen for the gzip'ed outputstream. */ @Override public void flush() throws IOException { @@ -131,9 +132,6 @@ public class GzipOutputFilter implements OutputFilter { } - /** - * Make the filter ready to process the next request. - */ @Override public void recycle() { // Set compression stream to null diff --git a/java/org/apache/coyote/http11/filters/IdentityInputFilter.java b/java/org/apache/coyote/http11/filters/IdentityInputFilter.java index f89cee5eec..ef494a5614 100644 --- a/java/org/apache/coyote/http11/filters/IdentityInputFilter.java +++ b/java/org/apache/coyote/http11/filters/IdentityInputFilter.java @@ -126,6 +126,7 @@ public class IdentityInputFilter implements InputFilter, ApplicationBufferHandle /** + * {@inheritDoc} * Read the content length from the request. */ @Override @@ -166,9 +167,6 @@ public class IdentityInputFilter implements InputFilter, ApplicationBufferHandle } - /** - * Amount of bytes still available in a buffer. - */ @Override public int available() { // No data buffered here. Try the next filter in the chain. @@ -176,18 +174,12 @@ public class IdentityInputFilter implements InputFilter, ApplicationBufferHandle } - /** - * Set the next buffer in the filter pipeline. - */ @Override public void setBuffer(InputBuffer buffer) { this.buffer = buffer; } - /** - * Make the filter ready to process the next request. - */ @Override public void recycle() { contentLength = -1; @@ -195,10 +187,6 @@ public class IdentityInputFilter implements InputFilter, ApplicationBufferHandle } - /** - * Return the name of the associated encoding; Here, the value is - * "identity". - */ @Override public ByteChunk getEncodingName() { return ENCODING; diff --git a/java/org/apache/coyote/http11/filters/SavedRequestInputFilter.java b/java/org/apache/coyote/http11/filters/SavedRequestInputFilter.java index d9a8c152e2..fb3b8638eb 100644 --- a/java/org/apache/coyote/http11/filters/SavedRequestInputFilter.java +++ b/java/org/apache/coyote/http11/filters/SavedRequestInputFilter.java @@ -58,6 +58,7 @@ public class SavedRequestInputFilter implements InputFilter { } /** + * {@inheritDoc} * Set the content length on the request. */ @Override @@ -65,16 +66,13 @@ public class SavedRequestInputFilter implements InputFilter { request.setContentLength(input.getLength()); } - /** - * Make the filter ready to process the next request. - */ @Override public void recycle() { input = null; } /** - * Return the name of the associated encoding; here, the value is null. + * @return null */ @Override public ByteChunk getEncodingName() { @@ -83,15 +81,13 @@ public class SavedRequestInputFilter implements InputFilter { /** * Set the next buffer in the filter pipeline (has no effect). + * @param buffer ignored */ @Override public void setBuffer(InputBuffer buffer) { // NOOP since this filter will be providing the request body } - /** - * Amount of bytes still available in a buffer. - */ @Override public int available() { return input.getLength(); @@ -99,6 +95,7 @@ public class SavedRequestInputFilter implements InputFilter { /** * End the current request (has no effect). + * @return 0 */ @Override public long end() throws IOException { diff --git a/java/org/apache/coyote/http11/filters/VoidInputFilter.java b/java/org/apache/coyote/http11/filters/VoidInputFilter.java index 0784d7bd01..5db6fac975 100644 --- a/java/org/apache/coyote/http11/filters/VoidInputFilter.java +++ b/java/org/apache/coyote/http11/filters/VoidInputFilter.java @@ -58,52 +58,30 @@ public class VoidInputFilter implements InputFilter { // ---------------------------------------------------- InputFilter Methods - /** - * Set the associated request. - */ @Override public void setRequest(Request request) { // NOOP: Request isn't used so ignore it } - /** - * Set the next buffer in the filter pipeline. - */ @Override public void setBuffer(InputBuffer buffer) { // NOOP: No body to read } - /** - * Make the filter ready to process the next request. - */ @Override public void recycle() { // NOOP } - /** - * Return the name of the associated encoding; Here, the value is - * "void". - */ @Override public ByteChunk getEncodingName() { return ENCODING; } - /** - * End the current request. It is acceptable to write extra bytes using - * buffer.doWrite during the execution of this method. - * - * @return Should return 0 unless the filter does some content length - * delimitation, in which case the number is the amount of extra bytes or - * missing bytes, which would indicate an error. - * Note: It is recommended that extra bytes be swallowed by the filter. - */ @Override public long end() throws IOException { return 0; diff --git a/java/org/apache/coyote/http11/upgrade/InternalHttpUpgradeHandler.java b/java/org/apache/coyote/http11/upgrade/InternalHttpUpgradeHandler.java index 3151d95c8d..7ed2e14700 100644 --- a/java/org/apache/coyote/http11/upgrade/InternalHttpUpgradeHandler.java +++ b/java/org/apache/coyote/http11/upgrade/InternalHttpUpgradeHandler.java @@ -30,20 +30,46 @@ import org.apache.tomcat.util.net.SocketWrapperBase; */ public interface InternalHttpUpgradeHandler extends HttpUpgradeHandler { + /** + * Process the specified event. + * @param status the event + * @return the status following the event + */ SocketState upgradeDispatch(SocketEvent status); + /** + * Check for a possible timeout. + * @param now the time to use for the timeout check + */ void timeoutAsync(long now); + /** + * Associate with the specified socket. + * @param wrapper the socket + */ void setSocketWrapper(SocketWrapperBase<?> wrapper); + /** + * Associate with the specified SSL support. + * @param sslSupport the SSL support + */ void setSslSupport(SSLSupport sslSupport); + /** + * Pause processing for the connection. + */ void pause(); + /** + * @return {@code true} if able to process asynchronous IO, default is {@code false} + */ default boolean hasAsyncIO() { return false; } + /** + * @return the associated upgrade information used to collect statistics for the connection + */ default UpgradeInfo getUpgradeInfo() { return null; } diff --git a/java/org/apache/coyote/http2/AbstractNonZeroStream.java b/java/org/apache/coyote/http2/AbstractNonZeroStream.java index aae614f42c..333e33e5e3 100644 --- a/java/org/apache/coyote/http2/AbstractNonZeroStream.java +++ b/java/org/apache/coyote/http2/AbstractNonZeroStream.java @@ -41,11 +41,19 @@ abstract class AbstractNonZeroStream extends AbstractStream { } + /** + * @return {@code true} if the state indicates a close + */ final boolean isClosedFinal() { return state.isClosedFinal(); } + /** + * Check the frame type against the state + * @param frameType the type + * @throws Http2Exception if an error is detected + */ final void checkState(FrameType frameType) throws Http2Exception { state.checkFrameType(frameType); } @@ -59,5 +67,10 @@ abstract class AbstractNonZeroStream extends AbstractStream { */ abstract ByteBuffer getInputByteBuffer(); + /** + * Notify that some data has been received. + * @param payloadSize the byte count + * @throws Http2Exception if an error is detected + */ abstract void receivedData(int payloadSize) throws Http2Exception; } diff --git a/java/org/apache/coyote/http2/AbstractStream.java b/java/org/apache/coyote/http2/AbstractStream.java index 367e764232..35aa402730 100644 --- a/java/org/apache/coyote/http2/AbstractStream.java +++ b/java/org/apache/coyote/http2/AbstractStream.java @@ -50,21 +50,34 @@ abstract class AbstractStream { } + /** + * @return the stream identifier + */ final Integer getIdentifier() { return identifier; } + /** + * @return the stream identifier as a String + */ final String getIdAsString() { return idAsString; } + /** + * @return the stream identifier + */ final int getIdAsInt() { return identifier.intValue(); } + /** + * Set the window size for this stream. + * @param windowSize the value + */ final void setWindowSize(long windowSize) { windowAllocationLock.lock(); try { @@ -75,6 +88,9 @@ abstract class AbstractStream { } + /** + * @return the window size + */ final long getWindowSize() { windowAllocationLock.lock(); try { @@ -120,6 +136,11 @@ abstract class AbstractStream { } + /** + * Decrement window size. + * + * @param decrement The amount by which the window size should be decreased + */ final void decrementWindowSize(int decrement) { windowAllocationLock.lock(); try { @@ -137,11 +158,18 @@ abstract class AbstractStream { } + /** + * @return the requested amount of resources requested + */ final int getConnectionAllocationRequested() { return connectionAllocationRequested; } + /** + * Set the amount of requested resources. + * @param connectionAllocationRequested the value + */ final void setConnectionAllocationRequested(int connectionAllocationRequested) { log.trace(sm.getString("abstractStream.setConnectionAllocationRequested", getConnectionId(), getIdAsString(), Integer.toString(this.connectionAllocationRequested), Integer.toString(connectionAllocationRequested))); @@ -149,11 +177,18 @@ abstract class AbstractStream { } + /** + * @return the allocation that was made at the connection level + */ final int getConnectionAllocationMade() { return connectionAllocationMade; } + /** + * Set the allocation made at the connection level. + * @param connectionAllocationMade the value + */ final void setConnectionAllocationMade(int connectionAllocationMade) { log.trace(sm.getString("abstractStream.setConnectionAllocationMade", getConnectionId(), getIdAsString(), Integer.toString(this.connectionAllocationMade), Integer.toString(connectionAllocationMade))); @@ -161,5 +196,8 @@ abstract class AbstractStream { } + /** + * @return the connection id + */ abstract String getConnectionId(); } diff --git a/java/org/apache/tomcat/util/net/ApplicationBufferHandler.java b/java/org/apache/tomcat/util/net/ApplicationBufferHandler.java index d0a41b466c..0e8873c796 100644 --- a/java/org/apache/tomcat/util/net/ApplicationBufferHandler.java +++ b/java/org/apache/tomcat/util/net/ApplicationBufferHandler.java @@ -39,10 +39,21 @@ public interface ApplicationBufferHandler { } }; + /** + * Set the byte buffer. + * @param buffer the byte buffer + */ void setByteBuffer(ByteBuffer buffer); + /** + * @return the byte buffer + */ ByteBuffer getByteBuffer(); + /** + * Expand the byte buffer to at least the given size. Some implementations may not implement this. + * @param size the desired size + */ void expand(int size); } --------------------------------------------------------------------- To unsubscribe, e-mail: dev-unsubscr...@tomcat.apache.org For additional commands, e-mail: dev-h...@tomcat.apache.org