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 2021/11/24 12:27:43 UTC
[tomcat] 01/06: Javadoc improvements back-ported from 10.1.x
This is an automated email from the ASF dual-hosted git repository.
markt pushed a commit to branch 10.0.x
in repository https://gitbox.apache.org/repos/asf/tomcat.git
commit 9152dcb3c6382948f171353fa3f276ee77290a33
Author: Mark Thomas <ma...@apache.org>
AuthorDate: Wed Nov 24 12:09:48 2021 +0000
Javadoc improvements back-ported from 10.1.x
---
.../catalina/core/ApplicationFilterConfig.java | 16 ++++++-----
java/org/apache/catalina/filters/CorsFilter.java | 2 +-
java/org/apache/catalina/mapper/Mapper.java | 3 +-
.../org/apache/catalina/mapper/MapperListener.java | 6 ++--
.../apache/catalina/webresources/StandardRoot.java | 2 +-
java/org/apache/coyote/ajp/AjpProcessor.java | 2 +-
java/org/apache/coyote/http2/HpackDecoder.java | 2 +-
java/org/apache/coyote/http2/Http2Parser.java | 2 +-
.../apache/jasper/compiler/AttributeParser.java | 6 ----
java/org/apache/jasper/compiler/ELParser.java | 3 +-
.../tomcat/dbcp/dbcp2/BasicDataSourceFactory.java | 4 +--
.../tomcat/util/bcel/classfile/ClassParser.java | 32 +++++++++++-----------
.../tomcat/util/bcel/classfile/ConstantDouble.java | 3 +-
.../tomcat/util/bcel/classfile/ConstantFloat.java | 3 +-
.../util/bcel/classfile/ConstantInteger.java | 3 +-
.../tomcat/util/bcel/classfile/ConstantLong.java | 3 +-
.../tomcat/util/bcel/classfile/ConstantPool.java | 4 +--
java/org/apache/tomcat/util/buf/UriUtil.java | 4 +--
.../apache/tomcat/util/http/parser/TokenList.java | 4 +--
.../tomcat/websocket/WsWebSocketContainer.java | 11 +++++---
.../startup/TestContextConfigAnnotation.java | 6 +---
.../classes/websocket/drawboard/Client.java | 3 +-
.../WEB-INF/classes/websocket/drawboard/Room.java | 18 ++++++------
23 files changed, 73 insertions(+), 69 deletions(-)
diff --git a/java/org/apache/catalina/core/ApplicationFilterConfig.java b/java/org/apache/catalina/core/ApplicationFilterConfig.java
index aede350..3b81f73 100644
--- a/java/org/apache/catalina/core/ApplicationFilterConfig.java
+++ b/java/org/apache/catalina/core/ApplicationFilterConfig.java
@@ -85,9 +85,10 @@ public final class ApplicationFilterConfig implements FilterConfig, Serializable
* @exception InstantiationException if an exception occurs while
* instantiating the filter object
* @exception ServletException if thrown by the filter's init() method
- * @throws NamingException
- * @throws SecurityException
- * @throws IllegalArgumentException
+ * @throws NamingException If a JNDI lookup fails
+ * @throws SecurityException If a security manager prevents the creation
+ * @throws IllegalArgumentException If the provided configuration is not
+ * valid
*/
ApplicationFilterConfig(Context context, FilterDef filterDef)
throws ClassCastException, ReflectiveOperationException, ServletException,
@@ -232,10 +233,11 @@ public final class ApplicationFilterConfig implements FilterConfig, Serializable
* @exception InstantiationException if an exception occurs while
* instantiating the filter object
* @exception ServletException if thrown by the filter's init() method
- * @throws NamingException
- * @throws ReflectiveOperationException
- * @throws SecurityException
- * @throws IllegalArgumentException
+ * @throws NamingException If a JNDI lookup fails
+ * @throws ReflectiveOperationException If the creation of the filter fails
+ * @throws SecurityException If a security manager prevents the creation
+ * @throws IllegalArgumentException If the provided configuration is not
+ * valid
*/
Filter getFilter() throws ClassCastException, ReflectiveOperationException, ServletException,
NamingException, IllegalArgumentException, SecurityException {
diff --git a/java/org/apache/catalina/filters/CorsFilter.java b/java/org/apache/catalina/filters/CorsFilter.java
index f64d7ad..b3d187e 100644
--- a/java/org/apache/catalina/filters/CorsFilter.java
+++ b/java/org/apache/catalina/filters/CorsFilter.java
@@ -706,7 +706,7 @@ public class CorsFilter extends GenericFilter {
* @param preflightMaxAge
* The amount of seconds the user agent is allowed to cache the
* result of the pre-flight request.
- * @throws ServletException
+ * @throws ServletException If the configuration is invalid
*/
private void parseAndStore(final String allowedOrigins,
final String allowedHttpMethods, final String allowedHttpHeaders,
diff --git a/java/org/apache/catalina/mapper/Mapper.java b/java/org/apache/catalina/mapper/Mapper.java
index a5f9dc2..f51a69c 100644
--- a/java/org/apache/catalina/mapper/Mapper.java
+++ b/java/org/apache/catalina/mapper/Mapper.java
@@ -730,7 +730,8 @@ public final class Mapper {
/**
* Map the specified URI.
- * @throws IOException
+ * @throws IOException If an error occurs while manipulating the URI during
+ * the mapping
*/
private final void internalMap(CharChunk host, CharChunk uri,
String version, MappingData mappingData) throws IOException {
diff --git a/java/org/apache/catalina/mapper/MapperListener.java b/java/org/apache/catalina/mapper/MapperListener.java
index 6b024f2..fa303c4 100644
--- a/java/org/apache/catalina/mapper/MapperListener.java
+++ b/java/org/apache/catalina/mapper/MapperListener.java
@@ -508,7 +508,8 @@ public class MapperListener extends LifecycleMBeanBase
/**
* Add this mapper to the container and all child containers
*
- * @param container
+ * @param container the container (and any associated childern) to which
+ * the mapper is to be added
*/
private void addListeners(Container container) {
container.addContainerListener(this);
@@ -522,7 +523,8 @@ public class MapperListener extends LifecycleMBeanBase
/**
* Remove this mapper from the container and all child containers
*
- * @param container
+ * @param container the container (and any associated childern) from which
+ * the mapper is to be removed
*/
private void removeListeners(Container container) {
container.removeContainerListener(this);
diff --git a/java/org/apache/catalina/webresources/StandardRoot.java b/java/org/apache/catalina/webresources/StandardRoot.java
index ec28485..daa60d5 100644
--- a/java/org/apache/catalina/webresources/StandardRoot.java
+++ b/java/org/apache/catalina/webresources/StandardRoot.java
@@ -237,7 +237,7 @@ public class StandardRoot extends LifecycleMBeanBase implements WebResourceRoot
* that the path is a String that starts with '/' and checks that the path
* can be normalized without stepping outside of the root.
*
- * @param path
+ * @param path The path to validate
* @return the normalized path
*/
private String validate(String path) {
diff --git a/java/org/apache/coyote/ajp/AjpProcessor.java b/java/org/apache/coyote/ajp/AjpProcessor.java
index b98f78c..caecb89 100644
--- a/java/org/apache/coyote/ajp/AjpProcessor.java
+++ b/java/org/apache/coyote/ajp/AjpProcessor.java
@@ -1229,7 +1229,7 @@ public class AjpProcessor extends AbstractProcessor {
* called, should this call block until data becomes available?
* @return <code>true</code> if the requested number of bytes were read
* else <code>false</code>
- * @throws IOException
+ * @throws IOException If an I/O error occurs during the read
*/
private boolean read(byte[] buf, int pos, int n, boolean block) throws IOException {
int read = socketWrapper.read(block, buf, pos, n);
diff --git a/java/org/apache/coyote/http2/HpackDecoder.java b/java/org/apache/coyote/http2/HpackDecoder.java
index badebad..7cd5a13 100644
--- a/java/org/apache/coyote/http2/HpackDecoder.java
+++ b/java/org/apache/coyote/http2/HpackDecoder.java
@@ -259,7 +259,7 @@ public class HpackDecoder {
* Handle an indexed header representation
*
* @param index The index
- * @throws HpackException
+ * @throws HpackException If an error occurs processing the given index
*/
private void handleIndex(int index) throws HpackException {
if (index <= Hpack.STATIC_TABLE_LENGTH) {
diff --git a/java/org/apache/coyote/http2/Http2Parser.java b/java/org/apache/coyote/http2/Http2Parser.java
index 0e489e8..30d2118 100644
--- a/java/org/apache/coyote/http2/Http2Parser.java
+++ b/java/org/apache/coyote/http2/Http2Parser.java
@@ -352,7 +352,7 @@ class Http2Parser {
* @param streamId The pushed stream
* @param buffer The payload, if available
*
- * @throws Http2Exception
+ * @throws Http2Exception Always
*/
protected void readPushPromiseFrame(int streamId, ByteBuffer buffer) throws Http2Exception {
throw new ConnectionException(sm.getString("http2Parser.processFramePushPromise",
diff --git a/java/org/apache/jasper/compiler/AttributeParser.java b/java/org/apache/jasper/compiler/AttributeParser.java
index 5575237..bcb8bc3 100644
--- a/java/org/apache/jasper/compiler/AttributeParser.java
+++ b/java/org/apache/jasper/compiler/AttributeParser.java
@@ -89,12 +89,6 @@ public class AttributeParser {
private final StringBuilder result;
- /**
- * For test purposes.
- * @param input
- * @param quote
- * @param strict
- */
private AttributeParser(String input, char quote,
boolean isELIgnored, boolean isDeferredSyntaxAllowedAsLiteral,
boolean strict, boolean quoteAttributeEL) {
diff --git a/java/org/apache/jasper/compiler/ELParser.java b/java/org/apache/jasper/compiler/ELParser.java
index c06a2b6..8f7ad93 100644
--- a/java/org/apache/jasper/compiler/ELParser.java
+++ b/java/org/apache/jasper/compiler/ELParser.java
@@ -236,7 +236,8 @@ public class ELParser {
* for $ and # is optional.
*
* @param input Non-EL input to be escaped
- * @param isDeferredSyntaxAllowedAsLiteral
+ * @param isDeferredSyntaxAllowedAsLiteral Flag that indicates if deferred
+ * syntax (#{) is allowed as a literal.\
*
* @return The escaped version of the input
*/
diff --git a/java/org/apache/tomcat/dbcp/dbcp2/BasicDataSourceFactory.java b/java/org/apache/tomcat/dbcp/dbcp2/BasicDataSourceFactory.java
index a71f8ff..7a77f40 100644
--- a/java/org/apache/tomcat/dbcp/dbcp2/BasicDataSourceFactory.java
+++ b/java/org/apache/tomcat/dbcp/dbcp2/BasicDataSourceFactory.java
@@ -319,9 +319,9 @@ public class BasicDataSourceFactory implements ObjectFactory {
/**
* Parse properties from the string. Format of the string must be [propertyName=property;]*
*
- * @param propText
+ * @param propText The string containing the properties
* @return Properties
- * @throws IOException
+ * @throws IOException If the properties string is not correctly formatted
*/
private static Properties getProperties(final String propText) throws IOException {
final Properties p = new Properties();
diff --git a/java/org/apache/tomcat/util/bcel/classfile/ClassParser.java b/java/org/apache/tomcat/util/bcel/classfile/ClassParser.java
index 3e18993..90fb145 100644
--- a/java/org/apache/tomcat/util/bcel/classfile/ClassParser.java
+++ b/java/org/apache/tomcat/util/bcel/classfile/ClassParser.java
@@ -106,8 +106,8 @@ public final class ClassParser {
/**
* Reads information about the attributes of the class.
* @param fieldOrMethod false if processing a class
- * @throws IOException
- * @throws ClassFormatException
+ * @throws IOException if an I/O occurs reading the the .class file
+ * @throws ClassFormatException If the .class file is not valid
*/
private void readAttributes(boolean fieldOrMethod) throws IOException, ClassFormatException {
final int attributes_count = dataInputStream.readUnsignedShort();
@@ -147,8 +147,8 @@ public final class ClassParser {
/**
* Reads information about the class and its super class.
- * @throws IOException
- * @throws ClassFormatException
+ * @throws IOException if an I/O occurs reading the the .class file
+ * @throws ClassFormatException If the .class file is not valid
*/
private void readClassInfo() throws IOException, ClassFormatException {
accessFlags = dataInputStream.readUnsignedShort();
@@ -178,8 +178,8 @@ public final class ClassParser {
/**
* Reads constant pool entries.
- * @throws IOException
- * @throws ClassFormatException
+ * @throws IOException if an I/O occurs reading the the .class file
+ * @throws ClassFormatException If the .class file is not valid
*/
private void readConstantPool() throws IOException, ClassFormatException {
constantPool = new ConstantPool(dataInputStream);
@@ -188,8 +188,8 @@ public final class ClassParser {
/**
* Reads information about the fields of the class, i.e., its variables.
- * @throws IOException
- * @throws ClassFormatException
+ * @throws IOException if an I/O occurs reading the the .class file
+ * @throws ClassFormatException If the .class file is not valid
*/
private void readFields() throws IOException, ClassFormatException {
final int fields_count = dataInputStream.readUnsignedShort();
@@ -208,8 +208,8 @@ public final class ClassParser {
/**
* Checks whether the header of the file is ok.
* Of course, this has to be the first action on successive file reads.
- * @throws IOException
- * @throws ClassFormatException
+ * @throws IOException if an I/O occurs reading the the .class file
+ * @throws ClassFormatException If the .class file is not valid
*/
private void readID() throws IOException, ClassFormatException {
if (dataInputStream.readInt() != MAGIC) {
@@ -220,8 +220,8 @@ public final class ClassParser {
/**
* Reads information about the interfaces implemented by this class.
- * @throws IOException
- * @throws ClassFormatException
+ * @throws IOException if an I/O occurs reading the the .class file
+ * @throws ClassFormatException If the .class file is not valid
*/
private void readInterfaces() throws IOException, ClassFormatException {
final int interfaces_count = dataInputStream.readUnsignedShort();
@@ -239,8 +239,8 @@ public final class ClassParser {
/**
* Reads information about the methods of the class.
- * @throws IOException
- * @throws ClassFormatException
+ * @throws IOException if an I/O occurs reading the the .class file
+ * @throws ClassFormatException If the .class file is not valid
*/
private void readMethods() throws IOException, ClassFormatException {
final int methods_count = dataInputStream.readUnsignedShort();
@@ -257,8 +257,8 @@ public final class ClassParser {
/**
* Reads major and minor version of compiler which created the file.
- * @throws IOException
- * @throws ClassFormatException
+ * @throws IOException if an I/O occurs reading the the .class file
+ * @throws ClassFormatException If the .class file is not valid
*/
private void readVersion() throws IOException, ClassFormatException {
// file.readUnsignedShort(); // Unused minor
diff --git a/java/org/apache/tomcat/util/bcel/classfile/ConstantDouble.java b/java/org/apache/tomcat/util/bcel/classfile/ConstantDouble.java
index 1152dbd..1c69a76 100644
--- a/java/org/apache/tomcat/util/bcel/classfile/ConstantDouble.java
+++ b/java/org/apache/tomcat/util/bcel/classfile/ConstantDouble.java
@@ -37,7 +37,8 @@ public final class ConstantDouble extends Constant {
* Initialize instance from file data.
*
* @param file Input stream
- * @throws IOException
+ * @throws IOException If an I/O occurs reading from the provided
+ * InoutStream
*/
ConstantDouble(final DataInput file) throws IOException {
super(Const.CONSTANT_Double);
diff --git a/java/org/apache/tomcat/util/bcel/classfile/ConstantFloat.java b/java/org/apache/tomcat/util/bcel/classfile/ConstantFloat.java
index 1fd2450..4a699b6 100644
--- a/java/org/apache/tomcat/util/bcel/classfile/ConstantFloat.java
+++ b/java/org/apache/tomcat/util/bcel/classfile/ConstantFloat.java
@@ -37,7 +37,8 @@ public final class ConstantFloat extends Constant {
* Initialize instance from file data.
*
* @param file Input stream
- * @throws IOException
+ * @throws IOException If an I/O occurs reading from the provided
+ * InoutStream
*/
ConstantFloat(final DataInput file) throws IOException {
super(Const.CONSTANT_Float);
diff --git a/java/org/apache/tomcat/util/bcel/classfile/ConstantInteger.java b/java/org/apache/tomcat/util/bcel/classfile/ConstantInteger.java
index 0d95983..c2960ac 100644
--- a/java/org/apache/tomcat/util/bcel/classfile/ConstantInteger.java
+++ b/java/org/apache/tomcat/util/bcel/classfile/ConstantInteger.java
@@ -37,7 +37,8 @@ public final class ConstantInteger extends Constant {
* Initialize instance from file data.
*
* @param file Input stream
- * @throws IOException
+ * @throws IOException If an I/O occurs reading from the provided
+ * InoutStream
*/
ConstantInteger(final DataInput file) throws IOException {
super(Const.CONSTANT_Integer);
diff --git a/java/org/apache/tomcat/util/bcel/classfile/ConstantLong.java b/java/org/apache/tomcat/util/bcel/classfile/ConstantLong.java
index d7affef..b6dc2c0 100644
--- a/java/org/apache/tomcat/util/bcel/classfile/ConstantLong.java
+++ b/java/org/apache/tomcat/util/bcel/classfile/ConstantLong.java
@@ -37,7 +37,8 @@ public final class ConstantLong extends Constant {
* Initialize instance from file data.
*
* @param input Input stream
- * @throws IOException
+ * @throws IOException If an I/O occurs reading from the provided
+ * InoutStream
*/
ConstantLong(final DataInput input) throws IOException {
super(Const.CONSTANT_Long);
diff --git a/java/org/apache/tomcat/util/bcel/classfile/ConstantPool.java b/java/org/apache/tomcat/util/bcel/classfile/ConstantPool.java
index 81280c3..ac36aa1 100644
--- a/java/org/apache/tomcat/util/bcel/classfile/ConstantPool.java
+++ b/java/org/apache/tomcat/util/bcel/classfile/ConstantPool.java
@@ -40,8 +40,8 @@ public class ConstantPool {
* Reads constants from given input stream.
*
* @param input Input stream
- * @throws IOException
- * @throws ClassFormatException
+ * @throws IOException if an I/O occurs reading the the InputStream
+ * @throws ClassFormatException If the .class file is not valid
*/
ConstantPool(final DataInput input) throws IOException, ClassFormatException {
final int constant_pool_count = input.readUnsignedShort();
diff --git a/java/org/apache/tomcat/util/buf/UriUtil.java b/java/org/apache/tomcat/util/buf/UriUtil.java
index 374814b..a1c56e5 100644
--- a/java/org/apache/tomcat/util/buf/UriUtil.java
+++ b/java/org/apache/tomcat/util/buf/UriUtil.java
@@ -201,8 +201,8 @@ public final class UriUtil {
*
* @param path The path to test
*
- * @return {@code} if the supplied path starts with once of the recognised
- * sequences.
+ * @return {@code true} if the supplied path starts with once of the
+ * recognised sequences.
*/
public static boolean isAbsoluteURI(String path) {
// Special case as only a single /
diff --git a/java/org/apache/tomcat/util/http/parser/TokenList.java b/java/org/apache/tomcat/util/http/parser/TokenList.java
index ec69d3c..d805c61 100644
--- a/java/org/apache/tomcat/util/http/parser/TokenList.java
+++ b/java/org/apache/tomcat/util/http/parser/TokenList.java
@@ -38,7 +38,7 @@ public class TokenList {
* @param collection The Collection (usually a list or a set) to which the
* parsed tokens should be added
*
- * @return {@code} true if the header values were parsed cleanly and at
+ * @return {@code true} if the header values were parsed cleanly and at
* least one token was found, otherwise {@code false} (e.g. if a
* non-token value was encountered)
*
@@ -66,7 +66,7 @@ public class TokenList {
* @param collection The Collection (usually a list or a set) to which the
* parsed tokens should be added
*
- * @return {@code} true if the header values were parsed cleanly and at
+ * @return {@code true} if the header values were parsed cleanly and at
* least one token was found, otherwise {@code false} (e.g. if a
* non-token value was encountered)
*
diff --git a/java/org/apache/tomcat/websocket/WsWebSocketContainer.java b/java/org/apache/tomcat/websocket/WsWebSocketContainer.java
index 52d7837..7792122 100644
--- a/java/org/apache/tomcat/websocket/WsWebSocketContainer.java
+++ b/java/org/apache/tomcat/websocket/WsWebSocketContainer.java
@@ -781,10 +781,13 @@ public class WsWebSocketContainer implements WebSocketContainer, BackgroundProce
/**
* Process response, blocking until HTTP response has been fully received.
- * @throws ExecutionException
- * @throws InterruptedException
- * @throws DeploymentException
- * @throws TimeoutException
+ * @throws ExecutionException if there is an exception reading the response
+ * @throws InterruptedException if the thread is interrupted while reading
+ * the response
+ * @throws DeploymentException if the response status line is not correctly
+ * formatted
+ * @throws TimeoutException if the response was not read within the expected
+ * timeout
*/
private HttpResponse processResponse(ByteBuffer response,
AsyncChannelWrapper channel, long timeout) throws InterruptedException,
diff --git a/test/org/apache/catalina/startup/TestContextConfigAnnotation.java b/test/org/apache/catalina/startup/TestContextConfigAnnotation.java
index bf82b93..f395e7d 100644
--- a/test/org/apache/catalina/startup/TestContextConfigAnnotation.java
+++ b/test/org/apache/catalina/startup/TestContextConfigAnnotation.java
@@ -349,12 +349,8 @@ public class TestContextConfigAnnotation {
public void removePropertyChangeListener(PropertyChangeListener l) {}
}
- /**
+ /*
* Find compiled test class
- *
- * @param className
- * @return File Resource
- * @throws URISyntaxException
*/
private File paramClassResource(String className) throws URISyntaxException {
URL url = getClass().getClassLoader().getResource(className + ".class");
diff --git a/webapps/examples/WEB-INF/classes/websocket/drawboard/Client.java b/webapps/examples/WEB-INF/classes/websocket/drawboard/Client.java
index 0123c08..b4c8da7 100644
--- a/webapps/examples/WEB-INF/classes/websocket/drawboard/Client.java
+++ b/webapps/examples/WEB-INF/classes/websocket/drawboard/Client.java
@@ -165,7 +165,8 @@ public class Client {
/**
* Internally sends the messages asynchronously.
- * @param msg
+ *
+ * @param msg Message to send
*/
private void internalSendMessageAsync(AbstractWebsocketMessage msg) {
try {
diff --git a/webapps/examples/WEB-INF/classes/websocket/drawboard/Room.java b/webapps/examples/WEB-INF/classes/websocket/drawboard/Room.java
index 00c013f..60bc69e 100644
--- a/webapps/examples/WEB-INF/classes/websocket/drawboard/Room.java
+++ b/webapps/examples/WEB-INF/classes/websocket/drawboard/Room.java
@@ -215,7 +215,7 @@ public final class Room {
/**
* @see Player#removeFromRoom()
- * @param p
+ * @param p player to remove
*/
private void internalRemovePlayer(Player p) {
boolean removed = players.remove(p);
@@ -239,9 +239,9 @@ public final class Room {
/**
* @see Player#handleDrawMessage(DrawMessage, long)
- * @param p
- * @param msg
- * @param msgId
+ * @param p player
+ * @param msg message containing details of new shapes to draw
+ * @param msgId message ID
*/
private void internalHandleDrawMessage(Player p, DrawMessage msg,
long msgId) {
@@ -261,8 +261,8 @@ public final class Room {
* {@link #broadcastDrawMessage(DrawMessage)}
* as this method will buffer them and prefix them with the correct
* last received Message ID.
- * @param type
- * @param content
+ * @param type message type
+ * @param content message content
*/
private void broadcastRoomMessage(MessageType type, String content) {
for (Player p : players) {
@@ -276,7 +276,7 @@ public final class Room {
* and the {@link #drawmessageBroadcastTimer} will broadcast them
* at a regular interval, prefixing them with the player's current
* {@link Player#lastReceivedMessageId}.
- * @param msg
+ * @param msg message to broadcast
*/
private void broadcastDrawMessage(DrawMessage msg) {
if (!BUFFER_DRAW_MESSAGES) {
@@ -482,8 +482,8 @@ public final class Room {
/**
* Sends the given room message.
- * @param type
- * @param content
+ * @param type message type
+ * @param content message content
*/
private void sendRoomMessage(MessageType type, String content) {
Objects.requireNonNull(content);
---------------------------------------------------------------------
To unsubscribe, e-mail: dev-unsubscribe@tomcat.apache.org
For additional commands, e-mail: dev-help@tomcat.apache.org