464727 - Update Javadoc for Java 8 DocLint

+ Fixing javadoc in jetty-servlet

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

@@ -38,7 +38,7 @@ import org.eclipse.jetty.util.log.Logger;
  * Base class for all servlet-related classes that may be lazily instantiated  (eg servlet, filter, 
  * listener), and/or require metadata to be held regarding their origin 
  * (web.xml, annotation, programmatic api etc).
- * 
+ * @param <T> the type of holder
  */
 public abstract class BaseHolder<T> extends AbstractLifeCycle implements Dumpable
 {
@@ -68,7 +68,7 @@ public abstract class BaseHolder<T> extends AbstractLifeCycle implements Dumpabl
     /* ------------------------------------------------------------ */
     /**
      * Do any setup necessary after starting
-     * @throws Exception
+     * @throws Exception if unable to initialize
      */
     public void initialize()
     throws Exception

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

@@ -69,16 +69,15 @@ import org.eclipse.jetty.util.resource.ResourceCollection;
 import org.eclipse.jetty.util.resource.ResourceFactory;
 
 
-
-/* ------------------------------------------------------------ */
-/** The default servlet.
- * 
+/** 
+ * The default servlet.
+ * <p>
  * This servlet, normally mapped to /, provides the handling for static
  * content, OPTION and TRACE methods for the context.
  * The following initParameters are supported, these can be set either
  * on the servlet itself or as ServletContext initParameters with a prefix
  * of org.eclipse.jetty.servlet.Default. :
- * <PRE>
+ * <pre>
  *  acceptRanges      If true, range requests and responses are
  *                    supported
  *
@@ -137,10 +136,7 @@ import org.eclipse.jetty.util.resource.ResourceFactory;
  *                    Other file extensions that signify that a file is gzip compressed. Eg ".svgz"
  *
  *
- * </PRE>
- *
- *
- *
+ * </pre>
  *
  */
 public class DefaultServlet extends HttpServlet implements ResourceFactory
@@ -616,10 +612,6 @@ public class DefaultServlet extends HttpServlet implements ResourceFactory
 
     }
 
