You are viewing a plain text version of this content. The canonical link for it is here.
Posted to dev@tomcat.apache.org by ma...@apache.org on 2019/09/18 13:34:05 UTC
[tomcat] 02/02: Fix some Javadoc warning when building with later
versions of Java
This is an automated email from the ASF dual-hosted git repository.
markt pushed a commit to branch 7.0.x
in repository https://gitbox.apache.org/repos/asf/tomcat.git
commit f67a783210e58d48aa192ff3d5dd7e2c02307c98
Author: Mark Thomas <ma...@apache.org>
AuthorDate: Wed Sep 18 14:33:29 2019 +0100
Fix some Javadoc warning when building with later versions of Java
---
java/org/apache/coyote/AbstractProcessor.java | 3 ++-
java/org/apache/coyote/AbstractProtocol.java | 16 ++++++++++++++--
java/org/apache/coyote/OutputBuffer.java | 3 +++
java/org/apache/coyote/Processor.java | 7 +++++++
java/org/apache/coyote/ProtocolHandler.java | 3 +++
java/org/apache/coyote/ajp/AbstractAjpProcessor.java | 8 ++++++++
java/org/apache/coyote/ajp/AjpAprProcessor.java | 19 +++++++++++++++++++
java/org/apache/coyote/ajp/AjpMessage.java | 6 +++++-
8 files changed, 61 insertions(+), 4 deletions(-)
diff --git a/java/org/apache/coyote/AbstractProcessor.java b/java/org/apache/coyote/AbstractProcessor.java
index 80ed7c3..e74c385 100644
--- a/java/org/apache/coyote/AbstractProcessor.java
+++ b/java/org/apache/coyote/AbstractProcessor.java
@@ -122,7 +122,8 @@ public abstract class AbstractProcessor<S> implements ActionHook, Processor<S> {
}
/**
- * The endpoint receiving connections that are handled by this processor.
+ * @return The endpoint receiving connections that are handled by this
+ * processor.
*/
protected AbstractEndpoint<S> getEndpoint() {
return endpoint;
diff --git a/java/org/apache/coyote/AbstractProtocol.java b/java/org/apache/coyote/AbstractProtocol.java
index bbbf090..bf5308f 100644
--- a/java/org/apache/coyote/AbstractProtocol.java
+++ b/java/org/apache/coyote/AbstractProtocol.java
@@ -296,8 +296,10 @@ public abstract class AbstractProtocol<S> implements ProtocolHandler,
/**
* The name will be prefix-address-port if address is non-null and
- * prefix-port if the address is null. The name will be appropriately quoted
- * so it can be used directly in an ObjectName.
+ * prefix-port if the address is null.
+ *
+ * @return A name for this protocol instance that is appropriately quoted
+ * for use in an ObjectName.
*/
public String getName() {
StringBuilder name = new StringBuilder(getNamePrefix());
@@ -350,6 +352,7 @@ public abstract class AbstractProtocol<S> implements ProtocolHandler,
/**
* Obtain the handler associated with the underlying Endpoint
+ * @return the handler
*/
protected abstract Handler getHandler();
@@ -788,7 +791,16 @@ public abstract class AbstractProtocol<S> implements ProtocolHandler,
protected abstract void release(SocketWrapper<S> socket,
Processor<S> processor, boolean socketClosing,
boolean addToPoller);
+
/**
+ * Create an instance of an HTTP upgrade processor.
+ *
+ * @param socket The socket associated with the connection to upgrade
+ * @param inbound Listener to which data available events should be
+ * passed
+ * @return A Processor instance for the upgraded connection
+ * @throws IOException if an I/O error occurred during the creation of
+ * the Processor
* @deprecated Will be removed in Tomcat 8.0.x.
*/
@Deprecated
diff --git a/java/org/apache/coyote/OutputBuffer.java b/java/org/apache/coyote/OutputBuffer.java
index 93d18ce..4f5ebba 100644
--- a/java/org/apache/coyote/OutputBuffer.java
+++ b/java/org/apache/coyote/OutputBuffer.java
@@ -35,6 +35,9 @@ public interface OutputBuffer {
* Write the given data to the response. The caller owns the chunks.
*
* @param chunk data to write
+ * @param response The response to which the data should be written.
+ * (Should be the response already associated with the
+ * OutputBuffer).
*
* @return The number of bytes written which may be less than available in
* the input chunk
diff --git a/java/org/apache/coyote/Processor.java b/java/org/apache/coyote/Processor.java
index 62638e4..476be1c 100644
--- a/java/org/apache/coyote/Processor.java
+++ b/java/org/apache/coyote/Processor.java
@@ -40,11 +40,18 @@ public interface Processor<S> {
SocketState asyncPostProcess();
/**
+ * @return Listener to which data available events are passed once the
+ * associated connection has completed the proprietary Tomcat HTTP
+ * upgrade process.
+ *
* @deprecated Will be removed in Tomcat 8.0.x.
*/
@Deprecated
org.apache.coyote.http11.upgrade.UpgradeInbound getUpgradeInbound();
/**
+ * @return The socket state once the upgrade dispatch event has been
+ * processed.
+ * @throws IOException An IO error occurred
* @deprecated Will be removed in Tomcat 8.0.x.
*/
@Deprecated
diff --git a/java/org/apache/coyote/ProtocolHandler.java b/java/org/apache/coyote/ProtocolHandler.java
index 5c7cdf7..57997a1 100644
--- a/java/org/apache/coyote/ProtocolHandler.java
+++ b/java/org/apache/coyote/ProtocolHandler.java
@@ -105,6 +105,9 @@ public interface ProtocolHandler {
/**
* Requires APR/native library
+ *
+ * @return <code>true</code> if this Protocol Handler requires the
+ * APR/native library, otherwise <code>false</code>
*/
public boolean isAprRequired();
}
diff --git a/java/org/apache/coyote/ajp/AbstractAjpProcessor.java b/java/org/apache/coyote/ajp/AbstractAjpProcessor.java
index 9953c12..ba42828 100644
--- a/java/org/apache/coyote/ajp/AbstractAjpProcessor.java
+++ b/java/org/apache/coyote/ajp/AbstractAjpProcessor.java
@@ -710,6 +710,7 @@ public abstract class AbstractAjpProcessor<S> extends AbstractProcessor<S> {
* internal buffer.
*
* @return true if there is more data, false if not.
+ * @throws IOException An IO error occurred
*/
protected boolean refillReadBuffer() throws IOException {
// If the server returns an empty packet, assume that that end of
@@ -1015,6 +1016,7 @@ public abstract class AbstractAjpProcessor<S> extends AbstractProcessor<S> {
/**
* When committing the response, we have to validate the set of headers, as
* well as setup the response filters.
+ * @throws IOException An IO error occurred
*/
protected void prepareResponse() throws IOException {
@@ -1098,6 +1100,11 @@ public abstract class AbstractAjpProcessor<S> extends AbstractProcessor<S> {
/**
* Callback to write data from the buffer.
+ *
+ * @param explicit If {@code true} a flush message is sent, otherwise this
+ * method is a NO-OP
+ *
+ * @throws IOException An IO error occurred
*/
protected void flush(boolean explicit) throws IOException {
if (ajpFlush && explicit && !finished) {
@@ -1109,6 +1116,7 @@ public abstract class AbstractAjpProcessor<S> extends AbstractProcessor<S> {
/**
* Finish AJP response.
+ * @throws IOException An IO error occurred
*/
protected void finish() throws IOException {
diff --git a/java/org/apache/coyote/ajp/AjpAprProcessor.java b/java/org/apache/coyote/ajp/AjpAprProcessor.java
index e269cb6..96e0321 100644
--- a/java/org/apache/coyote/ajp/AjpAprProcessor.java
+++ b/java/org/apache/coyote/ajp/AjpAprProcessor.java
@@ -304,6 +304,11 @@ public class AjpAprProcessor extends AbstractAjpProcessor<Long> {
/**
* Read at least the specified amount of bytes, and place them
* in the input buffer.
+ *
+ * @param n The minimum number of bytes to read before the method returns
+ *
+ * @return Always {@code true}
+ * @throws IOException If an I/O error occurs during the read
*/
protected boolean read(int n)
throws IOException {
@@ -334,6 +339,15 @@ public class AjpAprProcessor extends AbstractAjpProcessor<Long> {
/**
* Read at least the specified amount of bytes, and place them
* in the input buffer.
+ *
+ * @param n The minimum number of bytes to read
+ * @param useAvailableData If {@code true}, only proceed with the read if
+ * there is at least one byte of data available to
+ * read in the input buffer
+ *
+ * @return {@code true} if the number of bytes requested was read,
+ * {@code false} if no bytes were read
+ * @throws IOException if an I/O error occurs during the read
*/
protected boolean readt(int n, boolean useAvailableData)
throws IOException {
@@ -401,8 +415,13 @@ public class AjpAprProcessor extends AbstractAjpProcessor<Long> {
/**
* Read an AJP message.
*
+ * @param message The message object to be populated
* @param first is true if the message is the first in the request, which
* will cause a short duration blocking read
+ * @param useAvailableData If {@code true} and if {@code first} is
+ * {@code true}, only proceed with the read if there
+ * is at least one byte of data available to read in
+ * the input buffer
* @return true if the message has been read, false if the short read
* didn't return anything
* @throws IOException any other failure, including incomplete reads
diff --git a/java/org/apache/coyote/ajp/AjpMessage.java b/java/org/apache/coyote/ajp/AjpMessage.java
index 03ef613..8ac70b1 100644
--- a/java/org/apache/coyote/ajp/AjpMessage.java
+++ b/java/org/apache/coyote/ajp/AjpMessage.java
@@ -238,6 +238,8 @@ public class AjpMessage {
* encoded length). The terminator is for the convenience of the C
* code, where it saves a round of copying. A null string is
* encoded as a string with length 0.
+ *
+ * @param str The String to append
*/
public void appendString(String str) {
if (str == null) {
@@ -406,7 +408,9 @@ public class AjpMessage {
/**
- * Dump the contents of the message, prefixed with the given String.
+ * Dump the contents of the message.
+ *
+ * @param msg The message to write
*/
public void dump(String msg) {
if (log.isDebugEnabled()) {
---------------------------------------------------------------------
To unsubscribe, e-mail: dev-unsubscribe@tomcat.apache.org
For additional commands, e-mail: dev-help@tomcat.apache.org