You are viewing a plain text version of this content. The canonical link for it is here.
Posted to dev@tomcat.apache.org by re...@apache.org on 2023/11/07 15:29:45 UTC
(tomcat) branch 10.1.x updated: Javadoc and comments cleanup
This is an automated email from the ASF dual-hosted git repository.
remm pushed a commit to branch 10.1.x
in repository https://gitbox.apache.org/repos/asf/tomcat.git
The following commit(s) were added to refs/heads/10.1.x by this push:
new bf9074ff8d Javadoc and comments cleanup
bf9074ff8d is described below
commit bf9074ff8ddf104409f165deddb589a17689d362
Author: remm <re...@apache.org>
AuthorDate: Tue Nov 7 16:14:19 2023 +0100
Javadoc and comments cleanup
Remove lots of old todos that are either done or not actually useful
(for example, the one buffer parsing for HTTP/1.1 was done with Coyote).
Deprecate MimeHeaders.clear which only had one caller, in favor of the
more consistently used recycle (at least in Tomcat).
---
java/org/apache/coyote/Response.java | 2 +-
java/org/apache/tomcat/util/buf/ByteChunk.java | 53 +++++++------
java/org/apache/tomcat/util/buf/CharChunk.java | 2 +-
java/org/apache/tomcat/util/buf/MessageBytes.java | 5 +-
java/org/apache/tomcat/util/http/MimeHeaders.java | 92 ++++++++---------------
5 files changed, 66 insertions(+), 88 deletions(-)
diff --git a/java/org/apache/coyote/Response.java b/java/org/apache/coyote/Response.java
index 5eae29558d..354634513d 100644
--- a/java/org/apache/coyote/Response.java
+++ b/java/org/apache/coyote/Response.java
@@ -633,7 +633,7 @@ public final class Response {
commitTimeNanos = -1;
errorException = null;
errorState.set(0);
- headers.clear();
+ headers.recycle();
trailerFieldsSupplier = null;
// Servlet 3.1 non-blocking write listener
listener = null;
diff --git a/java/org/apache/tomcat/util/buf/ByteChunk.java b/java/org/apache/tomcat/util/buf/ByteChunk.java
index 27c985e6e2..f53102ddc5 100644
--- a/java/org/apache/tomcat/util/buf/ByteChunk.java
+++ b/java/org/apache/tomcat/util/buf/ByteChunk.java
@@ -26,23 +26,6 @@ import java.nio.charset.Charset;
import java.nio.charset.CodingErrorAction;
import java.nio.charset.StandardCharsets;
-/*
- * In a server it is very important to be able to operate on
- * the original byte[] without converting everything to chars.
- * Some protocols are ASCII only, and some allow different
- * non-UNICODE encodings. The encoding is not known beforehand,
- * and can even change during the execution of the protocol.
- * ( for example a multipart message may have parts with different
- * encoding )
- *
- * For HTTP it is not very clear how the encoding of RequestURI
- * and mime values can be determined, but it is a great advantage
- * to be able to parse the request without converting to string.
- */
-
-// TODO: This class could either extend ByteBuffer, or better a ByteBuffer
-// inside this way it could provide the search/etc on ByteBuffer, as a helper.
-
/**
* This class is used to represent a chunk of bytes, and utilities to manipulate byte[].
* <p>
@@ -57,6 +40,18 @@ import java.nio.charset.StandardCharsets;
* This is important because it allows processing the http headers directly on the received bytes, without converting to
* chars and Strings until the strings are needed. In addition, the charset is determined later, from headers or user
* code.
+ * <p>
+ * In a server it is very important to be able to operate on
+ * the original byte[] without converting everything to chars.
+ * Some protocols are ASCII only, and some allow different
+ * non-UNICODE encodings. The encoding is not known beforehand,
+ * and can even change during the execution of the protocol.
+ * ( for example a multipart message may have parts with different
+ * encoding )
+ * <p>
+ * For HTTP it is not very clear how the encoding of RequestURI
+ * and mime values can be determined, but it is a great advantage
+ * to be able to parse the request without converting to string.
*
* @author dac@sun.com
* @author James Todd [gonzo@sun.com]
@@ -494,7 +489,7 @@ public final class ByteChunk extends AbstractChunk {
}
// limit < buf.length (the buffer is already big)
- // or we already have space XXX
+ // or we already have space
if (desiredSize <= buff.length) {
return;
}
@@ -608,15 +603,14 @@ public final class ByteChunk extends AbstractChunk {
/**
* Compares the message bytes to the specified String object.
+ * <p>
+ * NOTE: This only works for characters in the range 0-127.
*
* @param s the String to compare
*
* @return <code>true</code> if the comparison succeeded, <code>false</code> otherwise
*/
public boolean equals(String s) {
- // XXX ENCODING - this only works if encoding is UTF8-compat
- // ( ok for tomcat, where we compare ascii - header names, etc )!!!
-
byte[] b = buff;
int len = end - start;
if (b == null || len != s.length()) {
@@ -634,6 +628,8 @@ public final class ByteChunk extends AbstractChunk {
/**
* Compares the message bytes to the specified String object.
+ * <p>
+ * NOTE: This only works for characters in the range 0-127.
*
* @param s the String to compare
*
@@ -687,8 +683,17 @@ public final class ByteChunk extends AbstractChunk {
}
+ /**
+ * Compares the message bytes to the specified char array.
+ * <p>
+ * NOTE: This only works for characters in the range 0-127.
+ *
+ * @param c2 the array to compare to
+ * @param off2 offset
+ * @param len2 length
+ * @return <code>true</code> if the comparison succeeded, <code>false</code> otherwise
+ */
public boolean equals(char c2[], int off2, int len2) {
- // XXX works only for enc compatible with ASCII/UTF !!!
byte b1[] = buff;
if (c2 == null && b1 == null) {
return true;
@@ -711,6 +716,8 @@ public final class ByteChunk extends AbstractChunk {
/**
* Returns true if the buffer starts with the specified string when tested in a case sensitive manner.
+ * <p>
+ * NOTE: This only works for characters in the range 0-127.
*
* @param s the string
* @param pos The position
@@ -735,6 +742,8 @@ public final class ByteChunk extends AbstractChunk {
/**
* Returns true if the buffer starts with the specified string when tested in a case insensitive manner.
+ * <p>
+ * NOTE: This only works for characters in the range 0-127.
*
* @param s the string
* @param pos The position
diff --git a/java/org/apache/tomcat/util/buf/CharChunk.java b/java/org/apache/tomcat/util/buf/CharChunk.java
index b0b4745768..4f3dcf4188 100644
--- a/java/org/apache/tomcat/util/buf/CharChunk.java
+++ b/java/org/apache/tomcat/util/buf/CharChunk.java
@@ -369,7 +369,7 @@ public final class CharChunk extends AbstractChunk implements CharSequence {
}
// limit < buf.length (the buffer is already big)
- // or we already have space XXX
+ // or we already have space
if (desiredSize <= buff.length) {
return;
}
diff --git a/java/org/apache/tomcat/util/buf/MessageBytes.java b/java/org/apache/tomcat/util/buf/MessageBytes.java
index 0eee6e75d4..70ac7d9bfe 100644
--- a/java/org/apache/tomcat/util/buf/MessageBytes.java
+++ b/java/org/apache/tomcat/util/buf/MessageBytes.java
@@ -571,9 +571,7 @@ public final class MessageBytes implements Cloneable, Serializable {
setCharset(src.getCharset());
}
- // -------------------- Deprecated code --------------------
// efficient long
- // XXX used only for headers - shouldn't be stored here.
private long longValue;
private boolean hasLongValue = false;
@@ -620,9 +618,8 @@ public final class MessageBytes implements Cloneable, Serializable {
type = T_BYTES;
}
- // Used for headers conversion
/**
- * Convert the buffer to a long, cache the value.
+ * Convert the buffer to a long, cache the value. Used for headers conversion.
*
* @return the long value
*/
diff --git a/java/org/apache/tomcat/util/http/MimeHeaders.java b/java/org/apache/tomcat/util/http/MimeHeaders.java
index f0bb2aef48..dbe0cee272 100644
--- a/java/org/apache/tomcat/util/http/MimeHeaders.java
+++ b/java/org/apache/tomcat/util/http/MimeHeaders.java
@@ -24,63 +24,44 @@ import java.util.Enumeration;
import org.apache.tomcat.util.buf.MessageBytes;
import org.apache.tomcat.util.res.StringManager;
-/*
+/**
+ * Memory-efficient repository for Mime Headers. When the object is recycled, it will keep the allocated headers[] and
+ * all the MimeHeaderField - no GC is generated.
+ * <p>
+ * For input headers it is possible to use the MessageByte for Fields - so no GC will be generated.
+ * <p>
+ * The only garbage is generated when using the String for header names/values - this can't be avoided when the servlet
+ * calls header methods, but is easy to avoid inside tomcat. The goal is to use _only_ MessageByte-based Fields, and
+ * reduce to 0 the memory overhead of tomcat.
+ * <p>
* This class is used to contain standard internet message headers,
* used for SMTP (RFC822) and HTTP (RFC2068) messages as well as for
* MIME (RFC 2045) applications such as transferring typed data and
* grouping related items in multipart message bodies.
- *
- * <P> Message headers, as specified in RFC822, include a field name
+ * <p>
+ * Message headers, as specified in RFC822, include a field name
* and a field body. Order has no semantic significance, and several
* fields with the same name may exist. However, most fields do not
* (and should not) exist more than once in a header.
- *
- * <P> Many kinds of field body must conform to a specified syntax,
+ * <p>
+ * Many kinds of field body must conform to a specified syntax,
* including the standard parenthesized comment syntax. This class
* supports only two simple syntaxes, for dates and integers.
- *
- * <P> When processing headers, care must be taken to handle the case of
+ * <p>
+ * When processing headers, care must be taken to handle the case of
* multiple same-name fields correctly. The values of such fields are
* only available as strings. They may be accessed by index (treating
* the header as an array of fields), or by name (returning an array
* of string values).
- */
-
-/* Headers are first parsed and stored in the order they are
- received. This is based on the fact that most servlets will not
- directly access all headers, and most headers are single-valued.
- ( the alternative - a hash or similar data structure - will add
- an overhead that is not needed in most cases )
-
- Apache seems to be using a similar method for storing and manipulating
- headers.
-
- Future enhancements:
- - hash the headers the first time a header is requested ( i.e. if the
- servlet needs direct access to headers).
- - scan "common" values ( length, cookies, etc ) during the parse
- ( addHeader hook )
-
- */
-
-
-/**
- * Memory-efficient repository for Mime Headers. When the object is recycled, it will keep the allocated headers[] and
- * all the MimeHeaderField - no GC is generated.
- * <p>
- * For input headers it is possible to use the MessageByte for Fields - so no GC will be generated.
* <p>
- * The only garbage is generated when using the String for header names/values - this can't be avoided when the servlet
- * calls header methods, but is easy to avoid inside tomcat. The goal is to use _only_ MessageByte-based Fields, and
- * reduce to 0 the memory overhead of tomcat.
+ * Headers are first parsed and stored in the order they are
+ * received. This is based on the fact that most servlets will not
+ * directly access all headers, and most headers are single-valued.
+ * (the alternative - a hash or similar data structure - will add
+ * an overhead that is not needed in most cases)
* <p>
- * TODO:
- * <ul>
- * <li>one-buffer parsing - for http (other protocols don't need that)</li>
- * <li>remove unused methods</li>
- * <li>External enumerations, with 0 GC.</li>
- * <li>use HeaderName ID</li>
- * </ul>
+ * Apache seems to be using a similar method for storing and manipulating
+ * headers.
*
* @author dac@eng.sun.com
* @author James Todd [gonzo@eng.sun.com]
@@ -88,9 +69,9 @@ import org.apache.tomcat.util.res.StringManager;
* @author kevin seguin
*/
public class MimeHeaders {
+
/**
- * Initial size - should be == average number of headers per request XXX make it configurable ( fine-tuning of
- * web-apps )
+ * Initial size - should be == average number of headers per request
*/
public static final int DEFAULT_HEADER_SIZE = 8;
@@ -136,24 +117,18 @@ public class MimeHeaders {
/**
* Clears all header fields.
*/
- // [seguin] added for consistency -- most other objects have recycle().
public void recycle() {
- clear();
- }
-
- /**
- * Clears all header fields.
- */
- public void clear() {
for (int i = 0; i < count; i++) {
headers[i].recycle();
}
count = 0;
}
- /**
- * EXPENSIVE!!! only for debugging.
- */
+ @Deprecated
+ public void clear() {
+ recycle();
+ }
+
@Override
public String toString() {
StringWriter sw = new StringWriter();
@@ -333,6 +308,7 @@ public class MimeHeaders {
}
// -------------------- Getting headers --------------------
+
/**
* Finds and returns a header field with the given name. If no such field exists, null is returned. If more than one
* such field is in the header, an arbitrary one is returned.
@@ -374,23 +350,19 @@ public class MimeHeaders {
return result;
}
- // bad shortcut - it'll convert to string ( too early probably,
- // encoding is guessed very late )
public String getHeader(String name) {
MessageBytes mh = getValue(name);
return mh != null ? mh.toString() : null;
}
// -------------------- Removing --------------------
+
/**
* Removes a header field with the specified name. Does nothing if such a field could not be found.
*
* @param name the name of the header field to be removed
*/
public void removeHeader(String name) {
- // XXX
- // warning: rather sticky code; heavily tuned
-
for (int i = 0; i < count; i++) {
if (headers[i].getName().equalsIgnoreCase(name)) {
removeHeader(i--);
---------------------------------------------------------------------
To unsubscribe, e-mail: dev-unsubscribe@tomcat.apache.org
For additional commands, e-mail: dev-help@tomcat.apache.org