Fixing broken javadoc and imports

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

jetty-annotations/src/main/java/org/eclipse/jetty/annotations/AnnotationDecorator.java

@@ -61,7 +61,7 @@ public class AnnotationDecorator implements Decorator
     /**
      * @param <T>
      * @param filter
-     * @return
+     * @return the decorated filter
      * @throws ServletException
      * @see org.eclipse.jetty.servlet.ServletContextHandler.Decorator#decorateFilterInstance(javax.servlet.Filter)
      */
@@ -75,7 +75,7 @@ public class AnnotationDecorator implements Decorator
     /**
      * @param <T>
      * @param listener
-     * @return
+     * @return the decorated event listener instance
      * @throws ServletException
      * @see org.eclipse.jetty.servlet.ServletContextHandler.Decorator#decorateListenerInstance(java.util.EventListener)
      */
@@ -99,7 +99,7 @@ public class AnnotationDecorator implements Decorator
     /**
      * @param <T>
      * @param servlet
-     * @return
+     * @return the decorated servlet instance
      * @throws ServletException
      * @see org.eclipse.jetty.servlet.ServletContextHandler.Decorator#decorateServletInstance(javax.servlet.Servlet)
      */

jetty-annotations/src/main/java/org/eclipse/jetty/annotations/DeclareRolesAnnotationHandler.java

@@ -13,10 +13,6 @@
 
 package org.eclipse.jetty.annotations;
 
-import java.util.Arrays;
-import java.util.HashSet;
-import java.util.Set;
-
 import javax.servlet.Servlet;
 
 import javax.annotation.security.DeclareRoles;