-    /**
-     * @param resource
-     * @return
-     */
     protected boolean isGzippedContent(String path)
     {
         if (path == null) return false;

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

@@ -37,10 +37,6 @@ import org.eclipse.jetty.util.component.Dumpable;
 import org.eclipse.jetty.util.log.Log;
 import org.eclipse.jetty.util.log.Logger;
 
-/* --------------------------------------------------------------------- */
-/**
- *
- */
 public class FilterHolder extends Holder<Filter>
 {
     private static final Logger LOG = Log.getLogger(FilterHolder.class);
@@ -61,6 +57,7 @@ public class FilterHolder extends Holder<Filter>
 
     /* ---------------------------------------------------------------- */
     /** Constructor
+     * @param source the holder source
      */
     public FilterHolder(Holder.Source source)
     {
@@ -69,6 +66,7 @@ public class FilterHolder extends Holder<Filter>
 
     /* ---------------------------------------------------------------- */
     /** Constructor
+     * @param filter the filter class
      */
     public FilterHolder(Class<? extends Filter> filter)
     {
@@ -78,6 +76,7 @@ public class FilterHolder extends Holder<Filter>
 
     /* ---------------------------------------------------------------- */
     /** Constructor for existing filter.
+     * @param filter the filter
      */
     public FilterHolder(Filter filter)
     {

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

@@ -45,6 +45,8 @@ public class FilterMapping implements Dumpable
 
     /* ------------------------------------------------------------ */
     /** Dispatch type from name
+     * @param type the type name
+     * @return the dispatcher type
      */
     public static DispatcherType dispatch(String type)
     {
@@ -63,6 +65,8 @@ public class FilterMapping implements Dumpable
 
     /* ------------------------------------------------------------ */
     /** Dispatch type from name
+     * @param type the dispatcher type
+     * @return the type constant ({@link #REQUEST}, {@link #ASYNC}, {@link #FORWARD}, {@link #INCLUDE}, or {@link #ERROR})
      */
     public static int dispatch(DispatcherType type)
     {

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

@@ -42,7 +42,7 @@ import org.eclipse.jetty.util.log.Logger;
  * 
  * Specialization of AbstractHolder for servlet-related classes that 
  * have init-params etc
- * 
+ * @param <T> the type of holder
  */
 @ManagedObject("Holder - a container for servlets and the like")
 public class Holder<T> extends BaseHolder<T>

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

@@ -66,12 +66,13 @@ import org.eclipse.jetty.util.annotation.ManagedAttribute;
 import org.eclipse.jetty.util.annotation.ManagedObject;
 import org.eclipse.jetty.util.component.LifeCycle;
 
-
-/* ------------------------------------------------------------ */
-/** Servlet Context.
+/** 
+ * Servlet Context.
+ * <p>
  * This extension to the ContextHandler allows for
  * simple construction of a context with ServletHandler and optionally
- * session and security handlers, et.<pre>
+ * session and security handlers, et.
+ * <pre>
  *   new ServletContext("/context",Context.SESSIONS|Context.NO_SECURITY);
  * </pre>
  * <p>
@@ -394,7 +395,10 @@ public class ServletContextHandler extends ContextHandler
     }
     
     /* ------------------------------------------------------------ */
-    /** conveniance method to add a servlet.
+    /** Convenience method to add a servlet.
+     * @param className the servlet class name
+     * @param pathSpec the path spec to map servlet to
+     * @return the ServletHolder for the added servlet
      */
     public ServletHolder addServlet(String className,String pathSpec)
     {
@@ -402,7 +406,10 @@ public class ServletContextHandler extends ContextHandler
     }
 
     /* ------------------------------------------------------------ */
-    /** conveniance method to add a servlet.
+    /** Convenience method to add a servlet.
+     * @param servlet the servlet class
+     * @param pathSpec the path spec to map servlet to
+     * @return the ServletHolder for the added servlet
      */
     public ServletHolder addServlet(Class<? extends Servlet> servlet,String pathSpec)
     {
@@ -410,7 +417,9 @@ public class ServletContextHandler extends ContextHandler
     }
 
     /* ------------------------------------------------------------ */
-    /** conveniance method to add a servlet.
+    /** Convenience method to add a servlet.
+     * @param servlet the servlet holder
+     * @param pathSpec the path spec
      */
     public void addServlet(ServletHolder servlet,String pathSpec)
     {
@@ -418,7 +427,10 @@ public class ServletContextHandler extends ContextHandler
     }
 
     /* ------------------------------------------------------------ */
-    /** conveniance method to add a filter
+    /** Convenience method to add a filter
+     * @param holder the filter holder
+     * @param pathSpec the path spec
+     * @param dispatches the dispatcher types for this filter
      */
     public void addFilter(FilterHolder holder,String pathSpec,EnumSet<DispatcherType> dispatches)
     {
@@ -426,7 +438,11 @@ public class ServletContextHandler extends ContextHandler
     }
 
     /* ------------------------------------------------------------ */
-    /** convenience method to add a filter
+    /** Convenience method to add a filter
+     * @param filterClass the filter class
+     * @param pathSpec the path spec
+     * @param dispatches the dispatcher types for this filter
+     * @return the FilterHolder that was created
      */
     public FilterHolder addFilter(Class<? extends Filter> filterClass,String pathSpec,EnumSet<DispatcherType> dispatches)
     {
@@ -434,7 +450,11 @@ public class ServletContextHandler extends ContextHandler
     }
 
     /* ------------------------------------------------------------ */
-    /** convenience method to add a filter
+    /** Convenience method to add a filter
+     * @param filterClass the filter class name 
+     * @param pathSpec the path spec
+     * @param dispatches the dispatcher types for this filter
+     * @return the FilterHolder that was created
      */
     public FilterHolder addFilter(String filterClass,String pathSpec,EnumSet<DispatcherType> dispatches)
     {

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

@@ -76,8 +76,9 @@ import org.eclipse.jetty.util.component.LifeCycle;
 import org.eclipse.jetty.util.log.Log;
 import org.eclipse.jetty.util.log.Logger;
 
-/* --------------------------------------------------------------------- */
-/** Servlet HttpHandler.
+/** 
+ * Servlet HttpHandler.
+ * <p>
  * This handler maps requests to servlets that implement the
  * javax.servlet.http.HttpServlet API.
  * <P>
@@ -88,10 +89,6 @@ import org.eclipse.jetty.util.log.Logger;
  * Unless run as part of a {@link ServletContextHandler} or derivative, the {@link #initialize()}
  * method must be called manually after start().
  */
-
-/* ------------------------------------------------------------ */
-/**
- */
 @ManagedObject("Servlet Handler")
 public class ServletHandler extends ScopedHandler
 {
@@ -409,8 +406,8 @@ public class ServletHandler extends ScopedHandler
     /**
      * Get the ServletMapping matching the path
      * 
-     * @param pathSpec
-     * @return
+     * @param pathSpec the path spec
+     * @return the servlet mapping for the path spec (or null if not found)
      */
     public ServletMapping getServletMapping(String pathSpec)
     {
@@ -834,6 +831,7 @@ public class ServletHandler extends ScopedHandler
 
     /* ------------------------------------------------------------ */
     /** Initialize filters and load-on-startup servlets.
+     * @throws Exception if unable to initialize
      */
     public void initialize()
         throws Exception
@@ -908,7 +906,7 @@ public class ServletHandler extends ScopedHandler
     
     /* ------------------------------------------------------------ */
     /** Add a holder for a listener
-     * @param filter
+     * @param listener the listener for the holder
      */
     public void addListener (ListenerHolder listener)
     {
@@ -942,7 +940,9 @@ public class ServletHandler extends ScopedHandler
 
     /* ------------------------------------------------------------ */
     /**
-     * see also newServletHolder(Class)
+     * Add a new servlet holder
+     * @param source the holder source
+     * @return the servlet holder
      */
     public ServletHolder newServletHolder(Holder.Source source)
     {
@@ -951,6 +951,8 @@ public class ServletHandler extends ScopedHandler
 
     /* ------------------------------------------------------------ */
     /** Convenience method to add a servlet.
+     * @param className the class name
+     * @param pathSpec the path spec
      * @return The servlet holder.
      */
     public ServletHolder addServletWithMapping (String className,String pathSpec)
@@ -962,7 +964,9 @@ public class ServletHandler extends ScopedHandler
     }
 
     /* ------------------------------------------------------------ */
-    /** conveniance method to add a servlet.
+    /** Convenience method to add a servlet.
+     * @param servlet the servlet class
+     * @param pathSpec the path spec
      * @return The servlet holder.
      */
     public ServletHolder addServletWithMapping (Class<? extends Servlet> servlet,String pathSpec)
@@ -975,7 +979,7 @@ public class ServletHandler extends ScopedHandler
     }
 
     /* ------------------------------------------------------------ */
-    /** conveniance method to add a servlet.
+    /** Convenience method to add a servlet.
      * @param servlet servlet holder to add
      * @param pathSpec servlet mappings for the servletHolder
      */
@@ -1005,8 +1009,9 @@ public class ServletHandler extends ScopedHandler
 
 
     /* ------------------------------------------------------------ */
-    /**Convenience method to add a pre-constructed ServletHolder.
-     * @param holder
+    /**
+     * Convenience method to add a pre-constructed ServletHolder.
+     * @param holder the servlet holder
      */
     public void addServlet(ServletHolder holder)
     {
@@ -1014,8 +1019,9 @@ public class ServletHandler extends ScopedHandler
     }
 
     /* ------------------------------------------------------------ */
-    /** Convenience method to add a pre-constructed ServletMapping.
-     * @param mapping
+    /** 
+     * Convenience method to add a pre-constructed ServletMapping.
+     * @param mapping the servlet mapping
      */
     public void addServletMapping (ServletMapping mapping)
     {
@@ -1181,13 +1187,15 @@ public class ServletHandler extends ScopedHandler
     }
 
     /* ------------------------------------------------------------ */
-    /** Convenience method to add a filter with a mapping
-     * @param className
-     * @param pathSpec
-     * @param dispatches
+    /** 
+     * Convenience method to add a filter with a mapping
+     * @param className the filter class name
+     * @param pathSpec the path spec
+     * @param dispatches the dispatcher types for this filter
      * @return the filter holder created
      * @deprecated use {@link #addFilterWithMapping(Class, String, EnumSet)} instead
      */
+    @Deprecated
     public FilterHolder addFilter (String className,String pathSpec,EnumSet<DispatcherType> dispatches)
     {
         return addFilterWithMapping(className, pathSpec, dispatches);
@@ -1195,9 +1203,9 @@ public class ServletHandler extends ScopedHandler
 
     /* ------------------------------------------------------------ */
     /**
-     * convenience method to add a filter and mapping
-     * @param filter
-     * @param filterMapping
+     * Convenience method to add a filter and mapping
+     * @param filter the filter holder
+     * @param filterMapping the filter mapping
      */
     public void addFilter (FilterHolder filter, FilterMapping filterMapping)
     {
@@ -1208,8 +1216,9 @@ public class ServletHandler extends ScopedHandler
     }
 
     /* ------------------------------------------------------------ */
-    /** Convenience method to add a preconstructed FilterHolder
-     * @param filter
+    /** 
+     * Convenience method to add a preconstructed FilterHolder
+     * @param filter the filter holder
      */
     public void addFilter (FilterHolder filter)
     {
@@ -1218,8 +1227,9 @@ public class ServletHandler extends ScopedHandler
     }
 
     /* ------------------------------------------------------------ */
-    /** Convenience method to add a preconstructed FilterMapping
-     * @param mapping
+    /** 
+     * Convenience method to add a preconstructed FilterMapping
+     * @param mapping the filter mapping
      */
     public void addFilterMapping (FilterMapping mapping)
     {
@@ -1262,8 +1272,9 @@ public class ServletHandler extends ScopedHandler
     
 
     /* ------------------------------------------------------------ */
-    /** Convenience method to add a preconstructed FilterMapping
-     * @param mapping
+    /** 
+     * Convenience method to add a preconstructed FilterMapping
+     * @param mapping the filter mapping
      */
     public void prependFilterMapping (FilterMapping mapping)
     {
@@ -1321,7 +1332,7 @@ public class ServletHandler extends ScopedHandler
      * @param mapping the FilterMapping to add
      * @param pos the position in the existing arry at which to add it
      * @param before if true, insert before  pos, if false insert after it
-     * @return
+     * @return the new FilterMappings post-insert
      */
     protected FilterMapping[] insertFilterMapping (FilterMapping mapping, int pos, boolean before)
     {

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

@@ -56,17 +56,13 @@ import org.eclipse.jetty.util.annotation.ManagedObject;
 import org.eclipse.jetty.util.log.Log;
 import org.eclipse.jetty.util.log.Logger;
 
-
-
-
-/* --------------------------------------------------------------------- */
-/** Servlet Instance and Context Holder.
+/** 
+ * Servlet Instance and Context Holder.
+ * <p>
  * Holds the name, params and some state of a javax.servlet.Servlet
  * instance. It implements the ServletConfig interface.
  * This class will organise the loading of the servlet when needed or
  * requested.
- *
- *
  */
 @ManagedObject("Servlet Holder")
 public class ServletHolder extends Holder<Servlet> implements UserIdentity.Scope, Comparable<ServletHolder>
@@ -107,6 +103,7 @@ public class ServletHolder extends Holder<Servlet> implements UserIdentity.Scope
 
     /* ---------------------------------------------------------------- */
     /** Constructor .
+     * @param creator the holder source
      */
     public ServletHolder(Holder.Source creator)
     {
@@ -115,6 +112,7 @@ public class ServletHolder extends Holder<Servlet> implements UserIdentity.Scope
 
     /* ---------------------------------------------------------------- */
     /** Constructor for existing servlet.
+     * @param servlet the servlet
      */
     public ServletHolder(Servlet servlet)
     {
@@ -124,6 +122,8 @@ public class ServletHolder extends Holder<Servlet> implements UserIdentity.Scope
 
     /* ---------------------------------------------------------------- */
     /** Constructor for servlet class.
+     * @param name the name of the servlet
+     * @param servlet the servlet class
      */
     public ServletHolder(String name, Class<? extends Servlet> servlet)
     {
@@ -134,6 +134,8 @@ public class ServletHolder extends Holder<Servlet> implements UserIdentity.Scope
 
     /* ---------------------------------------------------------------- */
     /** Constructor for servlet class.
+     * @param name the servlet name
+     * @param servlet the servlet
      */
     public ServletHolder(String name, Servlet servlet)
     {
@@ -144,6 +146,7 @@ public class ServletHolder extends Holder<Servlet> implements UserIdentity.Scope
 
     /* ---------------------------------------------------------------- */
     /** Constructor for servlet class.
+     * @param servlet the servlet class
      */
     public ServletHolder(Class<? extends Servlet> servlet)
     {
@@ -181,10 +184,13 @@ public class ServletHolder extends Holder<Servlet> implements UserIdentity.Scope
     }
 
     /* ------------------------------------------------------------ */
-    /** Set the initialize order.
-     * Holders with order<0, are initialized on use. Those with
-     * order>=0 are initialized in increasing order when the handler
+    /** 
+     * Set the initialize order.
+     * <p>
+     * Holders with order&lt;0, are initialized on use. Those with
+     * order&gt;=0 are initialized in increasing order when the handler
      * is started.
+     * @param order the servlet init order
      */
     public void setInitOrder(int order)
     {
@@ -193,7 +199,8 @@ public class ServletHolder extends Holder<Servlet> implements UserIdentity.Scope
     }
 
     /* ------------------------------------------------------------ */
-    /** Comparitor by init order.
+    /** 
+     * Comparator by init order.
      */
     @Override
     public int compareTo(ServletHolder sh)
@@ -452,6 +459,7 @@ public class ServletHolder extends Holder<Servlet> implements UserIdentity.Scope
     /* ------------------------------------------------------------ */
     /** Get the servlet.
      * @return The servlet
+     * @throws ServletException if unable to init the servlet on first use
      */
     public synchronized Servlet getServlet()
         throws ServletException
@@ -482,7 +490,7 @@ public class ServletHolder extends Holder<Servlet> implements UserIdentity.Scope
     /* ------------------------------------------------------------ */
     /**
      * Check to ensure class of servlet is acceptable.
-     * @throws UnavailableException
+     * @throws UnavailableException if Servlet class is not of type {@link javax.servlet.Servlet}
      */
     public void checkServletType ()
         throws UnavailableException
@@ -644,7 +652,7 @@ public class ServletHolder extends Holder<Servlet> implements UserIdentity.Scope
 
     /* ------------------------------------------------------------ */
     /**
-     * @throws Exception
+     * @throws Exception if unable to init the JSP Servlet
      */
     protected void initJspServlet () throws Exception
     {
@@ -681,7 +689,7 @@ public class ServletHolder extends Holder<Servlet> implements UserIdentity.Scope
      * Register a ServletRequestListener that will ensure tmp multipart
      * files are deleted when the request goes out of scope.
      * 
-     * @throws Exception
+     * @throws Exception if unable to init the multipart
      */
     protected void initMultiPart () throws Exception
     {
@@ -734,11 +742,11 @@ public class ServletHolder extends Holder<Servlet> implements UserIdentity.Scope
     /**
      * Prepare to service a request.
      * 
-     * @param baseRequest
-     * @param request
-     * @param response
-     * @throws ServletException
-     * @throws UnavailableException
+     * @param baseRequest the base request
+     * @param request the request
+     * @param response the response
+     * @throws ServletException if unable to prepare the servlet
+     * @throws UnavailableException if not available
      */
     protected void prepare (Request baseRequest, ServletRequest request, ServletResponse response)
     throws ServletException, UnavailableException
@@ -766,13 +774,15 @@ public class ServletHolder extends Holder<Servlet> implements UserIdentity.Scope
     }
 
     /* ------------------------------------------------------------ */
-    /** Service a request with this servlet.
-     * @param baseRequest
-     * @param request
-     * @param response
-     * @throws ServletException
-     * @throws UnavailableException
-     * @throws IOException
+    /** 
+     * Service a request with this servlet.
+     * 
+     * @param baseRequest the base request
+     * @param request the request
+     * @param response the response
+     * @throws ServletException if unable to process the servlet
+     * @throws UnavailableException if servlet is unavailable
+     * @throws IOException if unable to process the request or response
      */
     public void handle(Request baseRequest,
                        ServletRequest request,
@@ -1170,9 +1180,9 @@ public class ServletHolder extends Holder<Servlet> implements UserIdentity.Scope
     /* ------------------------------------------------------------ */
     /**
      * @return the newly created Servlet instance
-     * @throws ServletException
-     * @throws IllegalAccessException
-     * @throws InstantiationException
+     * @throws ServletException if unable to create a new instance
+     * @throws IllegalAccessException if not allowed to create a new instance
+     * @throws InstantiationException if creating new instance resulted in error
      */
     protected Servlet newInstance() throws ServletException, IllegalAccessException, InstantiationException
     {

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

@@ -86,9 +86,6 @@ public class ServletMapping
     
     
     /* ------------------------------------------------------------ */
-    /**
-     * @return
-     */
     @ManagedAttribute(value="default", readonly=true)
     public boolean isDefault()
     {
@@ -97,9 +94,6 @@ public class ServletMapping
     
     
     /* ------------------------------------------------------------ */
-    /**
-     * @param fromDefault
-     */
     public void setDefault(boolean fromDefault)
     {
         _default = fromDefault;

jetty-servlet/src/test/java/org/eclipse/jetty/servlet/ServletContextHandlerTest.java

@@ -366,8 +366,9 @@ public class ServletContextHandlerTest
     }
     
     /**
-     * Test behavior of legacy {@link ServletContextHandler.Decorator}, with
+     * Test behavior of legacy ServletContextHandler.Decorator, with
      * new DecoratedObjectFactory class
+     * @throws Exception on test failure
      */
     @SuppressWarnings("deprecation")
     @Test
@@ -395,6 +396,7 @@ public class ServletContextHandlerTest
     /**
      * Test behavior of new {@link org.eclipse.jetty.util.Decorator}, with
      * new DecoratedObjectFactory class
+     * @throws Exception on test failure
      */
     @Test
     public void testUtilDecorator() throws Exception

jetty-servlet/src/test/java/org/eclipse/jetty/servlet/ServletRequestLogTest.java

@@ -298,6 +298,7 @@ public class ServletRequestLogTest
      * Test a RequestLogHandler at the end of a HandlerCollection.
      * This handler chain is setup to look like Jetty versions up to 9.2. 
      * Default configuration.
+     * @throws Exception on test failure
      */
     @Test(timeout=4000)
     public void testLogHandlerCollection() throws Exception
@@ -382,6 +383,7 @@ public class ServletRequestLogTest
     /**
      * Test a RequestLogHandler at the end of a HandlerCollection.
      * and also with the default ErrorHandler as server bean in place.
+     * @throws Exception on test failure
      */
     @Test(timeout=4000)
     public void testLogHandlerCollection_ErrorHandler_ServerBean() throws Exception
@@ -469,6 +471,7 @@ public class ServletRequestLogTest
     /**
      * Test a RequestLogHandler at the end of a HandlerCollection
      * using servlet specific error page mapping.
+     * @throws Exception on test failure
      */
     @Test(timeout=4000)
     public void testLogHandlerCollection_SimpleErrorPageMapping() throws Exception
@@ -558,6 +561,7 @@ public class ServletRequestLogTest
     
     /**
      * Test an alternate (proposed) setup for using RequestLogHandler in a wrapped style
+     * @throws Exception on test failure
      */
     @Test(timeout=4000)
     public void testLogHandlerWrapped() throws Exception

jetty-servlet/src/test/java/org/eclipse/jetty/servlet/ServletTester.java

@@ -228,8 +228,9 @@ public class ServletTester extends ContainerLifeCycle
 
     /** Create a port based connector.
      * This methods adds a port connector to the server
+     * @param localhost true if connector should use localhost, false for default host behavior.
      * @return A URL to access the server via the connector.
-     * @throws Exception
+     * @throws Exception on test failure
      */
     public String createConnector(boolean localhost) throws Exception
     {