Deprecate ByteBufIndexFinder

- Prefer ByteBufProcessor
- Related: #1378

buffer/src/main/java/io/netty/buffer/AbstractByteBuf.java

@@ -987,6 +987,7 @@ public abstract class AbstractByteBuf implements ByteBuf {
     }
 
     @Override
+    @Deprecated
     public int indexOf(int fromIndex, int toIndex, ByteBufIndexFinder indexFinder) {
         return ByteBufUtil.indexOf(this, fromIndex, toIndex, indexFinder);
     }
@@ -997,6 +998,7 @@ public abstract class AbstractByteBuf implements ByteBuf {
     }
 
     @Override
+    @Deprecated
     public int bytesBefore(ByteBufIndexFinder indexFinder) {
         return bytesBefore(readerIndex(), readableBytes(), indexFinder);
     }
@@ -1008,6 +1010,7 @@ public abstract class AbstractByteBuf implements ByteBuf {
     }
 
     @Override
+    @Deprecated
     public int bytesBefore(int length, ByteBufIndexFinder indexFinder) {
         checkReadableBytes(length);
         return bytesBefore(readerIndex(), length, indexFinder);
@@ -1023,8 +1026,8 @@ public abstract class AbstractByteBuf implements ByteBuf {
     }
 
     @Override
-    public int bytesBefore(int index, int length,
+    @Deprecated
-            ByteBufIndexFinder indexFinder) {
+    public int bytesBefore(int index, int length, ByteBufIndexFinder indexFinder) {
         int endIndex = indexOf(index, index + length, indexFinder);
         if (endIndex < 0) {
             return -1;

buffer/src/main/java/io/netty/buffer/ByteBuf.java

@@ -176,15 +176,12 @@ import java.nio.charset.UnsupportedCharsetException;
  *
  * <h3>Search operations</h3>
  *
- * Various {@link #indexOf(int, int, byte)} methods help you locate an index of
+ * For simple single-byte searches, use {@link #indexOf(int, int, byte)} and {@link #bytesBefore(int, int, byte)}.
- * a value which meets a certain criteria.  Complicated dynamic sequential
+ * {@link #bytesBefore(byte)} is especially useful when you deal with a {@code NUL}-terminated string.
- * search can be done with {@link ByteBufIndexFinder} as well as simple
+ * For complicated searches, use {@link #forEachByte(int, int, ByteBufProcessor)} with a {@link ByteBufProcessor}
- * static single byte search.
+ * implementation.
- * <p>
- * If you are decoding variable length data such as NUL-terminated string, you
- * will find {@link #bytesBefore(byte)} also useful.
  *
- * <h3>Mark and reset</h3>
+ *  <h3>Mark and reset</h3>
  *
  * There are two marker indexes in every buffer. One is for storing
  * {@link #readerIndex() readerIndex} and the other is for storing
@@ -1577,6 +1574,8 @@ public interface ByteBuf extends ReferenceCounted, Comparable<ByteBuf> {
     int indexOf(int fromIndex, int toIndex, byte value);
 
     /**
+     * @deprecated Use {@link #forEachByte(int, int, ByteBufProcessor)} instead.
+     *
      * Locates the first place where the specified {@code indexFinder}
      * returns {@code true}.  The search takes place from the specified
      * {@code fromIndex} (inclusive) to the specified {@code toIndex}
@@ -1592,6 +1591,7 @@ public interface ByteBuf extends ReferenceCounted, Comparable<ByteBuf> {
      *         returned {@code true}.  {@code -1} if the {@code indexFinder}
      *         did not return {@code true} at all.
      */
+    @Deprecated
     int indexOf(int fromIndex, int toIndex, ByteBufIndexFinder indexFinder);
 
     /**
@@ -1608,6 +1608,8 @@ public interface ByteBuf extends ReferenceCounted, Comparable<ByteBuf> {
     int bytesBefore(byte value);
 
     /**
+     * @deprecated Use {@link #forEachByte(ByteBufProcessor)} instead.
+     *
      * Locates the first place where the specified {@code indexFinder} returns
      * {@code true}.  The search takes place from the current {@code readerIndex}
      * (inclusive) to the current {@code writerIndex}.
@@ -1620,6 +1622,7 @@ public interface ByteBuf extends ReferenceCounted, Comparable<ByteBuf> {
      *         {@code true}.  {@code -1} if the {@code indexFinder} did not
      *         return {@code true} at all.
      */
+    @Deprecated
     int bytesBefore(ByteBufIndexFinder indexFinder);
 
     /**
@@ -1639,6 +1642,8 @@ public interface ByteBuf extends ReferenceCounted, Comparable<ByteBuf> {
     int bytesBefore(int length, byte value);
 
     /**
+     * @deprecated Use {@link #forEachByte(int, int, ByteBufProcessor)} instead.
+     *
      * Locates the first place where the specified {@code indexFinder} returns
      * {@code true}.  The search starts the current {@code readerIndex}
      * (inclusive) and lasts for the specified {@code length}.
@@ -1654,6 +1659,7 @@ public interface ByteBuf extends ReferenceCounted, Comparable<ByteBuf> {
      * @throws IndexOutOfBoundsException
      *         if {@code length} is greater than {@code this.readableBytes}
      */
+    @Deprecated
     int bytesBefore(int length, ByteBufIndexFinder indexFinder);
 
     /**
@@ -1673,6 +1679,8 @@ public interface ByteBuf extends ReferenceCounted, Comparable<ByteBuf> {
     int bytesBefore(int index, int length, byte value);
 
     /**
+     * @deprecated Use {@link #forEachByte(int, int, ByteBufProcessor)} instead.
+     *
      * Locates the first place where the specified {@code indexFinder} returns
      * {@code true}.  The search starts the specified {@code index} (inclusive)
      * and lasts for the specified {@code length}.
@@ -1688,6 +1696,7 @@ public interface ByteBuf extends ReferenceCounted, Comparable<ByteBuf> {
      * @throws IndexOutOfBoundsException
      *         if {@code index + length} is greater than {@code this.capacity}
      */
+    @Deprecated
     int bytesBefore(int index, int length, ByteBufIndexFinder indexFinder);
 
     /**

buffer/src/main/java/io/netty/buffer/ByteBufIndexFinder.java

@@ -17,6 +17,8 @@ package io.netty.buffer;
 
 
 /**
+ * @deprecated Use {@link ByteBufProcessor} instead.
+ *
  * Locates an index of data in a {@link ByteBuf}.
  * <p>
  * This interface enables the sequential search for the data which meets more
@@ -25,6 +27,7 @@ package io.netty.buffer;
  * {@link ByteBuf#bytesBefore(int, int, ByteBufIndexFinder)}
  * for more explanation.
  */
+@Deprecated
 public interface ByteBufIndexFinder {
 
     /**
@@ -38,8 +41,11 @@ public interface ByteBufIndexFinder {
     boolean find(ByteBuf buffer, int guessedIndex);
 
     /**
+     * @deprecated Use {@link ByteBufProcessor#FIND_NUL} instead.
+     *
      * Index finder which locates a {@code NUL (0x00)} byte.
      */
+    @Deprecated
     ByteBufIndexFinder NUL = new ByteBufIndexFinder() {
         @Override
         public boolean find(ByteBuf buffer, int guessedIndex) {
@@ -48,8 +54,11 @@ public interface ByteBufIndexFinder {
     };
 
     /**
+     * @deprecated Use {@link ByteBufProcessor#FIND_NON_NUL} instead.
+     *
      * Index finder which locates a non-{@code NUL (0x00)} byte.
      */
+    @Deprecated
     ByteBufIndexFinder NOT_NUL = new ByteBufIndexFinder() {
         @Override
         public boolean find(ByteBuf buffer, int guessedIndex) {
@@ -58,8 +67,11 @@ public interface ByteBufIndexFinder {
     };
 
     /**
+     * @deprecated Use {@link ByteBufProcessor#FIND_CR} instead.
+     *
      * Index finder which locates a {@code CR ('\r')} byte.
      */
+    @Deprecated
     ByteBufIndexFinder CR = new ByteBufIndexFinder() {
         @Override
         public boolean find(ByteBuf buffer, int guessedIndex) {
@@ -68,8 +80,11 @@ public interface ByteBufIndexFinder {
     };
 
     /**
+     * @deprecated Use {@link ByteBufProcessor#FIND_NON_CR} instead.
+     *
      * Index finder which locates a non-{@code CR ('\r')} byte.
      */
+    @Deprecated
     ByteBufIndexFinder NOT_CR = new ByteBufIndexFinder() {
         @Override
         public boolean find(ByteBuf buffer, int guessedIndex) {
@@ -78,8 +93,11 @@ public interface ByteBufIndexFinder {
     };
 
     /**
+     * @deprecated Use {@link ByteBufProcessor#FIND_LF} instead.
+     *
      * Index finder which locates a {@code LF ('\n')} byte.
      */
+    @Deprecated
     ByteBufIndexFinder LF = new ByteBufIndexFinder() {
         @Override
         public boolean find(ByteBuf buffer, int guessedIndex) {
@@ -88,8 +106,11 @@ public interface ByteBufIndexFinder {
     };
 
     /**
+     * @deprecated Use {@link ByteBufProcessor#FIND_NON_LF} instead.
+     *
      * Index finder which locates a non-{@code LF ('\n')} byte.
      */
+    @Deprecated
     ByteBufIndexFinder NOT_LF = new ByteBufIndexFinder() {
         @Override
         public boolean find(ByteBuf buffer, int guessedIndex) {
@@ -98,8 +119,11 @@ public interface ByteBufIndexFinder {
     };
 
     /**
+     * @deprecated Use {@link ByteBufProcessor#FIND_CRLF} instead.
+     *
      * Index finder which locates a {@code CR ('\r')} or {@code LF ('\n')}.
      */
+    @Deprecated
     ByteBufIndexFinder CRLF = new ByteBufIndexFinder() {
         @Override
         public boolean find(ByteBuf buffer, int guessedIndex) {
@@ -109,9 +133,11 @@ public interface ByteBufIndexFinder {
     };
 
     /**
-     * Index finder which locates a byte which is neither a {@code CR ('\r')}
+     * @deprecated Use {@link ByteBufProcessor#FIND_NON_CRLF} instead.
-     * nor a {@code LF ('\n')}.
+     *
+     * Index finder which locates a byte which is neither a {@code CR ('\r')} nor a {@code LF ('\n')}.
      */
+    @Deprecated
     ByteBufIndexFinder NOT_CRLF = new ByteBufIndexFinder() {
         @Override
         public boolean find(ByteBuf buffer, int guessedIndex) {
@@ -121,9 +147,11 @@ public interface ByteBufIndexFinder {
     };
 
     /**
-     * Index finder which locates a linear whitespace
+     * @deprecated Use {@link ByteBufProcessor#FIND_LINEAR_WHITESPACE} instead.
-     * ({@code ' '} and {@code '\t'}).
+     *
+     * Index finder which locates a linear whitespace ({@code ' '} and {@code '\t'}).
      */
+    @Deprecated
     ByteBufIndexFinder LINEAR_WHITESPACE = new ByteBufIndexFinder() {
         @Override
         public boolean find(ByteBuf buffer, int guessedIndex) {
@@ -133,9 +161,11 @@ public interface ByteBufIndexFinder {
     };
 
     /**
-     * Index finder which locates a byte which is not a linear whitespace
+     * @deprecated Use {@link ByteBufProcessor#FIND_NON_LINEAR_WHITESPACE} instead.
-     * (neither {@code ' '} nor {@code '\t'}).
+     *
+     * Index finder which locates a byte which is not a linear whitespace (neither {@code ' '} nor {@code '\t'}).
      */
+    @Deprecated
     ByteBufIndexFinder NOT_LINEAR_WHITESPACE = new ByteBufIndexFinder() {
         @Override
         public boolean find(ByteBuf buffer, int guessedIndex) {

buffer/src/main/java/io/netty/buffer/ByteBufProcessor.java

@@ -19,8 +19,149 @@ package io.netty.buffer;
 import io.netty.util.Signal;
 
 public interface ByteBufProcessor {
+
     Signal ABORT = new Signal(ByteBufProcessor.class.getName() + ".ABORT");
 
+    /**
+     * Aborts on a {@code NUL (0x00)}.
+     */
+    ByteBufProcessor FIND_NUL = new ByteBufProcessor() {
+        @Override
+        public int process(ByteBuf buf, int index, byte value) throws Exception {
+            if (value == 0) {
+                throw ABORT;
+            } else {
+                return 1;
+            }
+        }
+    };
+
+    /**
+     * Aborts on a non-{@code NUL (0x00)}.
+     */
+    ByteBufProcessor FIND_NON_NUL = new ByteBufProcessor() {
+        @Override
+        public int process(ByteBuf buf, int index, byte value) throws Exception {
+            if (value != 0) {
+                throw ABORT;
+            } else {
+                return 1;
+            }
+        }
+    };
+
+    /**
+     * Aborts on a {@code CR ('\r')}.
+     */
+    ByteBufProcessor FIND_CR = new ByteBufProcessor() {
+        @Override
+        public int process(ByteBuf buf, int index, byte value) throws Exception {
+            if (value == '\r') {
+                throw ABORT;
+            } else {
+                return 1;
+            }
+        }
+    };
+
+    /**
+     * Aborts on a non-{@code CR ('\r')}.
+     */
+    ByteBufProcessor FIND_NON_CR = new ByteBufProcessor() {
+        @Override
+        public int process(ByteBuf buf, int index, byte value) throws Exception {
+            if (value != '\r') {
+                throw ABORT;
+            } else {
+                return 1;
+            }
+        }
+    };
+
+    /**
+     * Aborts on a {@code LF ('\n')}.
+     */
+    ByteBufProcessor FIND_LF = new ByteBufProcessor() {
+        @Override
+        public int process(ByteBuf buf, int index, byte value) throws Exception {
+            if (value == '\n') {
+                throw ABORT;
+            } else {
+                return 1;
+            }
+        }
+    };
+
+    /**
+     * Aborts on a non-{@code LF ('\n')}.
+     */
+    ByteBufProcessor FIND_NON_LF = new ByteBufProcessor() {
+        @Override
+        public int process(ByteBuf buf, int index, byte value) throws Exception {
+            if (value != '\n') {
+                throw ABORT;
+            } else {
+                return 1;
+            }
+        }
+    };
+
+    /**
+     * Aborts on a {@code CR ('\r')} or a {@code LF ('\n')}.
+     */
+    ByteBufProcessor FIND_CRLF = new ByteBufProcessor() {
+        @Override
+        public int process(ByteBuf buf, int index, byte value) throws Exception {
+            if (value == '\r' || value == '\n') {
+                throw ABORT;
+            } else {
+                return 1;
+            }
+        }
+    };
+
+    /**
+     * Aborts on a byte which is neither a {@code CR ('\r')} nor a {@code LF ('\n')}.
+     */
+    ByteBufProcessor FIND_NON_CRLF = new ByteBufProcessor() {
+        @Override
+        public int process(ByteBuf buf, int index, byte value) throws Exception {
+            if (value != '\r' && value != '\n') {
+                throw ABORT;
+            } else {
+                return 1;
+            }
+        }
+    };
+
+    /**
+     * Aborts on a linear whitespace (a ({@code ' '} or a {@code '\t'}).
+     */
+    ByteBufProcessor FIND_LINEAR_WHITESPACE = new ByteBufProcessor() {
+        @Override
+        public int process(ByteBuf buf, int index, byte value) throws Exception {
+            if (value == ' ' || value == '\t') {
+                throw ABORT;
+            } else {
+                return 1;
+            }
+        }
+    };
+
+    /**
+     * Aborts on a byte which is not a linear whitespace (neither {@code ' '} nor {@code '\t'}).
+     */
+    ByteBufProcessor FIND_NON_LINEAR_WHITESPACE = new ByteBufProcessor() {
+        @Override
+        public int process(ByteBuf buf, int index, byte value) throws Exception {
+            if (value != ' ' && value != '\t') {
+                throw ABORT;
+            } else {
+                return 1;
+            }
+        }
+    };
+
     /**
      * @return the number of elements processed. {@link ByteBuf#forEachByte(ByteBufProcessor)} will determine
      *         the index of the next byte to be processed based on this value.  Usually, an implementation will

buffer/src/main/java/io/netty/buffer/ByteBufUtil.java

@@ -277,6 +277,7 @@ public final class ByteBufUtil {
      * The default implementation of {@link ByteBuf#indexOf(int, int, ByteBufIndexFinder)}.
      * This method is useful when implementing a new buffer type.
      */
+    @Deprecated
     public static int indexOf(ByteBuf buffer, int fromIndex, int toIndex, ByteBufIndexFinder indexFinder) {
         if (fromIndex <= toIndex) {
             return firstIndexOf(buffer, fromIndex, toIndex, indexFinder);
@@ -347,8 +348,8 @@ public final class ByteBufUtil {
         return -1;
     }
 
-    private static int firstIndexOf(
+    @SuppressWarnings("deprecation")
-            ByteBuf buffer, int fromIndex, int toIndex, ByteBufIndexFinder indexFinder) {
+    private static int firstIndexOf(ByteBuf buffer, int fromIndex, int toIndex, ByteBufIndexFinder indexFinder) {
         fromIndex = Math.max(fromIndex, 0);
         if (fromIndex >= toIndex || buffer.capacity() == 0) {
             return -1;
@@ -363,8 +364,8 @@ public final class ByteBufUtil {
         return -1;
     }
 
-    private static int lastIndexOf(
+    @SuppressWarnings("deprecation")
-            ByteBuf buffer, int fromIndex, int toIndex, ByteBufIndexFinder indexFinder) {
+    private static int lastIndexOf(ByteBuf buffer, int fromIndex, int toIndex, ByteBufIndexFinder indexFinder) {
         fromIndex = Math.min(fromIndex, buffer.capacity());
         if (fromIndex < 0 || buffer.capacity() == 0) {
             return -1;

buffer/src/main/java/io/netty/buffer/EmptyByteBuf.java

@@ -668,6 +668,7 @@ public final class EmptyByteBuf implements ByteBuf {
     }
 
     @Override
+    @Deprecated
     public int indexOf(int fromIndex, int toIndex, ByteBufIndexFinder indexFinder) {
         checkIndex(fromIndex);
         checkIndex(toIndex);
@@ -680,6 +681,7 @@ public final class EmptyByteBuf implements ByteBuf {
     }
 
     @Override
+    @Deprecated
     public int bytesBefore(ByteBufIndexFinder indexFinder) {
         return -1;
     }
@@ -691,6 +693,7 @@ public final class EmptyByteBuf implements ByteBuf {
     }
 
     @Override
+    @Deprecated
     public int bytesBefore(int length, ByteBufIndexFinder indexFinder) {
         checkLength(length);
         return -1;
@@ -703,6 +706,7 @@ public final class EmptyByteBuf implements ByteBuf {
     }
 
     @Override
+    @Deprecated
     public int bytesBefore(int index, int length, ByteBufIndexFinder indexFinder) {
         checkIndex(index, length);
         return -1;

buffer/src/main/java/io/netty/buffer/SwappedByteBuf.java

@@ -681,6 +681,7 @@ public final class SwappedByteBuf implements ByteBuf {
     }
 
     @Override
+    @Deprecated
     public int indexOf(int fromIndex, int toIndex, ByteBufIndexFinder indexFinder) {
         return buf.indexOf(fromIndex, toIndex, indexFinder);
     }
@@ -691,6 +692,7 @@ public final class SwappedByteBuf implements ByteBuf {
     }
 
     @Override
+    @Deprecated
     public int bytesBefore(ByteBufIndexFinder indexFinder) {
         return buf.bytesBefore(new SwappedByteBufIndexFinder(indexFinder));
     }
@@ -701,6 +703,7 @@ public final class SwappedByteBuf implements ByteBuf {
     }
 
     @Override
+    @Deprecated
     public int bytesBefore(int length, ByteBufIndexFinder indexFinder) {
         return buf.bytesBefore(length, new SwappedByteBufIndexFinder(indexFinder));
     }
@@ -711,6 +714,7 @@ public final class SwappedByteBuf implements ByteBuf {
     }
 
     @Override
+    @Deprecated
     public int bytesBefore(int index, int length, ByteBufIndexFinder indexFinder) {
         return buf.bytesBefore(index, length, new SwappedByteBufIndexFinder(indexFinder));
     }
@@ -877,6 +881,7 @@ public final class SwappedByteBuf implements ByteBuf {
         return "Swapped(" + buf.toString() + ')';
     }
 
+    @SuppressWarnings("deprecation")
     private final class SwappedByteBufIndexFinder implements ByteBufIndexFinder {
         private final ByteBufIndexFinder indexFinder;
 

buffer/src/main/java/io/netty/buffer/UnreleasableByteBuf.java

@@ -687,6 +687,7 @@ final class UnreleasableByteBuf implements ByteBuf {
     }
 
     @Override
+    @Deprecated
     public int indexOf(int fromIndex, int toIndex, ByteBufIndexFinder indexFinder) {
         return buf.indexOf(fromIndex, toIndex, indexFinder);
     }
@@ -697,6 +698,7 @@ final class UnreleasableByteBuf implements ByteBuf {
     }
 
     @Override
+    @Deprecated
     public int bytesBefore(ByteBufIndexFinder indexFinder) {
         return buf.bytesBefore(indexFinder);
     }
@@ -707,6 +709,7 @@ final class UnreleasableByteBuf implements ByteBuf {
     }
 
     @Override
+    @Deprecated
     public int bytesBefore(int length, ByteBufIndexFinder indexFinder) {
         return buf.bytesBefore(length, indexFinder);
     }
@@ -717,6 +720,7 @@ final class UnreleasableByteBuf implements ByteBuf {
     }
 
     @Override
+    @Deprecated
     public int bytesBefore(int index, int length, ByteBufIndexFinder indexFinder) {
         return buf.bytesBefore(index, length, indexFinder);
     }

codec/src/main/java/io/netty/handler/codec/ReplayingDecoderBuffer.java

@@ -307,6 +307,7 @@ final class ReplayingDecoderBuffer implements ByteBuf {
     }
 
     @Override
+    @Deprecated
     public int indexOf(int fromIndex, int toIndex, ByteBufIndexFinder indexFinder) {
         int endIndex = buffer.indexOf(fromIndex, toIndex, indexFinder);
         if (endIndex < 0) {
@@ -325,6 +326,7 @@ final class ReplayingDecoderBuffer implements ByteBuf {
     }
 
     @Override
+    @Deprecated
     public int bytesBefore(ByteBufIndexFinder indexFinder) {
         int bytes = buffer.bytesBefore(indexFinder);
         if (bytes < 0) {
@@ -344,6 +346,7 @@ final class ReplayingDecoderBuffer implements ByteBuf {
     }
 
     @Override
+    @Deprecated
     public int bytesBefore(int length, ByteBufIndexFinder indexFinder) {
         checkReadableBytes(length);
         int bytes = buffer.bytesBefore(length, indexFinder);
@@ -363,6 +366,7 @@ final class ReplayingDecoderBuffer implements ByteBuf {
     }
 
     @Override
+    @Deprecated
     public int bytesBefore(int index, int length, ByteBufIndexFinder indexFinder) {
         int bytes = buffer.bytesBefore(index, length, indexFinder);
         if (bytes < 0) {