@@ -35,7 +31,7 @@ public class DeclareRolesAnnotationHandler extends AbstractIntrospectableAnnotat
     protected WebAppContext _context;
     
     /**
-     * @param introspectAncestors
+     * @param context
      */
     public DeclareRolesAnnotationHandler(WebAppContext context)
     {

jetty-deploy/src/main/java/org/eclipse/jetty/deploy/ContextDeployer.java

@@ -18,6 +18,8 @@ import java.io.FilenameFilter;
 import java.util.HashMap;
 import java.util.Map;
 
+import org.eclipse.jetty.deploy.providers.ContextProvider;
+import org.eclipse.jetty.deploy.providers.ScanningAppProvider;
 import org.eclipse.jetty.server.Server;
 import org.eclipse.jetty.server.handler.ContextHandler;
 import org.eclipse.jetty.server.handler.ContextHandlerCollection;
@@ -63,10 +65,11 @@ import org.eclipse.jetty.xml.XmlConfiguration;
  * configurations to it simply by dropping different xml configuration files into the configuration directory.
  * 
  * @see DeploymentManager
- * @see MonitoredDirAppProvider
+ * @see ScanningAppProvider
  * 
  * @org.apache.xbean.XBean element="hotDeployer" description="Creates a hot deployer to watch a directory for changes at
  *                         a configurable interval."
+ * @deprecated replaced with {@link ContextProvider} from the {@link DeploymentManager}
  */
 @SuppressWarnings("unchecked")
 @Deprecated

jetty-deploy/src/main/java/org/eclipse/jetty/deploy/WebAppDeployer.java

@@ -15,6 +15,7 @@ package org.eclipse.jetty.deploy;
 
 import java.util.ArrayList;
 
+import org.eclipse.jetty.deploy.providers.ScanningAppProvider;
 import org.eclipse.jetty.server.Handler;
 import org.eclipse.jetty.server.handler.ContextHandler;
 import org.eclipse.jetty.server.handler.ContextHandlerCollection;
@@ -45,7 +46,7 @@ import org.eclipse.jetty.webapp.WebAppContext;
  * 
  * @deprecated
  * @see DeploymentManager
- * @see MonitoredDirAppProvider
+ * @see ScanningAppProvider
  * @see ContextDeployer
  */
 @SuppressWarnings("unchecked")

jetty-deploy/src/main/java/org/eclipse/jetty/deploy/providers/ContextProvider.java

@@ -2,24 +2,18 @@ package org.eclipse.jetty.deploy.providers;
 
 import java.io.File;
 import java.io.FilenameFilter;
-import java.util.HashMap;
-import java.util.Map;
 
 import org.eclipse.jetty.deploy.App;
 import org.eclipse.jetty.deploy.ConfigurationManager;
-import org.eclipse.jetty.deploy.ContextDeployer;
 import org.eclipse.jetty.deploy.util.FileID;
 import org.eclipse.jetty.server.handler.ContextHandler;
 import org.eclipse.jetty.util.resource.Resource;
 import org.eclipse.jetty.xml.XmlConfiguration;
 
-
-/* ------------------------------------------------------------ */
 /** Context directory App Provider.
- * <p>This specialization of {@link MonitoredDirAppProvider} is the
+ * <p>This specialization of {@link ScanningAppProvider} is the
- * replacement for {@link ContextDeployer} and it will scan a directory
+ * replacement for the old (and deprecated) <code>org.eclipse.jetty.deploy.ContextDeployer</code> and it will scan a directory
  * only for context.xml files.
- * @see ContextDeployer
  */
 public class ContextProvider extends ScanningAppProvider
 {

jetty-deploy/src/main/java/org/eclipse/jetty/deploy/providers/WebAppProvider.java

@@ -6,25 +6,21 @@ import java.io.IOException;
 import java.net.MalformedURLException;
 
 import org.eclipse.jetty.deploy.App;
-import org.eclipse.jetty.deploy.WebAppDeployer;
 import org.eclipse.jetty.deploy.util.FileID;
 import org.eclipse.jetty.server.handler.ContextHandler;
 import org.eclipse.jetty.util.URIUtil;
 import org.eclipse.jetty.util.resource.Resource;
 import org.eclipse.jetty.webapp.WebAppContext;
-import org.eclipse.jetty.webapp.WebInfConfiguration;
-
 
 /* ------------------------------------------------------------ */
 /** Context directory App Provider.
- * <p>This specialization of {@link MonitoredDirAppProvider} is the
+ * <p>This specialization of {@link ScanningAppProvider} is the
- * replacement for {@link WebAppDeployer} and it will scan a directory
+ * replacement for old (and deprecated) <code>org.eclipse.jetty.deploy.WebAppDeployer</code> and it will scan a directory
  * only for war files or directories files.</p>
  * <p>
  * Webapps with names root or starting with root- are deployed at /.
  * If the name is in the format root-hostname, then the webapp is deployed
  * at / in the virtual host hostname.
- * @see WebAppDeployer
  */
 public class WebAppProvider extends ScanningAppProvider
 {

jetty-deploy/src/test/java/org/eclipse/jetty/deploy/providers/MonitoredDirAppProviderRuntimeUpdatesTest.java

@@ -24,7 +24,7 @@ import org.junit.Test;
 
 /**
  * Similar in scope to {@link MonitoredDirAppProviderStartupTest}, except is concerned with the modification of existing
- * deployed webapps due to incoming changes identified by the {@link MonitoredDirAppProvider}.
+ * deployed webapps due to incoming changes identified by the {@link ScanningAppProvider}.
  */
 public class MonitoredDirAppProviderRuntimeUpdatesTest
 {

jetty-deploy/src/test/java/org/eclipse/jetty/deploy/providers/MonitoredDirAppProviderStartupTest.java

@@ -16,13 +16,12 @@
 package org.eclipse.jetty.deploy.providers;
 
 import org.eclipse.jetty.deploy.test.XmlConfiguredJetty;
-import org.eclipse.jetty.util.log.Log;
 import org.junit.AfterClass;
 import org.junit.BeforeClass;
 import org.junit.Test;
 
 /**
- * Tests {@link MonitoredDirAppProvider} as it starts up for the first time.
+ * Tests {@link ScanningAppProvider} as it starts up for the first time.
  */
 public class MonitoredDirAppProviderStartupTest
 {

jetty-io/src/main/java/org/eclipse/jetty/io/nio/SelectorManager.java

@@ -136,7 +136,6 @@ public abstract class SelectorManager extends AbstractLifeCycle
     /* ------------------------------------------------------------ */
     /** Register a channel
      * @param channel
-     * @param att Attached Object
      */
     public void register(SocketChannel channel)
     {

jetty-jndi/src/main/java/org/eclipse/jetty/jndi/NamingContext.java

@@ -88,10 +88,6 @@ public class NamingContext implements Context, Cloneable, Dumpable
     /*------------------------------------------------*/    
     /**
      * Naming Context Listener.
-     * <p>
-     * If the env property {@link NamingContext#LISTENERS_PROPERTY} is set to 
-     * a collection of Listeners, then the listener will be called as Bindings 
-     * are added and removed from the context.
      */
     public interface Listener
     {

jetty-plus/src/main/java/org/eclipse/jetty/plus/jndi/NamingEntry.java

@@ -68,7 +68,6 @@ public abstract class NamingEntry
      * be linked to the webapp's env-entry, resource-ref etc entries.
      * 
      * @param jndiName the name of the object which will eventually be in java:comp/env
-     * @param object the object to be bound
      * @throws NamingException
      */
     protected NamingEntry (String jndiName)

jetty-plus/src/main/java/org/eclipse/jetty/plus/webapp/PlusDescriptorProcessor.java

@@ -95,7 +95,7 @@ public class PlusDescriptorProcessor extends IterativeDescriptorProcessor
 
     
     /** 
-     * @see org.eclipse.jetty.webapp.IterativeDescriptorProcessor#end(org.eclipse.jetty.webapp.Descriptor, WebAppContext)
+     * {@inheritDoc}
      */
     public void end(WebAppContext context,Descriptor descriptor)
     {
@@ -703,7 +703,6 @@ public class PlusDescriptorProcessor extends IterativeDescriptorProcessor
      * @param node
      * @param jndiName
      * @param valueClass
-     * @return 
      */
     public void addInjections (WebAppContext context, Descriptor descriptor, XmlParser.Node node, String jndiName, Class<?> valueClass)
     {
@@ -756,7 +755,6 @@ public class PlusDescriptorProcessor extends IterativeDescriptorProcessor
 
     
     /** 
-     * @see org.eclipse.jetty.plus.webapp.AbstractConfiguration#bindEnvEntry(java.lang.String, java.lang.String)
      * @param name
      * @param value
      * @throws Exception
@@ -797,7 +795,6 @@ public class PlusDescriptorProcessor extends IterativeDescriptorProcessor
      * If a resource reference with the same name is in a jetty-env.xml
      * file, it will already have been bound.
      * 
-     * @see org.eclipse.jetty.plus.webapp.AbstractConfiguration#bindResourceRef(java.lang.String)
      * @param name
      * @throws Exception
      */
@@ -808,7 +805,6 @@ public class PlusDescriptorProcessor extends IterativeDescriptorProcessor
     }
 
     /** 
-     * @see org.eclipse.jetty.plus.webapp.AbstractConfiguration#bindResourceEnvRef(java.lang.String)
      * @param name
      * @throws Exception
      */

jetty-policy/src/main/java/org/eclipse/jetty/policy/JettyPolicy.java

@@ -391,7 +391,7 @@ public class JettyPolicy extends Policy
     
     /**
      * returns the known policy files that are being tracked by this instance of JettyPolicy
-     * @return
+     * @return set of known policy files
      */
     public Set<String> getKnownPolicyFiles()
     {

jetty-security/src/main/java/org/eclipse/jetty/security/ConstraintSecurityHandler.java

@@ -77,7 +77,7 @@ public class ConstraintSecurityHandler extends SecurityHandler implements Constr
      * 
      * @param strict the strict to set
      * @see #setRoles(Set)
-     * @see #setConstraintMappings(ConstraintMapping[], Set)
+     * @see #setConstraintMappings(List, Set)
      */
     public void setStrict(boolean strict)
     {
@@ -121,9 +121,9 @@ public class ConstraintSecurityHandler extends SecurityHandler implements Constr
      *            The contraintMappings to set as array, from which the set of known roles
      *            is determined.  Needed to retain API compatibility for 7.x
      */
-    public void setConstraintMappings( ConstraintMapping[] contraintMappings )
+    public void setConstraintMappings( ConstraintMapping[] constraintMappings )
     {
-        setConstraintMappings( Arrays.asList(contraintMappings), null);
+        setConstraintMappings( Arrays.asList(constraintMappings), null);
     }
     
     /* ------------------------------------------------------------ */
@@ -163,7 +163,7 @@ public class ConstraintSecurityHandler extends SecurityHandler implements Constr
     /**
      * Set the known roles.
      * This may be overridden by a subsequent call to {@link #setConstraintMappings(ConstraintMapping[])} or
-     * {@link #setConstraintMappings(ConstraintMapping[], Set)}.
+     * {@link #setConstraintMappings(List, Set)}.
      * @see #setStrict(boolean)
      * @param roles The known roles (or null to determine them from the mappings)
      */

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

@@ -674,7 +674,7 @@ public abstract class AbstractConnector extends HttpBuffers implements Connector
      * @set {@link #setForwardedForHeader(String)}
      * @set {@link #setForwardedHostHeader(String)}
      * @set {@link #setForwardedProtoHeader(String)}
-     * @set {@link #setForwardedServerHeader(String))}
+     * @set {@link #setForwardedServerHeader(String)}
      */
     public void setForwarded(boolean check)
     {

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

@@ -65,7 +65,6 @@ public class ResourceCache
     /* ------------------------------------------------------------ */
     /** Constructor.
      * @param mimeTypes Mimetype to use for meta data
-     * @param fileMappedBuffers True if file mapped buffers can be used for DirectBuffers
      */
     public ResourceCache(ResourceCache parent, ResourceFactory factory, MimeTypes mimeTypes)
     {

jetty-server/src/main/java/org/eclipse/jetty/server/handler/ConnectHandler.java

@@ -37,8 +37,6 @@ import org.eclipse.jetty.util.thread.ThreadPool;
  * <p>Implementation of a tunneling proxy that supports HTTP CONNECT.</p>
  * <p>To work as CONNECT proxy, objects of this class must be instantiated using the no-arguments
  * constructor, since the remote server information will be present in the CONNECT URI.</p>
- *
- * @see org.eclipse.jetty.servlets.ProxyServlet
  */
 public class ConnectHandler extends HandlerWrapper
 {
@@ -786,7 +784,7 @@ public class ConnectHandler extends HandlerWrapper
      * the content of the specified host map
      * 
      * @param entries new entries
-     * @param patternMap target host map
+     * @param hostMap target host map
      */
     protected void set(String[] entries,  HostMap<String> hostMap)
     {

jetty-server/src/main/java/org/eclipse/jetty/server/session/AbstractSessionManager.java

@@ -532,7 +532,7 @@ public abstract class AbstractSessionManager extends AbstractLifeCycle implement
      * A secure cookie will only be sent by a browser on a secure (https) connection to 
      * avoid the concern of cookies being intercepted on non secure channels.
      * For the cookie to be issued as secure, the {@link ServletRequest#isSecure()} method must return true.
-     * If SSL offload is used, then the {@link AbstractConnector#customize(org.eclipse.jetty.io.EndPoint, Request)
+     * If SSL offload is used, then the {@link AbstractConnector#customize(org.eclipse.jetty.io.EndPoint, Request)}
      * method can be used to force the request to be https, or the {@link AbstractConnector#setForwarded(boolean)}
      * can be set to true, so that the X-Forwarded-Proto header is respected.
      * <p>

jetty-servlet/src/main/java/org/eclipse/jetty/servlet/ErrorPageErrorHandler.java

@@ -180,7 +180,7 @@ public class ErrorPageErrorHandler extends ErrorHandler
     /** Add Error Page mapping for an exception class
      * This method is called as a result of an exception-type element in a web.xml file
      * or may be called directly
-     * @param exception The exception
+     * @param exceptionClassName The exception
      * @param uri The URI of the error page.
      */
     public void addErrorPage(String exceptionClassName,String uri)

jetty-servlet/src/main/java/org/eclipse/jetty/servlet/ServletContextHandler.java

@@ -464,7 +464,7 @@ public class ServletContextHandler extends ContextHandler
         
         /* ------------------------------------------------------------ */
         /**
-         * @see javax.servlet.ServletContext#addFilter(java.lang.String, java.lang.Class)
+         * @since servlet-api-3.0
          */
         public FilterRegistration.Dynamic addFilter(String filterName, Class<? extends Filter> filterClass)
         {
@@ -481,7 +481,7 @@ public class ServletContextHandler extends ContextHandler
 
         /* ------------------------------------------------------------ */
         /**
-         * @see javax.servlet.ServletContext#addFilter(java.lang.String, java.lang.String)
+         * @since servlet-api-3.0
          */
         public FilterRegistration.Dynamic addFilter(String filterName, String className)
         {
@@ -499,7 +499,7 @@ public class ServletContextHandler extends ContextHandler
 
         /* ------------------------------------------------------------ */
         /**
-         * @see javax.servlet.ServletContext#addFilter(java.lang.String, javax.servlet.Filter)
+         * @since servlet-api-3.0
          */
         public FilterRegistration.Dynamic addFilter(String filterName, Filter filter)
         {
@@ -516,7 +516,7 @@ public class ServletContextHandler extends ContextHandler
         
         /* ------------------------------------------------------------ */
         /**
-         * @see javax.servlet.ServletContext#addServlet(java.lang.String, java.lang.Class)
+         * @since servlet-api-3.0
          */
         public ServletRegistration.Dynamic addServlet(String servletName, Class<? extends Servlet> servletClass)
         {
@@ -533,7 +533,7 @@ public class ServletContextHandler extends ContextHandler
 
         /* ------------------------------------------------------------ */
         /**
-         * @see javax.servlet.ServletContext#addServlet(java.lang.String, java.lang.String)
+         * @since servlet-api-3.0
          */
         public ServletRegistration.Dynamic addServlet(String servletName, String className)
         {
@@ -549,6 +549,9 @@ public class ServletContextHandler extends ContextHandler
         }
 
         /* ------------------------------------------------------------ */
+        /**
+         * @since servlet-api-3.0
+         */
         public ServletRegistration.Dynamic addServlet(String servletName, Servlet servlet)
         {
             if (!isStarting())

jetty-servlet/src/main/java/org/eclipse/jetty/servlet/ServletHolder.java

@@ -732,7 +732,7 @@ public class ServletHolder extends Holder<Servlet> implements UserIdentity.Scope
     
     /* ------------------------------------------------------------ */
     /**
-     * @return
+     * @return the newly created Servlet instance
      * @throws ServletException
      * @throws IllegalAccessException
      * @throws InstantiationException

jetty-servlets/src/main/java/org/eclipse/jetty/servlets/QoSFilter.java

@@ -331,7 +331,7 @@ public class QoSFilter implements Filter
      * Set the maximum number of requests allowed to be processed
      * at the same time.
      * 
-     * @param passes the _passes to set
+     * @param value the number of requests
      */
     public void setMaxRequests(int value)
     {

jetty-util/src/main/java/org/eclipse/jetty/util/Scanner.java

@@ -146,7 +146,7 @@ public class Scanner
     /* ------------------------------------------------------------ */
     /**
      * @param recursive True if scanning is recursive
-     * @see  #setScanDepth()
+     * @see  #setScanDepth(int)
      */
     public void setRecursive (boolean recursive)
     {

jetty-webapp/src/main/java/org/eclipse/jetty/webapp/IterativeDescriptorProcessor.java

@@ -46,7 +46,7 @@ public abstract class IterativeDescriptorProcessor implements DescriptorProcesso
 
     
     /** 
-     * @see org.eclipse.jetty.webapp.DescriptorProcessor#process(org.eclipse.jetty.webapp.Descriptor)
+     * {@inheritDoc}
      */
     public void process(WebAppContext context, Descriptor descriptor)
     throws Exception

jetty-webapp/src/main/java/org/eclipse/jetty/webapp/Ordering.java

@@ -346,7 +346,7 @@ public interface Ordering
         * @param list
         * @param fragNameA
         * @param fragNameB
-        * @return
+        * @return true if frament name A is before fragment name B 
         */
        protected boolean isBefore (List<Resource> list, String fragNameA, String fragNameB)
        {
@@ -393,7 +393,7 @@ public interface Ordering
         * @param list
         * @param fragNameA
         * @param fragNameB
-        * @return
+        * @return true if fragment name A is after fragment name B
         */
        protected boolean isAfter(List<Resource> list, String fragNameA, String fragNameB)
        {

jetty-webapp/src/main/java/org/eclipse/jetty/webapp/StandardDescriptorProcessor.java

@@ -89,7 +89,7 @@ public class StandardDescriptorProcessor extends IterativeDescriptorProcessor
     
     
     /**
-     * @see org.eclipse.jetty.webapp.IterativeDescriptorProcessor#start()
+     * {@inheritDoc}
      */
     public void start(WebAppContext context, Descriptor descriptor)
     { 
@@ -98,7 +98,7 @@ public class StandardDescriptorProcessor extends IterativeDescriptorProcessor
     
     
     /** 
-     * @see org.eclipse.jetty.webapp.IterativeDescriptorProcessor#end()
+     * {@inheritDoc}
      */
     public void end(WebAppContext context, Descriptor descriptor)
     {
@@ -1395,7 +1395,7 @@ public class StandardDescriptorProcessor extends IterativeDescriptorProcessor
     /**
      * @param context
      * @param clazz
-     * @return
+     * @return the new event listener
      * @throws ServletException
      * @throws InstantiationException
      * @throws IllegalAccessException
@@ -1419,7 +1419,7 @@ public class StandardDescriptorProcessor extends IterativeDescriptorProcessor
     
     /**
      * @param p
-     * @return
+     * @return the normalized pattern
      */
     protected String normalizePattern(String p)
     {
@@ -1432,7 +1432,7 @@ public class StandardDescriptorProcessor extends IterativeDescriptorProcessor
      * above the webapp's classloader.
      * 
      * This is primarily used for jasper.
-     * @return
+     * @return the system class path
      */
     protected String getSystemClassPath(WebAppContext context)
     {

jetty-webapp/src/main/java/org/eclipse/jetty/webapp/WebAppContext.java

@@ -362,7 +362,7 @@ public class WebAppContext extends ServletContextHandler implements WebAppClassL
      * specifically:<ul>
      * <li>Instantiate the {@link Configuration} instances with a call to {@link #loadConfigurations()}.
      * <li>Setup the default System classes by calling {@link #loadSystemClasses()}
-     * <li>Setup the default Server classes by calling {@link #loadServerClasses()}
+     * <li>Setup the default Server classes by calling <code>loadServerClasses()</code>
      * <li>Instantiates a classload (if one is not already set)
      * <li>Calls the {@link Configuration#preConfigure(WebAppContext)} method of all 
      * Configuration instances.
@@ -851,7 +851,7 @@ public class WebAppContext extends ServletContextHandler implements WebAppClassL
     /* ------------------------------------------------------------ */
     /**
      * The override descriptor is a web.xml format file that is applied to the context after the standard WEB-INF/web.xml
-     * @param overrideDescriptor The overrideDescriptors (file or URL) to set.
+     * @param overrideDescriptors The overrideDescriptors (file or URL) to set.
      */
     public void setOverrideDescriptors(List<String> overrideDescriptors)
     {

jetty-websocket/src/main/java/org/eclipse/jetty/websocket/WebSocketFactory.java

@@ -90,7 +90,6 @@ public class WebSocketFactory
      * @param websocket The websocket handler implementation to use
      * @param origin The origin of the websocket connection
      * @param subprotocol The protocol
-     * @throws UpgradeConnectionException Thrown to upgrade the connection
      * @throws IOException
      */
     public void upgrade(HttpServletRequest request,HttpServletResponse response, WebSocket websocket, String origin, String subprotocol)

jetty-websocket/src/main/java/org/eclipse/jetty/websocket/WebSocketParserD00.java

@@ -72,7 +72,7 @@ public class WebSocketParserD00 implements WebSocketParser
 
     /* ------------------------------------------------------------ */
     /** Parse to next event.
-     * Parse to the next {@link FrameHandler} event or until no more data is
+     * Parse to the next {@link WebSocketParser.FrameHandler} event or until no more data is
      * available. Fill data from the {@link EndPoint} only as necessary.
      * @return An indication of progress or otherwise. -1 indicates EOF, 0 indicates
      * that no bytes were read and no messages parsed. A positive number indicates either

jetty-websocket/src/main/java/org/eclipse/jetty/websocket/WebSocketParserD01.java

@@ -88,7 +88,7 @@ public class WebSocketParserD01 implements WebSocketParser
 
     /* ------------------------------------------------------------ */
     /** Parse to next event.
-     * Parse to the next {@link FrameHandler} event or until no more data is
+     * Parse to the next {@link WebSocketParser.FrameHandler} event or until no more data is
      * available. Fill data from the {@link EndPoint} only as necessary.
      * @return An indication of progress or otherwise. -1 indicates EOF, 0 indicates
      * that no bytes were read and no messages parsed. A positive number indicates either