Fixes #336793 (Tee data filled and flushed from endpoint).

git-svn-id: svn+ssh://dev.eclipse.org/svnroot/rt/org.eclipse.jetty/jetty/trunk@2779 7e9141cc-0065-0410-87d8-b60c137991c4

VERSION.txt

@@ -2,6 +2,7 @@ jetty-7.3.1-SNAPSHOT
  + 335329 Moved blocking timeout handling to outside try catch
  + 336691 Possible wrong length returned by ChannelEndPoint.flush() in case of RandomAccessFileBuffer
  + 336781 If xml parser is not validating, turn off external dtd resolution
+ + 336793 Tee data filled and flushed from endpoint
 
 jetty-7.3.0.v20110203 3 February 2011
  + JETTY-1259 NullPointerException in JDBCSessionIdManager when invalidating session (further update)

jetty-io/src/main/java/org/eclipse/jetty/io/NetworkTrafficListener.java

@@ -15,16 +15,64 @@ package org.eclipse.jetty.io;
 
 import java.net.Socket;
 
+/**
+ * <p>A listener for raw network traffic within Jetty.</p>
+ * <p>{@link NetworkTrafficListener}s can be installed in a
+ * {@link org.eclipse.jetty.server.nio.NetworkTrafficSelectChannelConnector},
+ * and are notified of the following network traffic events:</p>
+ * <ul>
+ * <li>Connection opened, when the server has accepted the connection from a remote client</li>
+ * <li>Incoming bytes, when the server receives bytes sent from a remote client</li>
+ * <li>Outgoing bytes, when the server sends bytes to a remote client</li>
+ * <li>Connection closed, when the server has closed the connection to a remote client</li>
+ * </ul>
+ * <p>{@link NetworkTrafficListener}s can be used to log the network traffic viewed by
+ * a Jetty server (for example logging to filesystem) for activities such as debugging
+ * or request/response cycles or for replaying request/response cycles to other servers.</p>
+ */
 public interface NetworkTrafficListener
 {
+    /**
+     * <p>Callback method invoked when a connection from a remote client has been accepted.</p>
+     * <p>The {@code socket} parameter can be used to extract socket address information of
+     * the remote client.</p>
+     *
+     * @param socket the socket associated with the remote client
+     */
     public void opened(Socket socket);
 
+    /**
+     * <p>Callback method invoked when bytes sent by a remote client arrived on the server.</p>
+     *
+     * @param socket the socket associated with the remote client
+     * @param bytes  the read-only buffer containing the incoming bytes
+     */
     public void incoming(Socket socket, Buffer bytes);
 
+    /**
+     * <p>Callback method invoked when bytes are sent to a remote client from the server.</p>
+     * <p>This method is invoked after the bytes have been actually written to the remote client.</p>
+     *
+     * @param socket the socket associated with the remote client
+     * @param bytes  the read-only buffer containing the outgoing bytes
+     */
     public void outgoing(Socket socket, Buffer bytes);
 
+    /**
+     * <p>Callback method invoked when a connection to a remote client has been closed.</p>
+     * <p>The {@code socket} parameter is already closed when this method is called, so it
+     * cannot be queried for socket address information of the remote client.<br />
+     * However, the {@code socket} parameter is the same object passed to {@link #opened(Socket)},
+     * so it is possible to map socket information in {@link #opened(Socket)} and retrieve it
+     * in this method.
+     *
+     * @param socket the (closed) socket associated with the remote client
+     */
     public void closed(Socket socket);
 
+    /**
+     * <p>A commodity class that implements {@link NetworkTrafficListener} with empty methods.</p>
+     */
     public static class Empty implements NetworkTrafficListener
     {
         public void opened(Socket socket)

jetty-server/src/main/java/org/eclipse/jetty/server/nio/NetworkTrafficSelectChannelConnector.java

@@ -16,6 +16,7 @@ package org.eclipse.jetty.server.nio;
 import java.io.IOException;
 import java.nio.channels.SelectionKey;
 import java.nio.channels.SocketChannel;
+import java.util.ConcurrentModificationException;
 import java.util.List;
 import java.util.concurrent.CopyOnWriteArrayList;
 
@@ -24,15 +25,26 @@ import org.eclipse.jetty.io.nio.NetworkTrafficSelectChannelEndPoint;
 import org.eclipse.jetty.io.nio.SelectChannelEndPoint;
 import org.eclipse.jetty.io.nio.SelectorManager;
 
+/**
+ * <p>A specialized version of {@link SelectChannelConnector} that supports {@link NetworkTrafficListener}s.</p>
+ * <p>{@link NetworkTrafficListener}s can be added and removed dynamically before and after this connector has
+ * been started without causing {@link ConcurrentModificationException}s.</p>
+ */
 public class NetworkTrafficSelectChannelConnector extends SelectChannelConnector
 {
     private final List<NetworkTrafficListener> listeners = new CopyOnWriteArrayList<NetworkTrafficListener>();
 
+    /**
+     * @param listener the listener to add
+     */
     public void addNetworkTrafficListener(NetworkTrafficListener listener)
     {
         listeners.add(listener);
     }
 
+    /**
+     * @param listener the listener to remove
+     */
     public void removeNetworkTrafficListener(NetworkTrafficListener listener)
     {
         listeners.remove(listener);