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 a354f2d6dcf6c8ba5ecedbeb6b42a5d6dd5d986c Author: Mark Thomas <ma...@apache.org> AuthorDate: Fri Nov 8 22:13:59 2019 +0000 Fix some Javadoc warnings with Java 13 Generally, fix by aligning with 8.5.x/9.0.x. Also include some additional minor clean-up --- java/org/apache/catalina/ha/backend/Sender.java | 10 ++- java/org/apache/catalina/ha/backend/TcpSender.java | 1 + .../apache/catalina/tribes/ChannelReceiver.java | 3 +- .../catalina/tribes/transport/ReceiverBase.java | 25 +++---- .../tribes/transport/bio/BioReplicationTask.java | 9 ++- .../catalina/tribes/transport/bio/BioSender.java | 26 +++---- java/org/apache/tomcat/util/buf/ByteChunk.java | 23 ++++-- java/org/apache/tomcat/util/buf/MessageBytes.java | 84 ++++++++++++++-------- 8 files changed, 106 insertions(+), 75 deletions(-) diff --git a/java/org/apache/catalina/ha/backend/Sender.java b/java/org/apache/catalina/ha/backend/Sender.java index 191a19c..8857445 100644 --- a/java/org/apache/catalina/ha/backend/Sender.java +++ b/java/org/apache/catalina/ha/backend/Sender.java @@ -18,19 +18,23 @@ package org.apache.catalina.ha.backend; -/* - * Interface to send data to proxies - * +/** + * Interface to send data to proxies. */ public interface Sender { /** * Set the configuration parameters + * @param config The heartbeat listener configuration + * @throws Exception An error occurred */ public void init(HeartbeatListener config) throws Exception; /** * Send the message to the proxies + * @param mess The message that will be sent + * @return <code>0</code> if no error occurred, <code>-1</code> otherwise + * @throws Exception An error occurred */ public int send(String mess) throws Exception; } diff --git a/java/org/apache/catalina/ha/backend/TcpSender.java b/java/org/apache/catalina/ha/backend/TcpSender.java index 6c78e10..7dd9338 100644 --- a/java/org/apache/catalina/ha/backend/TcpSender.java +++ b/java/org/apache/catalina/ha/backend/TcpSender.java @@ -180,6 +180,7 @@ public class TcpSender /** * Close connection. + * @param i The index of the connection that will be closed */ protected void close(int i) { try { diff --git a/java/org/apache/catalina/tribes/ChannelReceiver.java b/java/org/apache/catalina/tribes/ChannelReceiver.java index e90c3e2..b1dae2e 100644 --- a/java/org/apache/catalina/tribes/ChannelReceiver.java +++ b/java/org/apache/catalina/tribes/ChannelReceiver.java @@ -23,14 +23,13 @@ package org.apache.catalina.tribes; * The <code>ChannelReceiver</code> interface is the data receiver component * at the bottom layer, the IO layer (for layers see the javadoc for the {@link Channel} interface). * This class may optionally implement a thread pool for parallel processing of incoming messages. - * @author Filip Hanik */ public interface ChannelReceiver extends Heartbeat { public static final int MAX_UDP_SIZE = 65535; /** * Start listening for incoming messages on the host/port - * @throws java.io.IOException + * @throws java.io.IOException Listen failed */ public void start() throws java.io.IOException; diff --git a/java/org/apache/catalina/tribes/transport/ReceiverBase.java b/java/org/apache/catalina/tribes/transport/ReceiverBase.java index 380807c..43d99d5 100644 --- a/java/org/apache/catalina/tribes/transport/ReceiverBase.java +++ b/java/org/apache/catalina/tribes/transport/ReceiverBase.java @@ -36,16 +36,6 @@ import org.apache.catalina.tribes.util.ExecutorFactory; import org.apache.juli.logging.Log; import org.apache.juli.logging.LogFactory; -/** - * <p>Title: </p> - * - * <p>Description: </p> - * - * <p>Company: </p> - * - * @author not attributable - * @version 1.0 - */ public abstract class ReceiverBase implements ChannelReceiver, ListenCallback, RxTaskPool.TaskCreator { public static final int OPTION_DIRECT_BUFFER = 0x0004; @@ -224,7 +214,7 @@ public abstract class ReceiverBase implements ChannelReceiver, ListenCallback, R * @param portstart Starting port for bind attempts * @param retries Number of times to attempt to bind (port incremented * between attempts) - * @throws IOException + * @throws IOException Socket bind error */ protected void bind(ServerSocket socket, int portstart, int retries) throws IOException { synchronized (bindLock) { @@ -252,11 +242,12 @@ public abstract class ReceiverBase implements ChannelReceiver, ListenCallback, R /** * Same as bind() except it does it for the UDP port - * @param socket - * @param portstart - * @param retries - * @return int - * @throws IOException + * @param socket The socket to bind + * @param portstart Starting port for bind attempts + * @param retries Number of times to attempt to bind (port incremented + * between attempts) + * @return int The retry count + * @throws IOException Socket bind error */ protected int bindUdp(DatagramSocket socket, int portstart, int retries) throws IOException { InetSocketAddress addr = null; @@ -619,4 +610,4 @@ public abstract class ReceiverBase implements ChannelReceiver, ListenCallback, R this.maxIdleTime = maxIdleTime; } -} \ No newline at end of file +} diff --git a/java/org/apache/catalina/tribes/transport/bio/BioReplicationTask.java b/java/org/apache/catalina/tribes/transport/bio/BioReplicationTask.java index a5d724f..88546dc 100644 --- a/java/org/apache/catalina/tribes/transport/bio/BioReplicationTask.java +++ b/java/org/apache/catalina/tribes/transport/bio/BioReplicationTask.java @@ -40,8 +40,6 @@ import org.apache.juli.logging.LogFactory; * serviceChannel() method stores the key reference in the thread object then * calls notify() to wake it up. When the channel has been drained, the worker * thread returns itself to its parent pool. - * - * @author Filip Hanik */ public class BioReplicationTask extends AbstractRxTask { @@ -134,8 +132,9 @@ public class BioReplicationTask extends AbstractRxTask { * interest in OP_READ. When this method completes it * re-enables OP_READ and calls wakeup() on the selector * so the selector will resume watching this channel. + * @throws Exception IO exception or execute exception */ - protected void drainSocket () throws Exception { + protected void drainSocket() throws Exception { InputStream in = socket.getInputStream(); // loop while data available, channel is non-blocking byte[] buf = new byte[1024]; @@ -149,8 +148,8 @@ public class BioReplicationTask extends AbstractRxTask { /** - * send a reply-acknowledgment (6,2,3) - * @param command + * Send a reply-acknowledgment (6,2,3) + * @param command The command to write */ protected void sendAck(byte[] command) { try { diff --git a/java/org/apache/catalina/tribes/transport/bio/BioSender.java b/java/org/apache/catalina/tribes/transport/bio/BioSender.java index cf9c73e..e95a8df 100644 --- a/java/org/apache/catalina/tribes/transport/bio/BioSender.java +++ b/java/org/apache/catalina/tribes/transport/bio/BioSender.java @@ -30,23 +30,24 @@ import org.apache.catalina.tribes.transport.AbstractSender; import org.apache.catalina.tribes.transport.Constants; import org.apache.catalina.tribes.transport.SenderState; import org.apache.catalina.tribes.util.StringManager; +import org.apache.juli.logging.Log; +import org.apache.juli.logging.LogFactory; /** * Send cluster messages with only one socket. Ack and keep Alive Handling is * supported * * @author Peter Rossbach - * @author Filip Hanik * @since 5.5.16 */ public class BioSender extends AbstractSender { - private static final org.apache.juli.logging.Log log = org.apache.juli.logging.LogFactory.getLog(BioSender.class); + private static final Log log = LogFactory.getLog(BioSender.class); /** * The string manager for this package. */ - protected static final StringManager sm = StringManager.getManager(Constants.Package); + protected static final StringManager sm = StringManager.getManager(BioSender.class); // ----------------------------------------------------- Instance Variables @@ -76,7 +77,7 @@ public class BioSender extends AbstractSender { // ------------------------------------------------------------- Properties /** - * Return descriptive information about this implementation and the + * @return descriptive information about this implementation and the * corresponding version number, in the format * <code><description>/<version></code>. */ @@ -147,9 +148,6 @@ public class BioSender extends AbstractSender { } - /** - * Name of this SockerSender - */ @Override public String toString() { StringBuilder buf = new StringBuilder("DataSender[("); @@ -161,8 +159,9 @@ public class BioSender extends AbstractSender { // --------------------------------------------------------- Protected Methods /** - * open real socket and set time out when waitForAck is enabled - * is socket open return directly + * Open real socket and set time out when waitForAck is enabled + * is socket open return directly. + * @throws IOException Error opening socket */ protected void openSocket() throws IOException { if(isConnected()) return ; @@ -233,8 +232,10 @@ public class BioSender extends AbstractSender { * @see #openSocket() * @see #sendMessage(byte[], boolean) * - * @param data - * data to send + * @param data Data to send + * @param reconnect Do a reconnect (close socket then reopen) + * @param waitForAck Wait for an acknowledgement + * @throws IOException IO error writing data * @since 5.5.10 */ @@ -252,8 +253,7 @@ public class BioSender extends AbstractSender { /** * Wait for Acknowledgement from other server. * FIXME Please, not wait only for three characters, better control that the wait ack message is correct. - * @throws java.io.IOException - * @throws java.net.SocketTimeoutException + * @throws IOException An IO error occurred */ protected void waitForAck() throws java.io.IOException { try { diff --git a/java/org/apache/tomcat/util/buf/ByteChunk.java b/java/org/apache/tomcat/util/buf/ByteChunk.java index f80d801..b553c6a 100644 --- a/java/org/apache/tomcat/util/buf/ByteChunk.java +++ b/java/org/apache/tomcat/util/buf/ByteChunk.java @@ -78,6 +78,9 @@ public final class ByteChunk extends AbstractChunk { /** * Read new bytes. * + * @param cbuf bytes that will be read + * @param off offset in the bytes array + * @param len length that will be read * @return The number of bytes read * * @throws IOException If an I/O error occurs during reading @@ -140,6 +143,7 @@ public final class ByteChunk extends AbstractChunk { /** + * @return {@link #clone()} * @deprecated Unused. Will be removed in Tomcat 8.0.x onwards. */ @Deprecated @@ -213,6 +217,7 @@ public final class ByteChunk extends AbstractChunk { /** + * @param optimizedWrite The new setting * @deprecated Unused. Will be removed in Tomcat 8.0.x onwards. */ @Deprecated @@ -277,8 +282,8 @@ public final class ByteChunk extends AbstractChunk { /** * Append a char, by casting it to byte. This IS NOT intended for unicode. * - * @param c - * @throws IOException + * @param c The character to append + * @throws IOException If the buffer is flushed and an I/O error occurs * @deprecated Unused. Will be removed in Tomcat 8.0.x onwards. */ @Deprecated @@ -369,6 +374,10 @@ public final class ByteChunk extends AbstractChunk { /** + * @param src To fill + * @return Count of bytes transferred + * @throws IOException If an I/O occurs obtaining more data to fill the + * supplied ByteChunk * @deprecated Unused. Will be removed in Tomcat 8.0.x onwards. */ @Deprecated @@ -522,6 +531,7 @@ public final class ByteChunk extends AbstractChunk { /** + * @return The content parsed as an int * @deprecated Unused. Will be removed in Tomcat 8.0.x onwards. */ @Deprecated @@ -650,10 +660,9 @@ public final class ByteChunk extends AbstractChunk { /** - * Returns true if the buffer starts with the specified string when tested - * in a case sensitive manner. - * * @param s the string + * @return true if the buffer starts with the specified string when tested + * in a case sensitive manner. * @deprecated Unused. Will be removed in Tomcat 8.0.x onwards. */ @Deprecated @@ -675,7 +684,8 @@ public final class ByteChunk extends AbstractChunk { /** - * Returns true if the message bytes start with the specified byte array. + * @param b2 The byte array to look for + * @return true if the message bytes start with the specified byte array. * * @deprecated Unused. Will be removed in Tomcat 8.0.x onwards. */ @@ -755,6 +765,7 @@ public final class ByteChunk extends AbstractChunk { /** + * @return Hash for lower case version of contents * @deprecated Unused. Will be removed in Tomcat 8.0.x onwards. */ @Deprecated diff --git a/java/org/apache/tomcat/util/buf/MessageBytes.java b/java/org/apache/tomcat/util/buf/MessageBytes.java index b8dbf43..a83f83c 100644 --- a/java/org/apache/tomcat/util/buf/MessageBytes.java +++ b/java/org/apache/tomcat/util/buf/MessageBytes.java @@ -52,7 +52,7 @@ public final class MessageBytes implements Cloneable, Serializable { public static final int T_CHARS = 3; private int hashCode=0; - // did we computed the hashcode ? + // did we compute the hashcode ? private boolean hasHashCode=false; // Internal objects to represent array + offset, and specific methods @@ -73,7 +73,9 @@ public final class MessageBytes implements Cloneable, Serializable { private MessageBytes() { } - /** Construct a new MessageBytes instance + /** + * Construct a new MessageBytes instance. + * @return the instance */ public static MessageBytes newInstance() { return factory.newInstance(); @@ -133,9 +135,9 @@ public final class MessageBytes implements Cloneable, Serializable { /** * Sets the content to be a char[] * - * @param c the bytes - * @param off the start offset of the bytes - * @param len the length of the bytes + * @param c the chars + * @param off the start offset of the chars + * @param len the length of the chars */ public void setChars( char[] c, int off, int len ) { charC.setChars( c, off, len ); @@ -148,6 +150,7 @@ public final class MessageBytes implements Cloneable, Serializable { /** * Set the content to be a string + * @param s The string */ public void setString( String s ) { strValue=s; @@ -165,30 +168,34 @@ public final class MessageBytes implements Cloneable, Serializable { // -------------------- Conversion and getters -------------------- - /** Compute the string value + /** + * Compute the string value. + * @return the string */ @Override public String toString() { - if( hasStrValue ) { + if (hasStrValue) { return strValue; } switch (type) { case T_CHARS: - strValue=charC.toString(); - hasStrValue=true; + strValue = charC.toString(); + hasStrValue = true; return strValue; case T_BYTES: - strValue=byteC.toString(); - hasStrValue=true; + strValue = byteC.toString(); + hasStrValue = true; return strValue; } return null; } //---------------------------------------- - /** Return the type of the original content. Can be - * T_STR, T_BYTES, T_CHARS or T_NULL + /** + * Return the type of the original content. Can be + * T_STR, T_BYTES, T_CHARS or T_NULL + * @return the type */ public int getType() { return type; @@ -197,6 +204,7 @@ public final class MessageBytes implements Cloneable, Serializable { /** * Returns the byte chunk, representing the byte[] and offset/length. * Valid only if T_BYTES or after a conversion was made. + * @return the byte chunk */ public ByteChunk getByteChunk() { return byteC; @@ -205,6 +213,7 @@ public final class MessageBytes implements Cloneable, Serializable { /** * Returns the char chunk, representing the char[] and offset/length. * Valid only if T_CHARS or after a conversion was made. + * @return the char chunk */ public CharChunk getCharChunk() { return charC; @@ -213,13 +222,14 @@ public final class MessageBytes implements Cloneable, Serializable { /** * Returns the string value. * Valid only if T_STR or after a conversion was made. + * @return the string */ public String getString() { return strValue; } /** - * Get the Charset used for string<->byte conversions. + * @return the Charset used for string<->byte conversions. */ public Charset getCharset() { return byteC.getCharset(); @@ -227,37 +237,48 @@ public final class MessageBytes implements Cloneable, Serializable { /** * Set the Charset used for string<->byte conversions. + * @param charset The charset */ public void setCharset(Charset charset) { byteC.setCharset(charset); } - /** Do a char->byte conversion. + + /** + * Do a char->byte conversion. */ public void toBytes() { + if (isNull()) { + return; + } if (!byteC.isNull()) { - type=T_BYTES; + type = T_BYTES; return; } toString(); - type=T_BYTES; + type = T_BYTES; Charset charset = byteC.getCharset(); ByteBuffer result = charset.encode(strValue); byteC.setBytes(result.array(), result.arrayOffset(), result.limit()); } - /** Convert to char[] and fill the CharChunk. - * XXX Not optimized - it converts to String first. + + /** + * Convert to char[] and fill the CharChunk. + * XXX Not optimized - it converts to String first. */ public void toChars() { - if( ! charC.isNull() ) { - type=T_CHARS; + if (isNull()) { + return; + } + if (!charC.isNull()) { + type = T_CHARS; return; } // inefficient toString(); - type=T_CHARS; - char cc[]=strValue.toCharArray(); + type = T_CHARS; + char cc[] = strValue.toCharArray(); charC.setChars(cc, 0, cc.length); } @@ -266,6 +287,7 @@ public final class MessageBytes implements Cloneable, Serializable { * Returns the length of the original buffer. * Note that the length in bytes may be different from the length * in chars. + * @return the length */ public int getLength() { if(type==T_BYTES) { @@ -289,7 +311,7 @@ public final class MessageBytes implements Cloneable, Serializable { /** * Compares the message bytes to the specified String object. * @param s the String to compare - * @return true if the comparison succeeded, false otherwise + * @return <code>true</code> if the comparison succeeded, <code>false</code> otherwise */ public boolean equals(String s) { switch (type) { @@ -310,7 +332,7 @@ public final class MessageBytes implements Cloneable, Serializable { /** * Compares the message bytes to the specified String object. * @param s the String to compare - * @return true if the comparison succeeded, false otherwise + * @return <code>true</code> if the comparison succeeded, <code>false</code> otherwise */ public boolean equalsIgnoreCase(String s) { switch (type) { @@ -389,7 +411,7 @@ public final class MessageBytes implements Cloneable, Serializable { } /** - * Returns true if the message bytes starts with the specified string. + * @return <code>true</code> if the message bytes starts with the specified string. * @param s the string * @param pos The start position */ @@ -501,8 +523,10 @@ public final class MessageBytes implements Cloneable, Serializable { } } - /** Copy the src into this MessageBytes, allocating more space if - * needed + /** + * Copy the src into this MessageBytes, allocating more space if needed. + * @param src The source + * @throws IOException Writing overflow data to the output channel failed */ public void duplicate( MessageBytes src ) throws IOException { @@ -648,7 +672,9 @@ public final class MessageBytes implements Cloneable, Serializable { } // Used for headers conversion - /** Convert the buffer to an long, cache the value + /** + * Convert the buffer to an long, cache the value. + * @return the long value */ public long getLong() { if( hasLongValue ) { --------------------------------------------------------------------- To unsubscribe, e-mail: dev-unsubscr...@tomcat.apache.org For additional commands, e-mail: dev-h...@tomcat.apache.org