#7281 add Interceptor javadoc

Signed-off-by: Ludovic Orban <lorban@bitronix.be>

jetty-server/src/main/java/org/eclipse/jetty/server/HttpInput.java

@@ -414,6 +414,52 @@ public class HttpInput extends ServletInputStream implements Runnable
             " eof=" + _consumedEof;
     }
 
+    /**
+     * <p>{@link Content} interceptor that can be registered using {@link #setInterceptor(Interceptor)} or
+     * {@link #addInterceptor(Interceptor)}.
+     * When {@link Content} instances are generated, they are passed to the registered interceptor (if any)
+     * that is then responsible for providing the actual content that is consumed by {@link #read(byte[], int, int)} and its
+     * sibling methods.</p>
+     * <p>A minimal implementation could be as simple as:
+     * <pre>
+     * public HttpInput.Content readFrom(HttpInput.Content content)
+     * {
+     *     LOGGER.debug("read content: {}", asString(content));
+     *     return content;
+     * }
+     * </pre>
+     * which would not do anything with the content besides logging it. A more involved implementation could look like the
+     * following:
+     * <pre>
+     * public HttpInput.Content readFrom(HttpInput.Content content)
+     * {
+     *     if (content.hasContent())
+     *         this.processedContent = processContent(content.getByteBuffer());
+     *     if (content.isEof())
+     *         disposeResources();
+     *     return content.isSpecial() ? content : this.processedContent;
+     * }
+     * </pre>
+     * Implementors of this interface must keep the following in mind:
+     * <ul>
+     *     <li>Calling {@link Content#getByteBuffer()} when {@link Content#isSpecial()} returns <code>true</code> throws
+     *     {@link IllegalStateException}.</li>
+     *     <li>A {@link Content} can both be non-special and have {@link Content#isEof()} return <code>true</code>.</li>
+     *     <li>{@link Content} extends {@link Callback} to manage the lifecycle of the contained byte buffer. The code calling
+     *     {@link #readFrom(Content)} is responsible for managing the lifecycle of both the passed and the returned content
+     *     instances, once {@link ByteBuffer#hasRemaining()} returns <code>false</code> {@link HttpInput} will make sure
+     *     {@link Callback#succeeded()} is called, or {@link Callback#failed(Throwable)} if an error occurs.</li>
+     *     <li>After {@link #readFrom(Content)} is called for the first time, subsequent {@link #readFrom(Content)} calls will
+     *     occur only after the contained byte buffer is empty (see above) or at any time if the returned content was special.</li>
+     *     <li>Once {@link #readFrom(Content)} returned a special content, subsequent calls to {@link #readFrom(Content)} must
+     *     always return the same special content.</li>
+     *     <li>Implementations implementing both this interface and {@link Destroyable} will have their
+     *     {@link Destroyable#destroy()} method called when {@link #recycle()} is called.</li>
+     * </ul>
+     * </p>
+     * <p></p>
+     * @see org.eclipse.jetty.server.handler.gzip.GzipHttpInputInterceptor
+     */
     public interface Interceptor
     {
         /**