Deprecate offset, as mentioned in the todo

Javadoc improvements.

java/org/apache/catalina/authenticator/BasicAuthenticator.java

@@ -197,7 +197,7 @@ public BasicCredentials(ByteChunk input, Charset charset) throws IllegalArgument
         public BasicCredentials(ByteChunk input, Charset charset, boolean trimCredentials)
                 throws IllegalArgumentException {
             authorization = input;
-            initialOffset = input.getOffset();
+            initialOffset = input.getStart();
             this.charset = charset;
             this.trimCredentials = trimCredentials;
 
@@ -249,7 +249,7 @@ private byte[] parseBase64() throws IllegalArgumentException {
             System.arraycopy(authorization.getBuffer(), base64blobOffset, encoded, 0, base64blobLength);
             byte[] decoded = Base64.getDecoder().decode(encoded);
             // restore original offset
-            authorization.setOffset(initialOffset);
+            authorization.setStart(initialOffset);
             if (decoded == null) {
                 throw new IllegalArgumentException(sm.getString("basicAuthenticator.notBase64"));
             }

java/org/apache/catalina/authenticator/SpnegoAuthenticator.java

@@ -163,7 +163,7 @@ protected boolean doAuthenticate(Request request, HttpServletResponse response)
             return false;
         }
 
-        authorizationBC.setOffset(authorizationBC.getOffset() + 10);
+        authorizationBC.setStart(authorizationBC.getStart() + 10);
 
         byte[] encoded = new byte[authorizationBC.getLength()];
         System.arraycopy(authorizationBC.getBuffer(), 0, encoded, 0, authorizationBC.getLength());

java/org/apache/catalina/mapper/Mapper.java

@@ -713,13 +713,13 @@ private void internalMap(CharChunk host, CharChunk uri, String version, MappingD
             // wildcard host. This is to allow this shortcut.
             int firstDot = host.indexOf('.');
             if (firstDot > -1) {
-                int offset = host.getOffset();
+                int start = host.getStart();
                 try {
-                    host.setOffset(firstDot + offset);
+                    host.setStart(firstDot + start);
                     mappedHost = exactFindIgnoreCase(hosts, host);
                 } finally {
                     // Make absolutely sure this gets reset
-                    host.setOffset(offset);
+                    host.setStart(start);
                 }
             }
             if (mappedHost == null) {
@@ -823,16 +823,16 @@ private void internalMap(CharChunk host, CharChunk uri, String version, MappingD
     private void internalMapWrapper(ContextVersion contextVersion, CharChunk path, MappingData mappingData)
             throws IOException {
 
-        int pathOffset = path.getOffset();
+        int pathStart = path.getStart();
         int pathEnd = path.getEnd();
         boolean noServletPath = false;
 
         int length = contextVersion.path.length();
-        if (length == (pathEnd - pathOffset)) {
+        if (length == (pathEnd - pathStart)) {
             noServletPath = true;
         }
-        int servletPath = pathOffset + length;
-        path.setOffset(servletPath);
+        int servletPath = pathStart + length;
+        path.setStart(servletPath);
 
         // Rule 1 -- Exact Match
         MappedWrapper[] exactWrappers = contextVersion.exactWrappers;
@@ -866,7 +866,7 @@ private void internalMapWrapper(ContextVersion contextVersion, CharChunk path, M
             // The path is empty, redirect to "/"
             path.append('/');
             pathEnd = path.getEnd();
-            mappingData.redirectPath.setChars(path.getBuffer(), pathOffset, pathEnd - pathOffset);
+            mappingData.redirectPath.setChars(path.getBuffer(), pathStart, pathEnd - pathStart);
             path.setEnd(pathEnd - 1);
             return;
         }
@@ -886,10 +886,10 @@ private void internalMapWrapper(ContextVersion contextVersion, CharChunk path, M
             }
             if (checkWelcomeFiles) {
                 for (int i = 0; (i < contextVersion.welcomeResources.length) && (mappingData.wrapper == null); i++) {
-                    path.setOffset(pathOffset);
+                    path.setStart(pathStart);
                     path.setEnd(pathEnd);
                     path.append(contextVersion.welcomeResources[i], 0, contextVersion.welcomeResources[i].length());
-                    path.setOffset(servletPath);
+                    path.setStart(servletPath);
 
                     // Rule 4a -- Welcome resources processing for exact macth
                     internalMapExactWrapper(exactWrappers, path, mappingData);
@@ -917,7 +917,7 @@ private void internalMapWrapper(ContextVersion contextVersion, CharChunk path, M
                     }
                 }
 
-                path.setOffset(servletPath);
+                path.setStart(servletPath);
                 path.setEnd(pathEnd);
             }
 
@@ -936,14 +936,14 @@ private void internalMapWrapper(ContextVersion contextVersion, CharChunk path, M
             }
             if (checkWelcomeFiles) {
                 for (int i = 0; (i < contextVersion.welcomeResources.length) && (mappingData.wrapper == null); i++) {
-                    path.setOffset(pathOffset);
+                    path.setStart(pathStart);
                     path.setEnd(pathEnd);
                     path.append(contextVersion.welcomeResources[i], 0, contextVersion.welcomeResources[i].length());
-                    path.setOffset(servletPath);
+                    path.setStart(servletPath);
                     internalMapExtensionWrapper(extensionWrappers, path, mappingData, false);
                 }
 
-                path.setOffset(servletPath);
+                path.setStart(servletPath);
                 path.setEnd(pathEnd);
             }
         }
@@ -975,7 +975,7 @@ private void internalMapWrapper(ContextVersion contextVersion, CharChunk path, M
                         // Note: this mutates the path: do not do any processing
                         // after this (since we set the redirectPath, there
                         // shouldn't be any)
-                        path.setOffset(pathOffset);
+                        path.setStart(pathStart);
                         path.append('/');
                         mappingData.redirectPath.setChars(path.getBuffer(), path.getStart(), path.getLength());
                     } else {
@@ -989,7 +989,7 @@ private void internalMapWrapper(ContextVersion contextVersion, CharChunk path, M
             }
         }
 
-        path.setOffset(pathOffset);
+        path.setStart(pathStart);
         path.setEnd(pathEnd);
     }
 
@@ -1054,10 +1054,10 @@ private void internalMapWildcardWrapper(MappedWrapper[] wrappers, int nesting, C
             if (found) {
                 mappingData.wrapperPath.setString(wrappers[pos].name);
                 if (path.getLength() > length) {
-                    mappingData.pathInfo.setChars(path.getBuffer(), path.getOffset() + length,
+                    mappingData.pathInfo.setChars(path.getBuffer(), path.getStart() + length,
                             path.getLength() - length);
                 }
-                mappingData.requestPath.setChars(path.getBuffer(), path.getOffset(), path.getLength());
+                mappingData.requestPath.setChars(path.getBuffer(), path.getStart(), path.getLength());
                 mappingData.wrapper = wrappers[pos].object;
                 mappingData.jspWildCard = wrappers[pos].jspWildCard;
                 mappingData.matchType = MappingMatch.PATH;
@@ -1078,7 +1078,7 @@ private void internalMapExtensionWrapper(MappedWrapper[] wrappers, CharChunk pat
             boolean resourceExpected) {
         char[] buf = path.getBuffer();
         int pathEnd = path.getEnd();
-        int servletPath = path.getOffset();
+        int servletPath = path.getStart();
         int slash = -1;
         for (int i = pathEnd - 1; i >= servletPath; i--) {
             if (buf[i] == '/') {
@@ -1095,7 +1095,7 @@ private void internalMapExtensionWrapper(MappedWrapper[] wrappers, CharChunk pat
                 }
             }
             if (period >= 0) {
-                path.setOffset(period + 1);
+                path.setStart(period + 1);
                 path.setEnd(pathEnd);
                 MappedWrapper wrapper = exactFind(wrappers, path);
                 if (wrapper != null && (resourceExpected || !wrapper.resourceOnly)) {
@@ -1104,7 +1104,7 @@ private void internalMapExtensionWrapper(MappedWrapper[] wrappers, CharChunk pat
                     mappingData.wrapper = wrapper.object;
                     mappingData.matchType = MappingMatch.EXTENSION;
                 }
-                path.setOffset(servletPath);
+                path.setStart(servletPath);
                 path.setEnd(pathEnd);
             }
         }

java/org/apache/coyote/ajp/AjpMessage.java

@@ -167,7 +167,7 @@ public void appendBytes(MessageBytes mb) {
             // values will be OK. Strings using other encodings may be
             // corrupted.
             byte[] buffer = bc.getBuffer();
-            for (int i = bc.getOffset(); i < bc.getLength(); i++) {
+            for (int i = bc.getStart(); i < bc.getLength(); i++) {
                 // byte values are signed i.e. -128 to 127
                 // The values are used unsigned. 0 to 31 are CTLs so they are
                 // filtered (apart from TAB which is 9). 127 is a control (DEL).

java/org/apache/coyote/ajp/AjpProcessor.java

@@ -713,7 +713,7 @@ private void prepareRequest() {
             } else if (hId == Constants.SC_REQ_CONTENT_TYPE || (hId == -1 && tmpMB.equalsIgnoreCase("Content-Type"))) {
                 // just read the content-type header, so set it
                 ByteChunk bchunk = vMB.getByteChunk();
-                request.contentType().setBytes(bchunk.getBytes(), bchunk.getOffset(), bchunk.getLength());
+                request.contentType().setBytes(bchunk.getBytes(), bchunk.getStart(), bchunk.getLength());
             }
         }
 

java/org/apache/coyote/http11/Http11OutputBuffer.java

@@ -388,7 +388,7 @@ private void write(MessageBytes mb) {
             // values will be OK. Strings using other encodings may be
             // corrupted.
             byte[] buffer = bc.getBuffer();
-            for (int i = bc.getOffset(); i < bc.getLength(); i++) {
+            for (int i = bc.getStart(); i < bc.getLength(); i++) {
                 // byte values are signed i.e. -128 to 127
                 // The values are used unsigned. 0 to 31 are CTLs so they are
                 // filtered (apart from TAB which is 9). 127 is a control (DEL).

java/org/apache/coyote/http11/filters/SavedRequestInputFilter.java

@@ -46,7 +46,7 @@ public SavedRequestInputFilter(ByteChunk input) {
 
     @Override
     public int doRead(ApplicationBufferHandler handler) throws IOException {
-        if(input.getOffset()>= input.getEnd()) {
+        if(input.getStart()>= input.getEnd()) {
             return -1;
         }
 
@@ -104,6 +104,6 @@ public long end() throws IOException {
 
     @Override
     public boolean isFinished() {
-        return input.getOffset() >= input.getEnd();
+        return input.getStart() >= input.getEnd();
     }
 }

java/org/apache/coyote/http2/Stream.java

@@ -1362,7 +1362,7 @@ final ByteBuffer getInBuffer() {
         final void insertReplayedBody(ByteChunk body) {
             readStateLock.lock();
             try {
-                inBuffer = ByteBuffer.wrap(body.getBytes(), body.getOffset(), body.getLength());
+                inBuffer = ByteBuffer.wrap(body.getBytes(), body.getStart(), body.getLength());
             } finally {
                 readStateLock.unlock();
             }

java/org/apache/tomcat/util/buf/AbstractChunk.java

@@ -58,6 +58,9 @@ public void setLimit(int limit) {
     }
 
 
+    /**
+     * @return the maximum amount of data in the buffer, and -1 if it has not been set
+     */
     public int getLimit() {
         return limit;
     }
@@ -80,23 +83,50 @@ public int getStart() {
     }
 
 
+    /**
+     * Set the start position of the data in the buffer.
+     * @param start the new start position
+     */
+    public void setStart(int start) {
+        if (end < start) {
+            end = start;
+        }
+        this.start = start;
+    }
+
+
+    /**
+     * @return the end position of the data in the buffer
+     */
     public int getEnd() {
         return end;
     }
 
 
-    public void setEnd(int i) {
-        end = i;
+    /**
+     * Set the end position of the data in the buffer.
+     * @param end the new end position
+     */
+    public void setEnd(int end) {
+        this.end = end;
     }
 
 
-    // TODO: Deprecate offset and use start
-
+    /**
+     * @return start
+     * @deprecated Unused. This method will be removed in Tomcat 12.
+     */
+    @Deprecated
     public int getOffset() {
         return start;
     }
 
-
+    /**
+     * Set start.
+     * @param off the new start
+     * @deprecated Unused. This method will be removed in Tomcat 12.
+     */
+    @Deprecated
     public void setOffset(int off) {
         if (end < off) {
             end = off;
@@ -113,6 +143,9 @@ public int getLength() {
     }
 
 
+    /**
+     * @return {@code true} if the buffer contains no data
+     */
     public boolean isNull() {
         if (end > 0) {
             return false;
@@ -121,19 +154,30 @@ public boolean isNull() {
     }
 
 
-    public int indexOf(String src, int srcOff, int srcLen, int myOff) {
-        char first = src.charAt(srcOff);
+    /**
+     * Return the index of the first occurrence of the subsequence of
+     * the given String, or -1 if it is not found.
+     *
+     * @param src the String to look for
+     * @param srcStart the subsequence start in the String
+     * @param srcLen the subsequence length in the String
+     * @param myOffset the index on which to start the search in the buffer
+     * @return the position of the first character of the first occurrence
+     *         of the subsequence in the buffer, or -1 if not found
+     */
+    public int indexOf(String src, int srcStart, int srcLen, int myOffset) {
+        char first = src.charAt(srcStart);
 
         // Look for first char
-        int srcEnd = srcOff + srcLen;
+        int srcEnd = srcStart + srcLen;
 
-        mainLoop: for (int i = myOff + start; i <= (end - srcLen); i++) {
+        mainLoop: for (int i = myOffset + start; i <= (end - srcLen); i++) {
             if (getBufferElement(i) != first) {
                 continue;
             }
             // found first char, now look for a match
             int myPos = i + 1;
-            for (int srcPos = srcOff + 1; srcPos < srcEnd;) {
+            for (int srcPos = srcStart + 1; srcPos < srcEnd;) {
                 if (getBufferElement(myPos++) != src.charAt(srcPos++)) {
                     continue mainLoop;
                 }
@@ -169,6 +213,9 @@ public int hashCode() {
     }
 
 
+    /**
+     * @return the hash code for this buffer
+     */
     public int hash() {
         int code = 0;
         for (int i = start; i < end; i++) {
@@ -178,5 +225,9 @@ public int hash() {
     }
 
 
+    /**
+     * @param index the element location in the buffer
+     * @return the element
+     */
     protected abstract int getBufferElement(int index);
 }

java/org/apache/tomcat/util/buf/B2CConverter.java

@@ -169,11 +169,11 @@ public void convert(ByteChunk bc, CharChunk cc, boolean endOfInput) throws IOExc
         } else if (result.isOverflow()) {
             // Propagate current positions to the byte chunk and char chunk, if
             // this continues the char buffer will get resized
-            bc.setOffset(bb.position());
+            bc.setStart(bb.position());
             cc.setEnd(cb.position());
         } else if (result.isUnderflow()) {
             // Propagate current positions to the byte chunk and char chunk
-            bc.setOffset(bb.position());
+            bc.setStart(bb.position());
             cc.setEnd(cb.position());
             // Put leftovers in the leftovers byte buffer
             if (bc.getLength() > 0) {

java/org/apache/tomcat/util/buf/C2BConverter.java

@@ -121,11 +121,11 @@ public void convert(CharChunk cc, ByteChunk bc) throws IOException {
         } else if (result.isOverflow()) {
             // Propagate current positions to the byte chunk and char chunk
             bc.setEnd(bb.position());
-            cc.setOffset(cb.position());
+            cc.setStart(cb.position());
         } else if (result.isUnderflow()) {
             // Propagate current positions to the byte chunk and char chunk
             bc.setEnd(bb.position());
-            cc.setOffset(cb.position());
+            cc.setStart(cb.position());
             // Put leftovers in the leftovers char buffer
             if (cc.getLength() > 0) {
                 leftovers.limit(leftovers.array().length);