* This queue is uses a variant of the two lock queue algorithm to provide an efficient queue or list backed by a growable circular array.
- *
* Unlike {@link java.util.concurrent.ArrayBlockingQueue}, this class is able to grow and provides a blocking put call.
- *
* The queue has both a capacity (the size of the array currently allocated) and a max capacity (the maximum size that may be allocated), which defaults to
* {@link Integer#MAX_VALUE}.
+ *
*
* @param
* The element type
diff --git a/jetty-util/src/main/java/org/eclipse/jetty/util/BufferUtil.java b/jetty-util/src/main/java/org/eclipse/jetty/util/BufferUtil.java
index 377a10c2b2f..6e5c85b4e92 100644
--- a/jetty-util/src/main/java/org/eclipse/jetty/util/BufferUtil.java
+++ b/jetty-util/src/main/java/org/eclipse/jetty/util/BufferUtil.java
@@ -43,10 +43,12 @@ import org.eclipse.jetty.util.resource.Resource;
* The various ByteBuffer methods assume a mode and some of them will switch or enforce a mode:
* Allocate and clear set fill mode; flip and compact switch modes; read and write assume fill
* and flush modes. This duality can result in confusing code such as:
+ *
*
* buffer.clear();
* channel.write(buffer);
*
+ *
* Which looks as if it should write no data, but in fact writes the buffer worth of garbage.
*
*
@@ -58,13 +60,14 @@ import org.eclipse.jetty.util.resource.Resource;
*
* Thus this class provides alternate implementations of {@link #allocate(int)},
* {@link #allocateDirect(int)} and {@link #clear(ByteBuffer)} that leave the buffer
- * in flush mode. Thus the following tests will pass:
+ * in flush mode. Thus the following tests will pass:
+ *
+ *
* ByteBuffer buffer = BufferUtil.allocate(1024);
* assert(buffer.remaining()==0);
* BufferUtil.clear(buffer);
* assert(buffer.remaining()==0);
*
- *
* If the BufferUtil methods {@link #fill(ByteBuffer, byte[], int, int)},
* {@link #append(ByteBuffer, byte[], int, int)} or {@link #put(ByteBuffer, ByteBuffer)} are used,
* then the caller does not need to explicitly switch the buffer to fill mode.
@@ -72,6 +75,7 @@ import org.eclipse.jetty.util.resource.Resource;
* then they can use explicit calls of #flipToFill(ByteBuffer) and #flipToFlush(ByteBuffer, int)
* to change modes. Note because this convention attempts to avoid the copies of compact, the position
* is not set to zero on each fill cycle and so its value must be remembered:
+ *
*
* int pos = BufferUtil.flipToFill(buffer);
* try
@@ -83,8 +87,9 @@ import org.eclipse.jetty.util.resource.Resource;
* flipToFlush(buffer, pos);
* }
*
- * The flipToFill method will effectively clear the buffer if it is emtpy and will compact the buffer if there is no space.
- *
+ *
+ * The flipToFill method will effectively clear the buffer if it is empty and will compact the buffer if there is no space.
+ *
*/
public class BufferUtil
{
@@ -355,7 +360,7 @@ public class BufferUtil
* @param b bytes to append
* @param off offset into byte
* @param len length to append
- * @throws BufferOverflowException
+ * @throws BufferOverflowException if unable to append buffer due to space limits
*/
public static void append(ByteBuffer to, byte[] b, int off, int len) throws BufferOverflowException
{
@@ -392,6 +397,7 @@ public class BufferUtil
/** Appends a buffer to a buffer
* @param to Buffer is flush mode
* @param b buffer to append
+ * @return The position of the valid data before the flipped position.
*/
public static int append(ByteBuffer to, ByteBuffer b)
{
@@ -413,6 +419,7 @@ public class BufferUtil
* @param b bytes to fill
* @param off offset into byte
* @param len length to fill
+ * @return The position of the valid data before the flipped position.
*/
public static int fill(ByteBuffer to, byte[] b, int off, int len)
{
@@ -523,6 +530,7 @@ public class BufferUtil
/* ------------------------------------------------------------ */
/** Convert a partial buffer to a String.
*
+ * @param buffer the buffer to convert
* @param position The position in the buffer to start the string from
* @param length The length of the buffer
* @param charset The {@link Charset} to use to convert the bytes
@@ -560,11 +568,16 @@ public class BufferUtil
/* ------------------------------------------------------------ */
/**
- * Convert buffer to an integer. Parses up to the first non-numeric character. If no number is found an IllegalArgumentException is thrown
+ * Convert buffer to an integer. Parses up to the first non-numeric character. If no number is found an
+ * IllegalArgumentException is thrown
*
* @param buffer
* A buffer containing an integer in flush mode. The position is not changed.
- * @return an int
+ * @param position
+ * the position in the buffer to start reading from
+ * @param length
+ * the length of the buffer to use for conversion
+ * @return an int of the buffer bytes
*/
public static int toInt(ByteBuffer buffer, int position, int length)
{
@@ -952,8 +965,6 @@ public class BufferUtil
/* ------------------------------------------------------------ */
/** Convert Buffer to string ID independent of content
- * @param buffer
- * @return A string showing the buffer ID
*/
private static void idString(ByteBuffer buffer, StringBuilder out)
{
@@ -974,7 +985,7 @@ public class BufferUtil
/* ------------------------------------------------------------ */
/** Convert Buffer to string ID independent of content
- * @param buffer
+ * @param buffer the buffet to generate a string ID from
* @return A string showing the buffer ID
*/
public static String toIDString(ByteBuffer buffer)
@@ -987,7 +998,7 @@ public class BufferUtil
/* ------------------------------------------------------------ */
/** Convert Buffer to a detail debug string of pointers and content
- * @param buffer
+ * @param buffer the buffer to generate a detail string from
* @return A string showing the pointers and content of the buffer
*/
public static String toDetailString(ByteBuffer buffer)
@@ -1069,7 +1080,7 @@ public class BufferUtil
/* ------------------------------------------------------------ */
/** Convert buffer to a Hex Summary String.
- * @param buffer
+ * @param buffer the buffer to generate a hex byte summary from
* @return A string showing the escaped content of the buffer around the
* position and limit (marked with <<< and >>>)
*/
diff --git a/jetty-util/src/main/java/org/eclipse/jetty/util/CompletableCallback.java b/jetty-util/src/main/java/org/eclipse/jetty/util/CompletableCallback.java
index 1020bb6267e..156b4c20bc0 100644
--- a/jetty-util/src/main/java/org/eclipse/jetty/util/CompletableCallback.java
+++ b/jetty-util/src/main/java/org/eclipse/jetty/util/CompletableCallback.java
@@ -21,16 +21,18 @@ package org.eclipse.jetty.util;
import java.util.concurrent.atomic.AtomicReference;
/**
+ *
* A callback to be used by driver code that needs to know whether the callback has been
* succeeded or failed (that is, completed) just after the asynchronous operation or not,
* typically because further processing depends on the callback being completed.
* The driver code competes with the asynchronous operation to complete the callback.
- *
+ *
+ *
* If the callback is already completed, the driver code continues the processing,
* otherwise it suspends it. If it is suspended, the callback will be completed some time
* later, and {@link #resume()} or {@link #abort(Throwable)} will be called to allow the
* application to resume the processing.
- *
+ *
* Typical usage:
*
* CompletableCallback callback = new CompletableCallback()
@@ -124,6 +126,7 @@ public abstract class CompletableCallback implements Callback
/**
* Callback method invoked when this callback is failed.
+ * @param failure the throwable reprsenting the callback failure
*/
public abstract void abort(Throwable failure);
diff --git a/jetty-util/src/main/java/org/eclipse/jetty/util/ConcurrentArrayQueue.java b/jetty-util/src/main/java/org/eclipse/jetty/util/ConcurrentArrayQueue.java
index 6c4996b379c..9508b9724a1 100644
--- a/jetty-util/src/main/java/org/eclipse/jetty/util/ConcurrentArrayQueue.java
+++ b/jetty-util/src/main/java/org/eclipse/jetty/util/ConcurrentArrayQueue.java
@@ -34,14 +34,16 @@ import java.util.concurrent.atomic.AtomicReferenceArray;
/**
* A concurrent, unbounded implementation of {@link Queue} that uses singly-linked array blocks
* to store elements.
- *
+ *
* This class is a drop-in replacement for {@link ConcurrentLinkedQueue}, with similar performance
* but producing less garbage because arrays are used to store elements rather than nodes.
- *
+ *
+ *
* The algorithm used is a variation of the algorithm from Gidenstam, Sundell and Tsigas
* (http://www.adm.hb.se/~AGD/Presentations/CacheAwareQueue_OPODIS.pdf).
+ *
*
- * @param
+ * @param the Array entry type
*/
public class ConcurrentArrayQueue extends AbstractQueue
{
diff --git a/jetty-util/src/main/java/org/eclipse/jetty/util/DateCache.java b/jetty-util/src/main/java/org/eclipse/jetty/util/DateCache.java
index 1b5784fd0d9..04343242dd2 100644
--- a/jetty-util/src/main/java/org/eclipse/jetty/util/DateCache.java
+++ b/jetty-util/src/main/java/org/eclipse/jetty/util/DateCache.java
@@ -23,7 +23,6 @@ import java.util.Date;
import java.util.Locale;
import java.util.TimeZone;
-/* ------------------------------------------------------------ */
/** Date Format Cache.
* Computes String representations of Dates and caches
* the results so that subsequent requests within the same second
@@ -37,9 +36,7 @@ import java.util.TimeZone;
*
* If consecutive calls are frequently very different, then this
* may be a little slower than a normal DateFormat.
- *
*/
-
public class DateCache
{
public static final String DEFAULT_FORMAT="EEE MMM dd HH:mm:ss zzz yyyy";
@@ -77,6 +74,7 @@ public class DateCache
/* ------------------------------------------------------------ */
/** Constructor.
* Make a DateCache that will use the given format
+ * @param format the format to use
*/
public DateCache(String format)
{
@@ -161,7 +159,7 @@ public class DateCache
/* ------------------------------------------------------------ */
/** Format a date according to our stored formatter.
- * @param inDate
+ * @param inDate the Date
* @return Formatted date
*/
public String format(Date inDate)
@@ -187,7 +185,7 @@ public class DateCache
/** Format a date according to our stored formatter.
* If it happens to be in the same second as the last formatNow
* call, then the format is reused.
- * @param inDate
+ * @param inDate the date in milliseconds since unix epoch
* @return Formatted date
*/
public String format(long inDate)
@@ -215,7 +213,7 @@ public class DateCache
* The passed time is expected to be close to the current time, so it is
* compared to the last value passed and if it is within the same second,
* the format is reused. Otherwise a new cached format is created.
- * @param now
+ * @param now the milliseconds since unix epoch
* @return Formatted date
*/
public String formatNow(long now)
diff --git a/jetty-util/src/main/java/org/eclipse/jetty/util/HostMap.java b/jetty-util/src/main/java/org/eclipse/jetty/util/HostMap.java
index 18f557f1390..5db650f8a97 100644
--- a/jetty-util/src/main/java/org/eclipse/jetty/util/HostMap.java
+++ b/jetty-util/src/main/java/org/eclipse/jetty/util/HostMap.java
@@ -23,8 +23,8 @@ import java.util.HashMap;
import java.util.HashSet;
import java.util.Map;
-/* ------------------------------------------------------------ */
/**
+ * @param the element type
*/
@SuppressWarnings("serial")
public class HostMap extends HashMap
diff --git a/jetty-util/src/main/java/org/eclipse/jetty/util/IO.java b/jetty-util/src/main/java/org/eclipse/jetty/util/IO.java
index 6a0032a8748..03b0dc74430 100644
--- a/jetty-util/src/main/java/org/eclipse/jetty/util/IO.java
+++ b/jetty-util/src/main/java/org/eclipse/jetty/util/IO.java
@@ -108,6 +108,9 @@ public class IO
/* ------------------------------------------------------------------- */
/** Copy Stream in to Stream out until EOF or exception.
+ * @param in the input stream to read from (until EOF)
+ * @param out the output stream to write to
+ * @throws IOException if unable to copy streams
*/
public static void copy(InputStream in, OutputStream out)
throws IOException
@@ -117,6 +120,9 @@ public class IO
/* ------------------------------------------------------------------- */
/** Copy Reader to Writer out until EOF or exception.
+ * @param in the read to read from (until EOF)
+ * @param out the writer to write to
+ * @throws IOException if unable to copy the streams
*/
public static void copy(Reader in, Writer out)
throws IOException
@@ -126,6 +132,10 @@ public class IO
/* ------------------------------------------------------------------- */
/** Copy Stream in to Stream for byteCount bytes or until EOF or exception.
+ * @param in the stream to read from
+ * @param out the stream to write to
+ * @param byteCount the number of bytes to copy
+ * @throws IOException if unable to copy the streams
*/
public static void copy(InputStream in,
OutputStream out,
@@ -163,6 +173,10 @@ public class IO
/* ------------------------------------------------------------------- */
/** Copy Reader to Writer for byteCount bytes or until EOF or exception.
+ * @param in the Reader to read from
+ * @param out the Writer to write to
+ * @param byteCount the number of bytes to copy
+ * @throws IOException if unable to copy streams
*/
public static void copy(Reader in,
Writer out,
@@ -213,9 +227,9 @@ public class IO
/* ------------------------------------------------------------ */
/** Copy files or directories
- * @param from
- * @param to
- * @throws IOException
+ * @param from the file to copy
+ * @param to the destination to copy to
+ * @throws IOException if unable to copy
*/
public static void copy(File from,File to) throws IOException
{
@@ -261,6 +275,9 @@ public class IO
/* ------------------------------------------------------------ */
/** Read input stream to string.
+ * @param in the stream to read from (until EOF)
+ * @return the String parsed from stream (default Charset)
+ * @throws IOException if unable to read the stream (or handle the charset)
*/
public static String toString(InputStream in)
throws IOException
@@ -270,6 +287,10 @@ public class IO
/* ------------------------------------------------------------ */
/** Read input stream to string.
+ * @param in the stream to read from (until EOF)
+ * @param encoding the encoding to use (can be null to use default Charset)
+ * @return the String parsed from the stream
+ * @throws IOException if unable to read the stream (or handle the charset)
*/
public static String toString(InputStream in,String encoding)
throws IOException
@@ -278,6 +299,10 @@ public class IO
}
/** Read input stream to string.
+ * @param in the stream to read from (until EOF)
+ * @param encoding the Charset to use (can be null to use default Charset)
+ * @return the String parsed from the stream
+ * @throws IOException if unable to read the stream (or handle the charset)
*/
public static String toString(InputStream in, Charset encoding)
throws IOException
@@ -291,6 +316,9 @@ public class IO
/* ------------------------------------------------------------ */
/** Read input stream to string.
+ * @param in the reader to read from (until EOF)
+ * @return the String parsed from the reader
+ * @throws IOException if unable to read the stream (or handle the charset)
*/
public static String toString(Reader in)
throws IOException
@@ -304,7 +332,8 @@ public class IO
/* ------------------------------------------------------------ */
/** Delete File.
* This delete will recursively delete directories - BE CAREFULL
- * @param file The file to be deleted.
+ * @param file The file (or directory) to be deleted.
+ * @return true if anything was deleted. (note: this does not mean that all content in a directory was deleted)
*/
public static boolean delete(File file)
{
diff --git a/jetty-util/src/main/java/org/eclipse/jetty/util/IPAddressMap.java b/jetty-util/src/main/java/org/eclipse/jetty/util/IPAddressMap.java
index 370693c5180..f9143ff1edc 100644
--- a/jetty-util/src/main/java/org/eclipse/jetty/util/IPAddressMap.java
+++ b/jetty-util/src/main/java/org/eclipse/jetty/util/IPAddressMap.java
@@ -32,14 +32,15 @@ import java.util.StringTokenizer;
* four octet wildcard specifications (a.b.c.d) that are defined as follows.
*
*
- * nnn - an absolute value (0-255)
- * mmm-nnn - an inclusive range of absolute values,
- * with following shorthand notations:
- * nnn- => nnn-255
- * -nnn => 0-nnn
- * - => 0-255
- * a,b,... - a list of wildcard specifications
+ * nnn - an absolute value (0-255)
+ * mmm-nnn - an inclusive range of absolute values,
+ * with following shorthand notations:
+ * nnn- => nnn-255
+ * -nnn => 0-nnn
+ * - => 0-255
+ * a,b,... - a list of wildcard specifications
*
+ * @param the Map Entry value type
*/
@SuppressWarnings("serial")
public class IPAddressMap extends HashMap
diff --git a/jetty-util/src/main/java/org/eclipse/jetty/util/IteratingCallback.java b/jetty-util/src/main/java/org/eclipse/jetty/util/IteratingCallback.java
index 0f53d468788..a155a4e5690 100644
--- a/jetty-util/src/main/java/org/eclipse/jetty/util/IteratingCallback.java
+++ b/jetty-util/src/main/java/org/eclipse/jetty/util/IteratingCallback.java
@@ -26,29 +26,33 @@ import org.eclipse.jetty.util.thread.SpinLock;
* This specialized callback implements a pattern that allows
* a large job to be broken into smaller tasks using iteration
* rather than recursion.
- *
+ *
* A typical example is the write of a large content to a socket,
* divided in chunks. Chunk C1 is written by thread T1, which
* also invokes the callback, which writes chunk C2, which invokes
* the callback again, which writes chunk C3, and so forth.
- *
+ *
+ *
* The problem with the example is that if the callback thread
* is the same that performs the I/O operation, then the process
* is recursive and may result in a stack overflow.
* To avoid the stack overflow, a thread dispatch must be performed,
* causing context switching and cache misses, affecting performance.
- *
+ *
+ *
* To avoid this issue, this callback uses an AtomicReference to
* record whether success callback has been called during the processing
* of a sub task, and if so then the processing iterates rather than
* recurring.
- *
+ *
+ *
* Subclasses must implement method {@link #process()} where the sub
* task is executed and a suitable {@link IteratingCallback.Action} is
* returned to this callback to indicate the overall progress of the job.
* This callback is passed to the asynchronous execution of each sub
* task and a call the {@link #succeeded()} on this callback represents
* the completion of the sub task.
+ *
*/
public abstract class IteratingCallback implements Callback
{
@@ -138,9 +142,10 @@ public abstract class IteratingCallback implements Callback
/**
* Method called by {@link #iterate()} to process the sub task.
- *
+ *
* Implementations must start the asynchronous execution of the sub task
* (if any) and return an appropriate action:
+ *
*
* - {@link Action#IDLE} when no sub tasks are available for execution
* but the overall job is not completed yet
@@ -148,6 +153,8 @@ public abstract class IteratingCallback implements Callback
* has been started
* - {@link Action#SUCCEEDED} when the overall job is completed
*
+ *
+ * @return the appropriate Action
*
* @throws Exception if the sub task processing throws
*/
@@ -164,10 +171,11 @@ public abstract class IteratingCallback implements Callback
/**
* Invoked when the overall task has completed with a failure.
+ * @param cause the throwable to indicate cause of failure
*
* @see #onCompleteSuccess()
*/
- protected void onCompleteFailure(Throwable x)
+ protected void onCompleteFailure(Throwable cause)
{
}
@@ -464,9 +472,10 @@ public abstract class IteratingCallback implements Callback
/**
* Resets this callback.
- *
+ *
* A callback can only be reset to IDLE from the
* SUCCEEDED or FAILED states or if it is already IDLE.
+ *
*
* @return true if the reset was successful
*/
diff --git a/jetty-util/src/main/java/org/eclipse/jetty/util/LazyList.java b/jetty-util/src/main/java/org/eclipse/jetty/util/LazyList.java
index 2013a6851a6..0855be3854b 100644
--- a/jetty-util/src/main/java/org/eclipse/jetty/util/LazyList.java
+++ b/jetty-util/src/main/java/org/eclipse/jetty/util/LazyList.java
@@ -27,21 +27,23 @@ import java.util.Iterator;
import java.util.List;
import java.util.ListIterator;
-/* ------------------------------------------------------------ */
-/** Lazy List creation.
+/**
+ * Lazy List creation.
+ *
* A List helper class that attempts to avoid unnecessary List
* creation. If a method needs to create a List to return, but it is
* expected that this will either be empty or frequently contain a
* single item, then using LazyList will avoid additional object
* creations by using {@link Collections#EMPTY_LIST} or
* {@link Collections#singletonList(Object)} where possible.
+ *
*
* LazyList works by passing an opaque representation of the list in
* and out of all the LazyList methods. This opaque object is either
* null for an empty list, an Object for a list with a single entry
* or an {@link ArrayList} for a list of items.
- *
- *
Usage
+ *
+ * Usage
*
* Object lazylist =null;
* while(loopCondition)
@@ -162,7 +164,9 @@ public class LazyList
/* ------------------------------------------------------------ */
/** Ensure the capacity of the underlying list.
- *
+ * @param list the list to grow
+ * @param initialSize the size to grow to
+ * @return the new List with new size
*/
public static Object ensureSize(Object list, int initialSize)
{
@@ -230,6 +234,7 @@ public class LazyList
* @param list A LazyList returned from LazyList.add(Object)
* @return The List of added items, which may be an EMPTY_LIST
* or a SingletonList.
+ * @param the list entry type
*/
public static List getList(Object list)
{
@@ -245,6 +250,7 @@ public class LazyList
* empty list.
* @return The List of added items, which may be null, an EMPTY_LIST
* or a SingletonList.
+ * @param the list entry type
*/
@SuppressWarnings("unchecked")
public static List getList(Object list, boolean nullForEmpty)
@@ -365,6 +371,7 @@ public class LazyList
* @param list A LazyList returned from LazyList.add(Object) or null
* @param i int index
* @return the item from the list.
+ * @param the list entry type
*/
@SuppressWarnings("unchecked")
public static E get(Object list, int i)
diff --git a/jetty-util/src/main/java/org/eclipse/jetty/util/Loader.java b/jetty-util/src/main/java/org/eclipse/jetty/util/Loader.java
index 500f9f9c837..062029cef45 100644
--- a/jetty-util/src/main/java/org/eclipse/jetty/util/Loader.java
+++ b/jetty-util/src/main/java/org/eclipse/jetty/util/Loader.java
@@ -69,10 +69,10 @@ public class Loader
/* ------------------------------------------------------------ */
/** Load a class.
*
- * @param loadClass
- * @param name
+ * @param loadClass the class to use for the ClassLoader that was used
+ * @param name the name of the new class to load, using the same ClassLoader as the loadClass
* @return Class
- * @throws ClassNotFoundException
+ * @throws ClassNotFoundException if not able to find the class
*/
@SuppressWarnings("rawtypes")
public static Class loadClass(Class loadClass,String name)
@@ -153,7 +153,9 @@ public class Loader
* above the given classloader.
*
* This is primarily used for jasper.
+ * @param loader the classloader to use
* @return the system class path
+ * @throws Exception if unable to generate the classpath from the resource references
*/
public static String getClassPath(ClassLoader loader) throws Exception
{
diff --git a/jetty-util/src/main/java/org/eclipse/jetty/util/MemoryUtils.java b/jetty-util/src/main/java/org/eclipse/jetty/util/MemoryUtils.java
index a0e50f4561f..a8f830de4e0 100644
--- a/jetty-util/src/main/java/org/eclipse/jetty/util/MemoryUtils.java
+++ b/jetty-util/src/main/java/org/eclipse/jetty/util/MemoryUtils.java
@@ -22,8 +22,7 @@ import java.security.AccessController;
import java.security.PrivilegedAction;
/**
- * {@link MemoryUtils} provides an abstraction over memory properties and operations.
- *
+ * MemoryUtils provides an abstraction over memory properties and operations.
*/
public class MemoryUtils
{
@@ -67,5 +66,4 @@ public class MemoryUtils
{
return getCacheLineBytes() >> 3;
}
-
}
diff --git a/jetty-util/src/main/java/org/eclipse/jetty/util/MultiException.java b/jetty-util/src/main/java/org/eclipse/jetty/util/MultiException.java
index fdc62c516c6..3212551e794 100644
--- a/jetty-util/src/main/java/org/eclipse/jetty/util/MultiException.java
+++ b/jetty-util/src/main/java/org/eclipse/jetty/util/MultiException.java
@@ -84,7 +84,7 @@ public class MultiException extends Exception
* If this multi exception is empty then no action is taken. If it
* contains a single exception that is thrown, otherwise the this
* multi exception is thrown.
- * @exception Exception
+ * @exception Exception the Error or Exception if nested is 1, or the MultiException itself if nested is more than 1.
*/
public void ifExceptionThrow()
throws Exception
@@ -144,6 +144,7 @@ public class MultiException extends Exception
* If this multi exception is empty then no action is taken. If it
* contains a any exceptions then this
* multi exception is thrown.
+ * @throws MultiException the multiexception if there are nested exception
*/
public void ifExceptionThrowMulti()
throws MultiException
diff --git a/jetty-util/src/main/java/org/eclipse/jetty/util/MultiMap.java b/jetty-util/src/main/java/org/eclipse/jetty/util/MultiMap.java
index 286889bcde4..2d9a53342de 100644
--- a/jetty-util/src/main/java/org/eclipse/jetty/util/MultiMap.java
+++ b/jetty-util/src/main/java/org/eclipse/jetty/util/MultiMap.java
@@ -28,6 +28,7 @@ import java.util.Map.Entry;
/**
* A multi valued Map.
+ * @param the entry type for multimap values
*/
@SuppressWarnings("serial")
public class MultiMap extends HashMap>
@@ -283,7 +284,7 @@ public class MultiMap extends HashMap>
* Test for a specific single value in the map.
*
* NOTE: This is a SLOW operation, and is actively discouraged.
- * @param value
+ * @param value the value to search for
* @return true if contains simple value
*/
public boolean containsSimpleValue(V value)
diff --git a/jetty-util/src/main/java/org/eclipse/jetty/util/MultiPartInputStreamParser.java b/jetty-util/src/main/java/org/eclipse/jetty/util/MultiPartInputStreamParser.java
index a8607ea00f8..273c9f96d3d 100644
--- a/jetty-util/src/main/java/org/eclipse/jetty/util/MultiPartInputStreamParser.java
+++ b/jetty-util/src/main/java/org/eclipse/jetty/util/MultiPartInputStreamParser.java
@@ -293,7 +293,7 @@ public class MultiPartInputStreamParser
/**
* Only remove tmp files.
*
- * @throws IOException
+ * @throws IOException if unable to delete the file
*/
public void cleanUp() throws IOException
{
@@ -303,7 +303,8 @@ public class MultiPartInputStreamParser
/**
- * Get the file, if any, the data has been written to.
+ * Get the file
+ * @return the file, if any, the data has been written to.
*/
public File getFile ()
{
@@ -345,6 +346,7 @@ public class MultiPartInputStreamParser
/**
* Get the already parsed parts.
+ * @return the parts that were parsed
*/
public Collection getParsedParts()
{
@@ -364,7 +366,7 @@ public class MultiPartInputStreamParser
/**
* Delete any tmp storage for parts, and clear out the parts list.
*
- * @throws MultiException
+ * @throws MultiException if unable to delete the parts
*/
public void deleteParts ()
throws MultiException
@@ -391,8 +393,9 @@ public class MultiPartInputStreamParser
/**
* Parse, if necessary, the multipart data and return the list of Parts.
*
- * @throws IOException
- * @throws ServletException
+ * @return the parts
+ * @throws IOException if unable to get the parts
+ * @throws ServletException if unable to parse the parts
*/
public Collection getParts()
throws IOException, ServletException
@@ -412,9 +415,10 @@ public class MultiPartInputStreamParser
/**
* Get the named Part.
*
- * @param name
- * @throws IOException
- * @throws ServletException
+ * @param name the part name
+ * @return the parts
+ * @throws IOException if unable to get the part
+ * @throws ServletException if unable to parse the parts
*/
public Part getPart(String name)
throws IOException, ServletException
@@ -427,8 +431,8 @@ public class MultiPartInputStreamParser
/**
* Parse, if necessary, the multipart stream.
*
- * @throws IOException
- * @throws ServletException
+ * @throws IOException if unable to parse
+ * @throws ServletException FIXME, never thrown
*/
protected void parse ()
throws IOException, ServletException
diff --git a/jetty-util/src/main/java/org/eclipse/jetty/util/MultiPartOutputStream.java b/jetty-util/src/main/java/org/eclipse/jetty/util/MultiPartOutputStream.java
index ddf985045b3..13284c2f463 100644
--- a/jetty-util/src/main/java/org/eclipse/jetty/util/MultiPartOutputStream.java
+++ b/jetty-util/src/main/java/org/eclipse/jetty/util/MultiPartOutputStream.java
@@ -24,7 +24,6 @@ import java.io.OutputStream;
import java.nio.charset.StandardCharsets;
-/* ================================================================ */
/** Handle a multipart MIME response.
*
*
@@ -100,6 +99,8 @@ public class MultiPartOutputStream extends FilterOutputStream
/* ------------------------------------------------------------ */
/** Start creation of the next Content.
+ * @param contentType the content type of the part
+ * @throws IOException if unable to write the part
*/
public void startPart(String contentType)
throws IOException
@@ -118,6 +119,9 @@ public class MultiPartOutputStream extends FilterOutputStream
/* ------------------------------------------------------------ */
/** Start creation of the next Content.
+ * @param contentType the content type of the part
+ * @param headers the part headers
+ * @throws IOException if unable to write the part
*/
public void startPart(String contentType, String[] headers)
throws IOException
diff --git a/jetty-util/src/main/java/org/eclipse/jetty/util/MultiPartWriter.java b/jetty-util/src/main/java/org/eclipse/jetty/util/MultiPartWriter.java
index f0654f594be..93f603cd1a5 100644
--- a/jetty-util/src/main/java/org/eclipse/jetty/util/MultiPartWriter.java
+++ b/jetty-util/src/main/java/org/eclipse/jetty/util/MultiPartWriter.java
@@ -87,6 +87,8 @@ public class MultiPartWriter extends FilterWriter
/* ------------------------------------------------------------ */
/** Start creation of the next Content.
+ * @param contentType the content type
+ * @throws IOException if unable to write the part
*/
public void startPart(String contentType)
throws IOException
@@ -105,6 +107,7 @@ public class MultiPartWriter extends FilterWriter
/* ------------------------------------------------------------ */
/** end creation of the next Content.
+ * @throws IOException if unable to write the part
*/
public void endPart()
throws IOException
@@ -116,6 +119,9 @@ public class MultiPartWriter extends FilterWriter
/* ------------------------------------------------------------ */
/** Start creation of the next Content.
+ * @param contentType the content type of the part
+ * @param headers the part headers
+ * @throws IOException if unable to write the part
*/
public void startPart(String contentType, String[] headers)
throws IOException
diff --git a/jetty-util/src/main/java/org/eclipse/jetty/util/PatternMatcher.java b/jetty-util/src/main/java/org/eclipse/jetty/util/PatternMatcher.java
index 503010163d5..0d23f2fcb32 100644
--- a/jetty-util/src/main/java/org/eclipse/jetty/util/PatternMatcher.java
+++ b/jetty-util/src/main/java/org/eclipse/jetty/util/PatternMatcher.java
@@ -53,7 +53,7 @@ public abstract class PatternMatcher
* @param pattern the pattern
* @param uris the uris to test the pattern against
* @param isNullInclusive if true, an empty pattern means all names match, if false, none match
- * @throws Exception
+ * @throws Exception if fundamental error in pattern matching
*/
public void match (Pattern pattern, URI[] uris, boolean isNullInclusive)
throws Exception
diff --git a/jetty-util/src/main/java/org/eclipse/jetty/util/QuotedStringTokenizer.java b/jetty-util/src/main/java/org/eclipse/jetty/util/QuotedStringTokenizer.java
index 7436c6021f3..951a1b3ed2c 100644
--- a/jetty-util/src/main/java/org/eclipse/jetty/util/QuotedStringTokenizer.java
+++ b/jetty-util/src/main/java/org/eclipse/jetty/util/QuotedStringTokenizer.java
@@ -472,6 +472,7 @@ public class QuotedStringTokenizer
/* ------------------------------------------------------------ */
/** Unquote a string.
* @param s The string to unquote.
+ * @param lenient true if unquoting should be lenient to escaped content, leaving some alone, false if string unescaping
* @return quoted string
*/
public static String unquote(String s, boolean lenient)
diff --git a/jetty-util/src/main/java/org/eclipse/jetty/util/RolloverFileOutputStream.java b/jetty-util/src/main/java/org/eclipse/jetty/util/RolloverFileOutputStream.java
index 8085f1eeea4..1ff0b7631c7 100644
--- a/jetty-util/src/main/java/org/eclipse/jetty/util/RolloverFileOutputStream.java
+++ b/jetty-util/src/main/java/org/eclipse/jetty/util/RolloverFileOutputStream.java
@@ -40,8 +40,6 @@ import java.util.TimerTask;
* actual date when creating and rolling over the file.
*
* Old files are retained for a number of days before being deleted.
- *
- *
*/
public class RolloverFileOutputStream extends FilterOutputStream
{
@@ -65,7 +63,7 @@ public class RolloverFileOutputStream extends FilterOutputStream
/**
* @param filename The filename must include the string "yyyy_mm_dd",
* which is replaced with the actual date when creating and rolling over the file.
- * @throws IOException
+ * @throws IOException if unable to create output
*/
public RolloverFileOutputStream(String filename)
throws IOException
@@ -78,7 +76,7 @@ public class RolloverFileOutputStream extends FilterOutputStream
* @param filename The filename must include the string "yyyy_mm_dd",
* which is replaced with the actual date when creating and rolling over the file.
* @param append If true, existing files will be appended to.
- * @throws IOException
+ * @throws IOException if unable to create output
*/
public RolloverFileOutputStream(String filename, boolean append)
throws IOException
@@ -92,7 +90,7 @@ public class RolloverFileOutputStream extends FilterOutputStream
* which is replaced with the actual date when creating and rolling over the file.
* @param append If true, existing files will be appended to.
* @param retainDays The number of days to retain files before deleting them. 0 to retain forever.
- * @throws IOException
+ * @throws IOException if unable to create output
*/
public RolloverFileOutputStream(String filename,
boolean append,
@@ -108,7 +106,8 @@ public class RolloverFileOutputStream extends FilterOutputStream
* which is replaced with the actual date when creating and rolling over the file.
* @param append If true, existing files will be appended to.
* @param retainDays The number of days to retain files before deleting them. 0 to retain forever.
- * @throws IOException
+ * @param zone the timezone for the output
+ * @throws IOException if unable to create output
*/
public RolloverFileOutputStream(String filename,
boolean append,
@@ -126,9 +125,10 @@ public class RolloverFileOutputStream extends FilterOutputStream
* which is replaced with the actual date when creating and rolling over the file.
* @param append If true, existing files will be appended to.
* @param retainDays The number of days to retain files before deleting them. 0 to retain forever.
+ * @param zone the timezone for the output
* @param dateFormat The format for the date file substitution. The default is "yyyy_MM_dd".
* @param backupFormat The format for the file extension of backup files. The default is "HHmmssSSS".
- * @throws IOException
+ * @throws IOException if unable to create output
*/
public RolloverFileOutputStream(String filename,
boolean append,
diff --git a/jetty-util/src/main/java/org/eclipse/jetty/util/Scanner.java b/jetty-util/src/main/java/org/eclipse/jetty/util/Scanner.java
index 848aa08e6ab..c6631da5550 100644
--- a/jetty-util/src/main/java/org/eclipse/jetty/util/Scanner.java
+++ b/jetty-util/src/main/java/org/eclipse/jetty/util/Scanner.java
@@ -221,7 +221,7 @@ public class Scanner extends AbstractLifeCycle
/**
* Apply a filter to files found in the scan directory.
* Only files matching the filter will be reported as added/changed/removed.
- * @param filter
+ * @param filter the filename filter to use
*/
public void setFilenameFilter (FilenameFilter filter)
{
@@ -257,7 +257,7 @@ public class Scanner extends AbstractLifeCycle
/* ------------------------------------------------------------ */
/** Set if found directories should be reported.
- * @param dirs
+ * @param dirs true to report directory changes as well
*/
public void setReportDirs(boolean dirs)
{
@@ -273,7 +273,7 @@ public class Scanner extends AbstractLifeCycle
/* ------------------------------------------------------------ */
/**
* Add an added/removed/changed listener
- * @param listener
+ * @param listener the listener to add
*/
public synchronized void addListener (Listener listener)
{
@@ -370,6 +370,7 @@ public class Scanner extends AbstractLifeCycle
}
/**
+ * @param path tests if the path exists
* @return true if the path exists in one of the scandirs
*/
public boolean exists(String path)
diff --git a/jetty-util/src/main/java/org/eclipse/jetty/util/SharedBlockingCallback.java b/jetty-util/src/main/java/org/eclipse/jetty/util/SharedBlockingCallback.java
index 3e2645e818b..68d1234d96b 100644
--- a/jetty-util/src/main/java/org/eclipse/jetty/util/SharedBlockingCallback.java
+++ b/jetty-util/src/main/java/org/eclipse/jetty/util/SharedBlockingCallback.java
@@ -33,7 +33,7 @@ import org.eclipse.jetty.util.log.Logger;
/**
* Provides a reusable {@link Callback} that can block the thread
* while waiting to be completed.
- *
+ *
* A typical usage pattern is:
*
* void someBlockingCall(Object... args) throws IOException
diff --git a/jetty-util/src/main/java/org/eclipse/jetty/util/SocketAddressResolver.java b/jetty-util/src/main/java/org/eclipse/jetty/util/SocketAddressResolver.java
index 62ad1cf54a7..068025526b0 100644
--- a/jetty-util/src/main/java/org/eclipse/jetty/util/SocketAddressResolver.java
+++ b/jetty-util/src/main/java/org/eclipse/jetty/util/SocketAddressResolver.java
@@ -33,12 +33,12 @@ import org.eclipse.jetty.util.thread.Scheduler;
/**
* Creates asynchronously {@link SocketAddress} instances, returning them through a {@link Promise},
* in order to avoid blocking on DNS lookup.
- *
+ *
* {@link InetSocketAddress#InetSocketAddress(String, int)} attempts to perform a DNS resolution of
* the host name, and this may block for several seconds.
* This class creates the {@link InetSocketAddress} in a separate thread and provides the result
* through a {@link Promise}, with the possibility to specify a timeout for the operation.
- *
+ *
* Example usage:
*
* SocketAddressResolver resolver = new SocketAddressResolver(executor, scheduler);
diff --git a/jetty-util/src/main/java/org/eclipse/jetty/util/StringUtil.java b/jetty-util/src/main/java/org/eclipse/jetty/util/StringUtil.java
index 6accd1e8d87..33655ccb4dd 100644
--- a/jetty-util/src/main/java/org/eclipse/jetty/util/StringUtil.java
+++ b/jetty-util/src/main/java/org/eclipse/jetty/util/StringUtil.java
@@ -64,6 +64,8 @@ public class StringUtil
/* ------------------------------------------------------------ */
/** Convert alternate charset names (eg utf8) to normalized
* name (eg UTF-8).
+ * @param s the charset to normalize
+ * @return the normalized charset (or null if normalized version not found)
*/
public static String normalizeCharset(String s)
{
@@ -74,6 +76,10 @@ public class StringUtil
/* ------------------------------------------------------------ */
/** Convert alternate charset names (eg utf8) to normalized
* name (eg UTF-8).
+ * @param s the charset to normalize
+ * @param offset the offset in the charset
+ * @param length the length of the charset in the input param
+ * @return the normalized charset (or null if not found)
*/
public static String normalizeCharset(String s,int offset,int length)
{
@@ -199,6 +205,9 @@ public class StringUtil
/* ------------------------------------------------------------ */
/**
* returns the next index of a character from the chars string
+ * @param s the input string to search
+ * @param chars the chars to look for
+ * @return the index of the character in the input stream found.
*/
public static int indexFrom(String s,String chars)
{
@@ -211,6 +220,10 @@ public class StringUtil
/* ------------------------------------------------------------ */
/**
* replace substrings within string.
+ * @param s the input string
+ * @param sub the string to look for
+ * @param with the string to replace with
+ * @return the now replaced string
*/
public static String replace(String s, String sub, String with)
{
@@ -238,6 +251,8 @@ public class StringUtil
/* ------------------------------------------------------------ */
/** Remove single or double quotes.
+ * @param s the input string
+ * @return the string with quotes removed
*/
public static String unquote(String s)
{
@@ -273,6 +288,9 @@ public class StringUtil
/* ------------------------------------------------------------ */
/**
* append hex digit
+ * @param buf the buffer to append to
+ * @param b the byte to append
+ * @param base the base of the hex output (almost always 16).
*
*/
public static void append(StringBuilder buf,byte b,int base)
@@ -289,6 +307,12 @@ public class StringUtil
}
/* ------------------------------------------------------------ */
+ /**
+ * Append 2 digits (zero padded) to the StringBuffer
+ *
+ * @param buf the buffer to append to
+ * @param i the value to append
+ */
public static void append2digits(StringBuffer buf,int i)
{
if (i<100)
@@ -299,6 +323,12 @@ public class StringUtil
}
/* ------------------------------------------------------------ */
+ /**
+ * Append 2 digits (zero padded) to the StringBuilder
+ *
+ * @param buf the buffer to append to
+ * @param i the value to append
+ */
public static void append2digits(StringBuilder buf,int i)
{
if (i<100)
@@ -501,6 +531,8 @@ public class StringUtil
* http://en.wikipedia.org/wiki/Security_Identifier
*
* S-1-IdentifierAuthority-SubAuthority1-SubAuthority2-...-SubAuthorityn
+ * @param sidBytes the SID bytes to build from
+ * @return the string SID
*/
public static String sidBytesToString(byte[] sidBytes)
{
@@ -548,6 +580,8 @@ public class StringUtil
* http://en.wikipedia.org/wiki/Security_Identifier
*
* S-1-IdentifierAuthority-SubAuthority1-SubAuthority2-...-SubAuthorityn
+ * @param sidString the string SID
+ * @return the binary SID
*/
public static byte[] sidStringToBytes( String sidString )
{
diff --git a/jetty-util/src/main/java/org/eclipse/jetty/util/TreeTrie.java b/jetty-util/src/main/java/org/eclipse/jetty/util/TreeTrie.java
index ccda7416b2f..b8b3afa6581 100644
--- a/jetty-util/src/main/java/org/eclipse/jetty/util/TreeTrie.java
+++ b/jetty-util/src/main/java/org/eclipse/jetty/util/TreeTrie.java
@@ -39,7 +39,7 @@ import java.util.Set;
* Trie is required external locks need to be applied.
*
*
- * @param
+ * @param the entry type
*/
public class TreeTrie extends AbstractTrie
{
diff --git a/jetty-util/src/main/java/org/eclipse/jetty/util/Trie.java b/jetty-util/src/main/java/org/eclipse/jetty/util/Trie.java
index 131e6105ba3..280ae4c28d2 100644
--- a/jetty-util/src/main/java/org/eclipse/jetty/util/Trie.java
+++ b/jetty-util/src/main/java/org/eclipse/jetty/util/Trie.java
@@ -24,7 +24,7 @@ import java.util.Set;
/* ------------------------------------------------------------ */
/** A Trie String lookup data structure.
- * @param
+ * @param the Trie entry type
*/
public interface Trie
{
@@ -49,6 +49,7 @@ public interface Trie
/* ------------------------------------------------------------ */
/** Get and exact match from a String key
* @param s The key
+ * @return the value for the string key
*/
public V get(String s);
@@ -57,6 +58,7 @@ public interface Trie
* @param s The key
* @param offset The offset within the string of the key
* @param len the length of the key
+ * @return the value for the string / offset / length
*/
public V get(String s,int offset,int len);
diff --git a/jetty-util/src/main/java/org/eclipse/jetty/util/TypeUtil.java b/jetty-util/src/main/java/org/eclipse/jetty/util/TypeUtil.java
index 42789983ee9..6eedd3e6fed 100644
--- a/jetty-util/src/main/java/org/eclipse/jetty/util/TypeUtil.java
+++ b/jetty-util/src/main/java/org/eclipse/jetty/util/TypeUtil.java
@@ -173,7 +173,9 @@ public class TypeUtil
/** Array to List.
*
* Works like {@link Arrays#asList(Object...)}, but handles null arrays.
+ * @param a the array to convert to a list
* @return a list backed by the array.
+ * @param the array and list entry type
*/
public static List asList(T[] a)
{
diff --git a/jetty-util/src/main/java/org/eclipse/jetty/util/URIUtil.java b/jetty-util/src/main/java/org/eclipse/jetty/util/URIUtil.java
index bb0f7f1a9c1..cf0f985ba0a 100644
--- a/jetty-util/src/main/java/org/eclipse/jetty/util/URIUtil.java
+++ b/jetty-util/src/main/java/org/eclipse/jetty/util/URIUtil.java
@@ -25,18 +25,20 @@ import org.eclipse.jetty.util.Utf8Appendable.NotUtf8Exception;
import org.eclipse.jetty.util.log.Log;
import org.eclipse.jetty.util.log.Logger;
-
-
-/* ------------------------------------------------------------ */
-/** URI Utility methods.
+/**
+ * URI Utility methods.
+ *
* This class assists with the decoding and encoding or HTTP URI's.
* It differs from the java.net.URL class as it does not provide
* communications ability, but it does assist with query string
* formatting.
- *
UTF-8 encoding is used by default for % encoded characters. This
+ *
+ *
+ * UTF-8 encoding is used by default for % encoded characters. This
* may be overridden with the org.eclipse.jetty.util.URI.charset system property.
- * @see UrlEncoded
+ *
*
+ * @see UrlEncoded
*/
public class URIUtil
implements Cloneable
@@ -479,6 +481,8 @@ public class URIUtil
/* ------------------------------------------------------------ */
/** Return the parent Path.
* Treat a URI like a directory path and return the parent directory.
+ * @param p the path to return a parent reference to
+ * @return the parent path of the URI
*/
public static String parentPath(String p)
{
@@ -494,7 +498,7 @@ public class URIUtil
/** Convert a path to a cananonical form.
* All instances of "." and ".." are factored out. Null is returned
* if the path tries to .. above its root.
- * @param path
+ * @param path the path to convert
* @return path or null.
*/
public static String canonicalPath(String path)
@@ -628,8 +632,8 @@ public class URIUtil
/* ------------------------------------------------------------ */
/** Convert a path to a compact form.
* All instances of "//" and "///" etc. are factored out to single "/"
- * @param path
- * @return path
+ * @param path the path to compact
+ * @return the compacted path
*/
public static String compactPath(String path)
{
@@ -715,11 +719,11 @@ public class URIUtil
/* ------------------------------------------------------------ */
/**
* Create a new URI from the arguments, handling IPv6 host encoding and default ports
- * @param scheme
- * @param server
- * @param port
- * @param path
- * @param query
+ * @param scheme the URI scheme
+ * @param server the URI server
+ * @param port the URI port
+ * @param path the URI path
+ * @param query the URI query
* @return A String URI
*/
public static String newURI(String scheme,String server, int port,String path,String query)
@@ -734,9 +738,9 @@ public class URIUtil
/* ------------------------------------------------------------ */
/**
* Create a new URI StringBuilder from the arguments, handling IPv6 host encoding and default ports
- * @param scheme
- * @param server
- * @param port
+ * @param scheme the URI scheme
+ * @param server the URI server
+ * @param port the URI port
* @return a StringBuilder containing URI prefix
*/
public static StringBuilder newURIBuilder(String scheme,String server, int port)
@@ -748,11 +752,11 @@ public class URIUtil
/* ------------------------------------------------------------ */
/**
- * Append scheme, host and port URI prefix, handling IPv6 address encoding and default ports
+ * Append scheme, host and port URI prefix, handling IPv6 address encoding and default ports
* @param url StringBuilder to append to
- * @param scheme
- * @param server
- * @param port
+ * @param scheme the URI scheme
+ * @param server the URI server
+ * @param port the URI port
*/
public static void appendSchemeHostPort(StringBuilder url,String scheme,String server, int port)
{
@@ -783,11 +787,11 @@ public class URIUtil
/* ------------------------------------------------------------ */
/**
- * Append scheme, host and port URI prefix, handling IPv6 address encoding and default ports
+ * Append scheme, host and port URI prefix, handling IPv6 address encoding and default ports
* @param url StringBuffer to append to
- * @param scheme
- * @param server
- * @param port
+ * @param scheme the URI scheme
+ * @param server the URI server
+ * @param port the URI port
*/
public static void appendSchemeHostPort(StringBuffer url,String scheme,String server, int port)
{
diff --git a/jetty-util/src/main/java/org/eclipse/jetty/util/UrlEncoded.java b/jetty-util/src/main/java/org/eclipse/jetty/util/UrlEncoded.java
index 8727d1326d1..e776c9a4d5d 100644
--- a/jetty-util/src/main/java/org/eclipse/jetty/util/UrlEncoded.java
+++ b/jetty-util/src/main/java/org/eclipse/jetty/util/UrlEncoded.java
@@ -33,22 +33,26 @@ import org.eclipse.jetty.util.Utf8Appendable.NotUtf8Exception;
import org.eclipse.jetty.util.log.Log;
import org.eclipse.jetty.util.log.Logger;
-/* ------------------------------------------------------------ */
-/** Handles coding of MIME "x-www-form-urlencoded".
+/**
+ * Handles coding of MIME "x-www-form-urlencoded".
*
* This class handles the encoding and decoding for either
* the query string of a URL or the _content of a POST HTTP request.
- *
- *
Notes
+ *
+ * Notes
+ *
* The UTF-8 charset is assumed, unless otherwise defined by either
* passing a parameter or setting the "org.eclipse.jetty.util.UrlEncoding.charset"
* System property.
+ *
*
* The hashtable either contains String single values, vectors
* of String or arrays of Strings.
+ *
*
* This class is only partially synchronised. In particular, simple
* get operations are not protected from concurrent updates.
+ *
*
* @see java.net.URLEncoder
*/
@@ -103,7 +107,8 @@ public class UrlEncoded extends MultiMap implements Cloneable
}
/* -------------------------------------------------------------- */
- /** Encode Hashtable with % encoding.
+ /** Encode MultiMap with % encoding for UTF8 sequences.
+ * @return the MultiMap as a string with % encoding
*/
public String encode()
{
@@ -111,7 +116,9 @@ public class UrlEncoded extends MultiMap implements Cloneable
}
/* -------------------------------------------------------------- */
- /** Encode Hashtable with % encoding.
+ /** Encode MultiMap with % encoding for arbitrary Charset sequences.
+ * @param charset the charset to use for encoding
+ * @return the MultiMap as a string encoded with % encodings
*/
public String encode(Charset charset)
{
@@ -119,9 +126,12 @@ public class UrlEncoded extends MultiMap implements Cloneable
}
/* -------------------------------------------------------------- */
- /** Encode Hashtable with % encoding.
+ /**
+ * Encode MultiMap with % encoding.
+ * @param charset the charset to encode with
* @param equalsForNullValue if True, then an '=' is always used, even
- * for parameters without a value. e.g. "blah?a=&b=&c=".
+ * for parameters without a value. e.g. "blah?a=&b=&c=".
+ * @return the MultiMap as a string encoded with % encodings
*/
public synchronized String encode(Charset charset, boolean equalsForNullValue)
{
@@ -129,9 +139,12 @@ public class UrlEncoded extends MultiMap implements Cloneable
}
/* -------------------------------------------------------------- */
- /** Encode Hashtable with % encoding.
+ /** Encode MultiMap with % encoding.
+ * @param map the map to encode
+ * @param charset the charset to use for encoding (uses default encoding if null)
* @param equalsForNullValue if True, then an '=' is always used, even
- * for parameters without a value. e.g. "blah?a=&b=&c=".
+ * for parameters without a value. e.g. "blah?a=&b=&c=".
+ * @return the MultiMap as a string encoded with % encodings.
*/
public static String encode(MultiMap map, Charset charset, boolean equalsForNullValue)
{
@@ -190,6 +203,8 @@ public class UrlEncoded extends MultiMap implements Cloneable
/* -------------------------------------------------------------- */
/** Decoded parameters to Map.
* @param content the string containing the encoded parameters
+ * @param map the MultiMap to put parsed query parameters into
+ * @param charset the charset to use for decoding
*/
public static void decodeTo(String content, MultiMap map, String charset)
{
@@ -199,6 +214,8 @@ public class UrlEncoded extends MultiMap implements Cloneable
/* -------------------------------------------------------------- */
/** Decoded parameters to Map.
* @param content the string containing the encoded parameters
+ * @param map the MultiMap to put parsed query parameters into
+ * @param charset the charset to use for decoding
*/
public static void decodeTo(String content, MultiMap map, Charset charset)
{
@@ -282,7 +299,7 @@ public class UrlEncoded extends MultiMap implements Cloneable
/* -------------------------------------------------------------- */
/** Decoded parameters to Map.
- * @param raw the byte[] containing the encoded parameters
+ * @param query the string containing the encoded parameters
* @param offset the offset within raw to decode from
* @param length the length of the section to decode
* @param map the {@link MultiMap} to populate
@@ -398,10 +415,13 @@ public class UrlEncoded extends MultiMap implements Cloneable
}
/* -------------------------------------------------------------- */
- /** Decoded parameters to Map.
+ /** Decoded parameters to MultiMap, using ISO8859-1 encodings.
+ *
* @param in InputSteam to read
* @param map MultiMap to add parameters to
- * @param maxLength maximum number of keys to read or -1 for no limit
+ * @param maxLength maximum length of form to read
+ * @param maxKeys maximum number of keys to read or -1 for no limit
+ * @throws IOException if unable to decode inputstream as ISO8859-1
*/
public static void decode88591To(InputStream in, MultiMap map, int maxLength, int maxKeys)
throws IOException
@@ -499,7 +519,9 @@ public class UrlEncoded extends MultiMap implements Cloneable
/** Decoded parameters to Map.
* @param in InputSteam to read
* @param map MultiMap to add parameters to
- * @param maxLength maximum number of keys to read or -1 for no limit
+ * @param maxLength maximum form length to decode
+ * @param maxKeys the maximum number of keys to read or -1 for no limit
+ * @throws IOException if unable to decode input stream
*/
public static void decodeUtf8To(InputStream in, MultiMap map, int maxLength, int maxKeys)
throws IOException
@@ -637,6 +659,11 @@ public class UrlEncoded extends MultiMap implements Cloneable
/* -------------------------------------------------------------- */
/** Decoded parameters to Map.
* @param in the stream containing the encoded parameters
+ * @param map the MultiMap to decode into
+ * @param charset the charset to use for decoding
+ * @param maxLength the maximum length of the form to decode
+ * @param maxKeys the maximum number of keys to decode
+ * @throws IOException if unable to decode input stream
*/
public static void decodeTo(InputStream in, MultiMap map, String charset, int maxLength, int maxKeys)
throws IOException
@@ -661,6 +688,11 @@ public class UrlEncoded extends MultiMap implements Cloneable
/* -------------------------------------------------------------- */
/** Decoded parameters to Map.
* @param in the stream containing the encoded parameters
+ * @param map the MultiMap to decode into
+ * @param charset the charset to use for decoding
+ * @param maxLength the maximum length of the form to decode
+ * @param maxKeys the maximum number of keys to decode
+ * @throws IOException if unable to decode input stream
*/
public static void decodeTo(InputStream in, MultiMap map, Charset charset, int maxLength, int maxKeys)
throws IOException
@@ -785,6 +817,8 @@ public class UrlEncoded extends MultiMap implements Cloneable
/** Decode String with % encoding.
* This method makes the assumption that the majority of calls
* will need no decoding.
+ * @param encoded the encoded string to decode
+ * @return the decoded string
*/
public static String decodeString(String encoded)
{
@@ -795,6 +829,11 @@ public class UrlEncoded extends MultiMap implements Cloneable
/** Decode String with % encoding.
* This method makes the assumption that the majority of calls
* will need no decoding.
+ * @param encoded the encoded string to decode
+ * @param offset the offset in the encoded string to decode from
+ * @param length the length of characters in the encoded string to decode
+ * @param charset the charset to use for decoding
+ * @return the decoded string
*/
public static String decodeString(String encoded,int offset,int length,Charset charset)
{
@@ -1012,7 +1051,7 @@ public class UrlEncoded extends MultiMap implements Cloneable
/* ------------------------------------------------------------ */
/** Perform URL encoding.
- * @param string
+ * @param string the string to encode
* @return encoded string.
*/
public static String encodeString(String string)
@@ -1022,7 +1061,8 @@ public class UrlEncoded extends MultiMap implements Cloneable
/* ------------------------------------------------------------ */
/** Perform URL encoding.
- * @param string
+ * @param string the string to encode
+ * @param charset the charset to use for encoding
* @return encoded string.
*/
public static String encodeString(String string,Charset charset)
diff --git a/jetty-util/src/main/java/org/eclipse/jetty/util/Utf8Appendable.java b/jetty-util/src/main/java/org/eclipse/jetty/util/Utf8Appendable.java
index bc037439b19..c0912e6df2d 100644
--- a/jetty-util/src/main/java/org/eclipse/jetty/util/Utf8Appendable.java
+++ b/jetty-util/src/main/java/org/eclipse/jetty/util/Utf8Appendable.java
@@ -37,7 +37,7 @@ import org.eclipse.jetty.util.log.Logger;
*
* License information for Bjoern Hoehrmann's code:
*
- * Copyright (c) 2008-2009 Bjoern Hoehrmann
+ * Copyright (c) 2008-2009 Bjoern Hoehrmann <bjoern@hoehrmann.de>
* Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal
* in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
* copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:
diff --git a/jetty-util/src/main/java/org/eclipse/jetty/util/annotation/ManagedAttribute.java b/jetty-util/src/main/java/org/eclipse/jetty/util/annotation/ManagedAttribute.java
index 1422d7b4dac..99e74545523 100644
--- a/jetty-util/src/main/java/org/eclipse/jetty/util/annotation/ManagedAttribute.java
+++ b/jetty-util/src/main/java/org/eclipse/jetty/util/annotation/ManagedAttribute.java
@@ -25,14 +25,13 @@ import java.lang.annotation.RetentionPolicy;
import java.lang.annotation.Target;
/**
- * The @ManagedAttribute annotation is used to indicate that a given method
+ * The @ManagedAttribute annotation is used to indicate that a given method
* exposes a JMX attribute. This annotation is placed always on the reader
* method of a given attribute. Unless it is marked as read-only in the
* configuration of the annotation a corresponding setter is looked for
* following normal naming conventions. For example if this annotation is
* on a method called getFoo() then a method called setFoo() would be looked
* for and if found wired automatically into the jmx attribute.
- *
*/
@Retention(RetentionPolicy.RUNTIME)
@Documented
@@ -42,7 +41,7 @@ public @interface ManagedAttribute
/**
* Description of the Managed Attribute
*
- * @returngit checkout
+ * @return value
*/
String value() default "Not Specified";
diff --git a/jetty-util/src/main/java/org/eclipse/jetty/util/annotation/ManagedObject.java b/jetty-util/src/main/java/org/eclipse/jetty/util/annotation/ManagedObject.java
index 07d9688e045..c29b138e649 100644
--- a/jetty-util/src/main/java/org/eclipse/jetty/util/annotation/ManagedObject.java
+++ b/jetty-util/src/main/java/org/eclipse/jetty/util/annotation/ManagedObject.java
@@ -25,12 +25,11 @@ import java.lang.annotation.RetentionPolicy;
import java.lang.annotation.Target;
/**
- * The @ManagedObject annotation is used on a class at the top level to
+ * The @ManagedObject annotation is used on a class at the top level to
* indicate that it should be exposed as an mbean. It has only one attribute
* to it which is used as the description of the MBean. Should multiple
- * @ManagedObject annotations be found in the chain of influence then the
+ * @ManagedObject annotations be found in the chain of influence then the
* first description is used.
- *
*/
@Retention(RetentionPolicy.RUNTIME)
@Documented
@@ -39,6 +38,7 @@ public @interface ManagedObject
{
/**
* Description of the Managed Object
+ * @return value
*/
String value() default "Not Specified";
diff --git a/jetty-util/src/main/java/org/eclipse/jetty/util/annotation/ManagedOperation.java b/jetty-util/src/main/java/org/eclipse/jetty/util/annotation/ManagedOperation.java
index ae3eb40e4ae..bdc789ff6a4 100644
--- a/jetty-util/src/main/java/org/eclipse/jetty/util/annotation/ManagedOperation.java
+++ b/jetty-util/src/main/java/org/eclipse/jetty/util/annotation/ManagedOperation.java
@@ -25,9 +25,8 @@ import java.lang.annotation.RetentionPolicy;
import java.lang.annotation.Target;
/**
- * The @ManagedOperation annotation is used to indicate that a given method
+ * The @ManagedOperation annotation is used to indicate that a given method
* should be considered a JMX operation.
- *
*/
@Retention(RetentionPolicy.RUNTIME)
@Documented
@@ -36,6 +35,7 @@ public @interface ManagedOperation
{
/**
* Description of the Managed Object
+ * @return value
*/
String value() default "Not Specified";
diff --git a/jetty-util/src/main/java/org/eclipse/jetty/util/annotation/Name.java b/jetty-util/src/main/java/org/eclipse/jetty/util/annotation/Name.java
index c4c678731c6..aab349fb213 100644
--- a/jetty-util/src/main/java/org/eclipse/jetty/util/annotation/Name.java
+++ b/jetty-util/src/main/java/org/eclipse/jetty/util/annotation/Name.java
@@ -39,11 +39,13 @@ public @interface Name
{
/**
* the name of the parameter
+ * @return the value
*/
String value();
/**
* the description of the parameter
+ * @return the description
*/
String description() default "";
}
diff --git a/jetty-util/src/main/java/org/eclipse/jetty/util/component/Container.java b/jetty-util/src/main/java/org/eclipse/jetty/util/component/Container.java
index bbb95a627e4..a75d459366d 100644
--- a/jetty-util/src/main/java/org/eclipse/jetty/util/component/Container.java
+++ b/jetty-util/src/main/java/org/eclipse/jetty/util/component/Container.java
@@ -20,6 +20,9 @@ package org.eclipse.jetty.util.component;
import java.util.Collection;
+/**
+ * A Container
+ */
public interface Container
{
/* ------------------------------------------------------------ */
@@ -39,6 +42,7 @@ public interface Container
/**
* @param clazz the class of the beans
* @return the list of beans of the given class (or subclass)
+ * @param the Bean type
* @see #getBeans()
*/
public Collection getBeans(Class clazz);
@@ -46,12 +50,14 @@ public interface Container
/**
* @param clazz the class of the bean
* @return the first bean of a specific class (or subclass), or null if no such bean exist
+ * @param the Bean type
*/
public T getBean(Class clazz);
/**
* Removes the given bean.
* If the bean is-a {@link Listener}, then also do an implicit {@link #removeEventListener(Listener)}.
+ * @param o the bean to remove
* @return whether the bean was removed
*/
public boolean removeBean(Object o);
@@ -59,14 +65,14 @@ public interface Container
/**
* Add an event listener.
* @see Container#addBean(Object)
- * @param listener
+ * @param listener the listener to add
*/
public void addEventListener(Listener listener);
/**
* Remove an event listener.
* @see Container#removeBean(Object)
- * @param listener
+ * @param listener the listener to remove
*/
public void removeEventListener(Listener listener);
diff --git a/jetty-util/src/main/java/org/eclipse/jetty/util/component/ContainerLifeCycle.java b/jetty-util/src/main/java/org/eclipse/jetty/util/component/ContainerLifeCycle.java
index 772c03fd2aa..060a3d1344a 100644
--- a/jetty-util/src/main/java/org/eclipse/jetty/util/component/ContainerLifeCycle.java
+++ b/jetty-util/src/main/java/org/eclipse/jetty/util/component/ContainerLifeCycle.java
@@ -124,8 +124,8 @@ public class ContainerLifeCycle extends AbstractLifeCycle implements Container,
/**
* Starts the given lifecycle.
*
- * @param l
- * @throws Exception
+ * @param l the lifecycle to start
+ * @throws Exception if unable to start lifecycle
*/
protected void start(LifeCycle l) throws Exception
{
@@ -135,8 +135,8 @@ public class ContainerLifeCycle extends AbstractLifeCycle implements Container,
/**
* Stops the given lifecycle.
*
- * @param l
- * @throws Exception
+ * @param l the lifecycle to stop
+ * @throws Exception if unable to stop the lifecycle
*/
protected void stop(LifeCycle l) throws Exception
{
@@ -329,11 +329,11 @@ public class ContainerLifeCycle extends AbstractLifeCycle implements Container,
/* ------------------------------------------------------------ */
/** Add a managed lifecycle.
- * This is a conveniance method that uses addBean(lifecycle,true)
+ *
This is a convenience method that uses addBean(lifecycle,true)
* and then ensures that the added bean is started iff this container
* is running. Exception from nested calls to start are caught and
* wrapped as RuntimeExceptions
- * @param lifecycle
+ * @param lifecycle the managed lifecycle to add
*/
public void addManaged(LifeCycle lifecycle)
{
diff --git a/jetty-util/src/main/java/org/eclipse/jetty/util/component/LifeCycle.java b/jetty-util/src/main/java/org/eclipse/jetty/util/component/LifeCycle.java
index 0713c6e7613..45c7bf02306 100644
--- a/jetty-util/src/main/java/org/eclipse/jetty/util/component/LifeCycle.java
+++ b/jetty-util/src/main/java/org/eclipse/jetty/util/component/LifeCycle.java
@@ -26,7 +26,7 @@ import org.eclipse.jetty.util.annotation.ManagedOperation;
/* ------------------------------------------------------------ */
/**
* The lifecycle interface for generic components.
- *
+ *
* Classes implementing this interface have a defined life cycle
* defined by the methods of this interface.
*
diff --git a/jetty-util/src/main/java/org/eclipse/jetty/util/log/Logger.java b/jetty-util/src/main/java/org/eclipse/jetty/util/log/Logger.java
index 9da7788e897..65ec959ae01 100644
--- a/jetty-util/src/main/java/org/eclipse/jetty/util/log/Logger.java
+++ b/jetty-util/src/main/java/org/eclipse/jetty/util/log/Logger.java
@@ -117,6 +117,7 @@ public interface Logger
/**
* Ignore an exception.
*
This should be used rather than an empty catch block.
+ * @param ignored the throwable to log as ignored
*/
public void ignore(Throwable ignored);
}
diff --git a/jetty-util/src/main/java/org/eclipse/jetty/util/log/StdErrLog.java b/jetty-util/src/main/java/org/eclipse/jetty/util/log/StdErrLog.java
index 7a322f28ac5..505d240f773 100644
--- a/jetty-util/src/main/java/org/eclipse/jetty/util/log/StdErrLog.java
+++ b/jetty-util/src/main/java/org/eclipse/jetty/util/log/StdErrLog.java
@@ -37,10 +37,10 @@ import org.eclipse.jetty.util.annotation.ManagedObject;
*
* - ${name|hierarchy}.LEVEL=(ALL|DEBUG|INFO|WARN|OFF)
* -
- * Sets the level that the Logger should log at.
- * Names can be a package name, or a fully qualified class name.
- * Default: INFO
- *
+ * Sets the level that the Logger should log at.
+ * Names can be a package name, or a fully qualified class name.
+ * Default: INFO
+ *
* Examples:
*
* - org.eclipse.jetty.LEVEL=WARN
@@ -56,35 +56,35 @@ import org.eclipse.jetty.util.annotation.ManagedObject;
* - ${name}.SOURCE=(true|false)
* -
* Logger specific, attempt to print the java source file name and line number
- * where the logging event originated from.
+ * where the logging event originated from.
* Name must be a fully qualified class name (package name hierarchy is not supported
- * by this configurable)
- * Warning: this is a slow operation and will have an impact on performance!
+ * by this configurable)
+ * Warning: this is a slow operation and will have an impact on performance!
* Default: false
*
*
* - ${name}.STACKS=(true|false)
* -
- * Logger specific, control the display of stacktraces.
+ * Logger specific, control the display of stacktraces.
* Name must be a fully qualified class name (package name hierarchy is not supported
- * by this configurable)
+ * by this configurable)
* Default: true
*
*
* - org.eclipse.jetty.util.log.stderr.SOURCE=(true|false)
* - Special Global Configuration, attempt to print the java source file name and line number
- * where the logging event originated from.
+ * where the logging event originated from.
* Default: false
*
*
* - org.eclipse.jetty.util.log.stderr.LONG=(true|false)
* - Special Global Configuration, when true, output logging events to STDERR using
- * long form, fully qualified class names. when false, use abbreviated package names
+ * long form, fully qualified class names. when false, use abbreviated package names
* Default: false
*
* - org.eclipse.jetty.util.log.stderr.ESCAPE=(true|false)
* - Global Configuration, when true output logging events to STDERR are always
- * escaped so that control characters are replaced with '?"; '\r' with '<' and '\n' replaced '|'
+ * escaped so that control characters are replaced with '?"; '\r' with '<' and '\n' replaced '|'
* Default: true
*
*
@@ -339,7 +339,6 @@ public class StdErrLog extends AbstractLogger
/**
* Condenses a classname by stripping down the package name to just the first character of each package name
* segment.Configured
- *
*
*
* Examples:
diff --git a/jetty-util/src/main/java/org/eclipse/jetty/util/resource/FileResource.java b/jetty-util/src/main/java/org/eclipse/jetty/util/resource/FileResource.java
index eeacc274353..7f9c629e2e6 100644
--- a/jetty-util/src/main/java/org/eclipse/jetty/util/resource/FileResource.java
+++ b/jetty-util/src/main/java/org/eclipse/jetty/util/resource/FileResource.java
@@ -346,7 +346,7 @@ public class FileResource extends Resource
/* ------------------------------------------------------------ */
/**
- * @param o
+ * @param o the object to compare against this instance
* @return true of the object o is a {@link FileResource} pointing to the same file as this resource.
*/
@Override
diff --git a/jetty-util/src/main/java/org/eclipse/jetty/util/resource/JarFileResource.java b/jetty-util/src/main/java/org/eclipse/jetty/util/resource/JarFileResource.java
index 310df4a761c..32a83568c4a 100644
--- a/jetty-util/src/main/java/org/eclipse/jetty/util/resource/JarFileResource.java
+++ b/jetty-util/src/main/java/org/eclipse/jetty/util/resource/JarFileResource.java
@@ -381,7 +381,7 @@ class JarFileResource extends JarResource
/**
* Take a Resource that possibly might use URLConnection caching
* and turn it into one that doesn't.
- * @param resource
+ * @param resource the JarFileResource to obtain without URLConnection caching.
* @return the non-caching resource
*/
public static Resource getNonCachingResource (Resource resource)
@@ -399,9 +399,9 @@ class JarFileResource extends JarResource
/**
* Check if this jar:file: resource is contained in the
* named resource. Eg jar:file:///a/b/c/foo.jar!/x.html isContainedIn file:///a/b/c/foo.jar
- * @param resource
+ * @param resource the resource to test for
* @return true if resource is contained in the named resource
- * @throws MalformedURLException
+ * @throws MalformedURLException if unable to process is contained due to invalid URL format
*/
@Override
public boolean isContainedIn (Resource resource)
diff --git a/jetty-util/src/main/java/org/eclipse/jetty/util/resource/PathResource.java b/jetty-util/src/main/java/org/eclipse/jetty/util/resource/PathResource.java
index 792e43a1378..e56c7b5d81f 100644
--- a/jetty-util/src/main/java/org/eclipse/jetty/util/resource/PathResource.java
+++ b/jetty-util/src/main/java/org/eclipse/jetty/util/resource/PathResource.java
@@ -89,11 +89,33 @@ public class PathResource extends Resource
return null;
}
+ /**
+ * Construct a new PathResource from a File object.
+ *
+ * An invocation of this convenience constructor of the form.
+ *
+ *
+ * new PathResource(file);
+ *
+ *
+ * behaves in exactly the same way as the expression
+ *
+ *
+ * new PathResource(file.toPath());
+ *
+
+ * @param file the file to use
+ */
public PathResource(File file)
{
this(file.toPath());
}
+ /**
+ * Construct a new PathResource from a Path object.
+ *
+ * @param path the path to use
+ */
public PathResource(Path path)
{
this.path = path.toAbsolutePath();
@@ -101,6 +123,14 @@ public class PathResource extends Resource
this.alias = checkAliasPath(path);
}
+ /**
+ * Construct a new PathResource from a URI object.
+ *
+ * Must be an absolute URI using the file scheme.
+ *
+ * @param uri the URI to build this PathResource from.
+ * @throws IOException if unable to construct the PathResource from the URI.
+ */
public PathResource(URI uri) throws IOException
{
if (!uri.isAbsolute())
@@ -137,6 +167,25 @@ public class PathResource extends Resource
this.alias = checkAliasPath(path);
}
+ /**
+ * Create a new PathResource from a provided URL object.
+ *
+ * An invocation of this convenience constructor of the form.
+ *
+ *
+ * new PathResource(url);
+ *
+ *
+ * behaves in exactly the same way as the expression
+ *
+ *
+ * new PathResource(url.toURI());
+ *
+ *
+ * @param url the url to attempt to create PathResource from
+ * @throws IOException if URL doesn't point to a location that can be transformed to a PathResource
+ * @throws URISyntaxException if the provided URL was malformed
+ */
public PathResource(URL url) throws IOException, URISyntaxException
{
this(url.toURI());
@@ -225,7 +274,10 @@ public class PathResource extends Resource
return path.toFile();
}
- public Path getPath() throws IOException
+ /**
+ * @return the {@link Path} of the resource
+ */
+ public Path getPath()
{
return path;
}
@@ -324,6 +376,11 @@ public class PathResource extends Resource
return this.alias!=null;
}
+ /**
+ * The Alias as a Path.
+ *
+ * @return the alias as a path.
+ */
public Path getAliasPath()
{
return this.alias;
diff --git a/jetty-util/src/main/java/org/eclipse/jetty/util/resource/Resource.java b/jetty-util/src/main/java/org/eclipse/jetty/util/resource/Resource.java
index c06390704f7..1e4823bd40b 100644
--- a/jetty-util/src/main/java/org/eclipse/jetty/util/resource/Resource.java
+++ b/jetty-util/src/main/java/org/eclipse/jetty/util/resource/Resource.java
@@ -39,6 +39,7 @@ import org.eclipse.jetty.util.IO;
import org.eclipse.jetty.util.Loader;
import org.eclipse.jetty.util.StringUtil;
import org.eclipse.jetty.util.URIUtil;
+import org.eclipse.jetty.util.UrlEncoded;
import org.eclipse.jetty.util.log.Log;
import org.eclipse.jetty.util.log.Logger;
@@ -61,7 +62,7 @@ public abstract class Resource implements ResourceFactory, Closeable
/**
* Change the default setting for url connection caches.
* Subsequent URLConnections will use this default.
- * @param useCaches
+ * @param useCaches true to enable URL connection caches, false otherwise.
*/
public static void setDefaultUseCaches (boolean useCaches)
{
@@ -257,6 +258,8 @@ public abstract class Resource implements ResourceFactory, Closeable
/* ------------------------------------------------------------ */
/** Find a classpath resource.
+ * @param resource the relative name of the resource
+ * @return Resource or null
*/
public static Resource newClassPathResource(String resource)
{
@@ -320,43 +323,52 @@ public abstract class Resource implements ResourceFactory, Closeable
/* ------------------------------------------------------------ */
/**
- * Returns true if the respresened resource exists.
+ * @return true if the represented resource exists.
*/
public abstract boolean exists();
/* ------------------------------------------------------------ */
/**
- * Returns true if the respresenetd resource is a container/directory.
- * If the resource is not a file, resources ending with "/" are
+ * @return true if the represented resource is a container/directory.
+ * if the resource is not a file, resources ending with "/" are
* considered directories.
*/
public abstract boolean isDirectory();
/* ------------------------------------------------------------ */
/**
- * Returns the last modified time
+ * Time resource was last modified.
+ *
+ * @return the last modified time as milliseconds since unix epoch
*/
public abstract long lastModified();
/* ------------------------------------------------------------ */
/**
- * Return the length of the resource
+ * Length of the resource.
+ *
+ * @return the length of the resource
*/
public abstract long length();
/* ------------------------------------------------------------ */
/**
- * Returns an URL representing the given resource
+ * URL representing the resource.
+ *
+ * @return an URL representing the given resource
+ * @deprecated use {{@link #getURI()}.toURL() instead.
*/
- // TODO: should deprecate this one and only use getURI()
+ @Deprecated
public abstract URL getURL();
/* ------------------------------------------------------------ */
/**
- * Returns an URI representing the given resource
+ * URI representing the resource.
+ *
+ * @return an URI representing the given resource
*/
public URI getURI()
{
@@ -373,8 +385,11 @@ public abstract class Resource implements ResourceFactory, Closeable
/* ------------------------------------------------------------ */
/**
- * Returns an File representing the given resource or NULL if this
+ * File representing the given resource.
+ *
+ * @return an File representing the given resource or NULL if this
* is not possible.
+ * @throws IOException if unable to get the resource due to permissions
*/
public abstract File getFile()
throws IOException;
@@ -382,47 +397,60 @@ public abstract class Resource implements ResourceFactory, Closeable
/* ------------------------------------------------------------ */
/**
- * Returns the name of the resource
+ * The name of the resource.
+ *
+ * @return the name of the resource
*/
public abstract String getName();
/* ------------------------------------------------------------ */
/**
- * Returns an input stream to the resource
+ * Input stream to the resource
+ *
+ * @return an input stream to the resource
+ * @throws IOException if unable to open the input stream
*/
public abstract InputStream getInputStream()
- throws java.io.IOException;
+ throws IOException;
/* ------------------------------------------------------------ */
/**
- * Returns an readable bytechannel to the resource or null if one is not available.
+ * Readable ByteChannel for the resource.
+ *
+ * @return an readable bytechannel to the resource or null if one is not available.
+ * @throws IOException if unable to open the readable bytechannel for the resource.
*/
public abstract ReadableByteChannel getReadableByteChannel()
- throws java.io.IOException;
+ throws IOException;
/* ------------------------------------------------------------ */
/**
* Deletes the given resource
+ * @return true if resource was found and successfully deleted, false if resource didn't exist or was unable to
+ * be deleted.
+ * @throws SecurityException if unable to delete due to permissions
*/
- // TODO: can throw IOException
public abstract boolean delete()
throws SecurityException;
/* ------------------------------------------------------------ */
/**
* Rename the given resource
+ * @param dest the destination name for the resource
+ * @return true if the resource was renamed, false if the resource didn't exist or was unable to be renamed.
+ * @throws SecurityException if unable to rename due to permissions
*/
- // TODO: can throw IOException
- public abstract boolean renameTo( Resource dest)
+ public abstract boolean renameTo(Resource dest)
throws SecurityException;
/* ------------------------------------------------------------ */
/**
- * Returns a list of resource names contained in the given resource
- * The resource names are not URL encoded.
+ * list of resource names contained in the given resource.
+ *
+ * @return a list of resource names contained in the given resource.
+ * Note: The resource names are not URL encoded.
*/
- // TODO: can throw IOException
public abstract String[] list();
/* ------------------------------------------------------------ */
@@ -430,6 +458,9 @@ public abstract class Resource implements ResourceFactory, Closeable
* Returns the resource contained inside the current resource with the
* given name.
* @param path The path segment to add, which is not encoded
+ * @return the Resource for the resolved path within this Resource.
+ * @throws IOException if unable to resolve the path
+ * @throws MalformedURLException if the resolution of the path fails because the input path parameter is malformed.
*/
public abstract Resource addPath(String path)
throws IOException,MalformedURLException;
@@ -457,26 +488,36 @@ public abstract class Resource implements ResourceFactory, Closeable
/* ------------------------------------------------------------ */
/**
- * @deprecated
+ * @param uri the uri to encode
+ * @return null (this is deprecated)
+ * @deprecated use {@link URIUtil} or {@link UrlEncoded} instead
*/
+ @Deprecated
public String encode(String uri)
{
return null;
}
/* ------------------------------------------------------------ */
+ // FIXME: this appears to not be used
+ @SuppressWarnings("javadoc")
public Object getAssociate()
{
return _associate;
}
/* ------------------------------------------------------------ */
+ // FIXME: this appear to not be used
+ @SuppressWarnings("javadoc")
public void setAssociate(Object o)
{
_associate=o;
}
/* ------------------------------------------------------------ */
+ /**
+ * @return true if this Resource is an alias to another real Resource
+ */
public boolean isAlias()
{
return getAlias()!=null;
@@ -496,6 +537,7 @@ public abstract class Resource implements ResourceFactory, Closeable
* @param base The base URL
* @param parent True if the parent directory should be included
* @return String of HTML
+ * @throws IOException if unable to get the list of resources as HTML
*/
public String getListHTML(String base,boolean parent)
throws IOException
@@ -623,9 +665,10 @@ public abstract class Resource implements ResourceFactory, Closeable
/* ------------------------------------------------------------ */
/**
- * @param out
+ * @param out the output stream to write to
* @param start First byte to write
* @param count Bytes to write or -1 for all of them.
+ * @throws IOException if unable to copy the Resource to the output
*/
public void writeTo(OutputStream out,long start,long count)
throws IOException
@@ -641,11 +684,20 @@ public abstract class Resource implements ResourceFactory, Closeable
}
/* ------------------------------------------------------------ */
+ /**
+ * Copy the Resource to the new destination file.
+ *
+ * Will not replace existing destination file.
+ *
+ * @param destination the destination file to create
+ * @throws IOException if unable to copy the resource
+ */
public void copyTo(File destination)
throws IOException
{
if (destination.exists())
- throw new IllegalArgumentException(destination+" exists");
+ throw new IllegalArgumentException(destination + " exists");
+
try (OutputStream out = new FileOutputStream(destination))
{
writeTo(out,0,-1);
@@ -653,6 +705,11 @@ public abstract class Resource implements ResourceFactory, Closeable
}
/* ------------------------------------------------------------ */
+ /**
+ * Generate a weak ETag reference for this Resource.
+ *
+ * @return the weak ETag reference for this resource.
+ */
public String getWeakETag()
{
try
@@ -709,7 +766,7 @@ public abstract class Resource implements ResourceFactory, Closeable
/** Generate a properly encoded URL from a {@link File} instance.
* @param file Target file.
* @return URL of the target file.
- * @throws MalformedURLException
+ * @throws MalformedURLException if unable to convert File to URL
*/
public static URL toURL(File file) throws MalformedURLException
{
diff --git a/jetty-util/src/main/java/org/eclipse/jetty/util/resource/ResourceCollection.java b/jetty-util/src/main/java/org/eclipse/jetty/util/resource/ResourceCollection.java
index 960956f56a4..e72ddaeebfa 100644
--- a/jetty-util/src/main/java/org/eclipse/jetty/util/resource/ResourceCollection.java
+++ b/jetty-util/src/main/java/org/eclipse/jetty/util/resource/ResourceCollection.java
@@ -248,10 +248,10 @@ public class ResourceCollection extends Resource
/* ------------------------------------------------------------ */
/**
- * @param path
+ * @param path the path to look for
* @return the resource(file) if found, returns a list of resource dirs if its a dir, else null.
- * @throws IOException
- * @throws MalformedURLException
+ * @throws IOException if unable to look for path
+ * @throws MalformedURLException if failed to look for path due to url issue
*/
protected Object findResource(String path) throws IOException, MalformedURLException
{
diff --git a/jetty-util/src/main/java/org/eclipse/jetty/util/resource/URLResource.java b/jetty-util/src/main/java/org/eclipse/jetty/util/resource/URLResource.java
index a2a438c9871..537baa58792 100644
--- a/jetty-util/src/main/java/org/eclipse/jetty/util/resource/URLResource.java
+++ b/jetty-util/src/main/java/org/eclipse/jetty/util/resource/URLResource.java
@@ -221,9 +221,11 @@ public class URLResource extends Resource
* the url protocol. Eg JarURLConnection does not reuse inputstreams.
*
* @param resetConnection if true the connection field is set to null
+ * @return the inputstream for this resource
+ * @throws IOException if unable to open the input stream
*/
protected synchronized InputStream getInputStream(boolean resetConnection)
- throws java.io.IOException
+ throws IOException
{
if (!checkConnection())
throw new IOException( "Invalid resource");
diff --git a/jetty-util/src/main/java/org/eclipse/jetty/util/security/CertificateValidator.java b/jetty-util/src/main/java/org/eclipse/jetty/util/security/CertificateValidator.java
index cf4eeb377ef..22ffd7737a2 100644
--- a/jetty-util/src/main/java/org/eclipse/jetty/util/security/CertificateValidator.java
+++ b/jetty-util/src/main/java/org/eclipse/jetty/util/security/CertificateValidator.java
@@ -72,8 +72,8 @@ public class CertificateValidator
/**
* creates an instance of the certificate validator
*
- * @param trustStore
- * @param crls
+ * @param trustStore the truststore to use
+ * @param crls the Certificate Revocation List to use
*/
public CertificateValidator(KeyStore trustStore, Collection crls)
{
@@ -89,8 +89,8 @@ public class CertificateValidator
/**
* validates all aliases inside of a given keystore
*
- * @param keyStore
- * @throws CertificateException
+ * @param keyStore the keystore to validate
+ * @throws CertificateException if keystore error and unable to validate
*/
public void validate( KeyStore keyStore ) throws CertificateException
{
@@ -116,10 +116,10 @@ public class CertificateValidator
/**
* validates a specific alias inside of the keystore being passed in
*
- * @param keyStore
- * @param keyAlias
+ * @param keyStore the keystore to validate
+ * @param keyAlias the keyalias in the keystore to valid with
* @return the keyAlias if valid
- * @throws CertificateException
+ * @throws CertificateException if keystore error and unable to validate
*/
public String validate(KeyStore keyStore, String keyAlias) throws CertificateException
{
@@ -146,9 +146,9 @@ public class CertificateValidator
/**
* validates a specific certificate inside of the keystore being passed in
*
- * @param keyStore
- * @param cert
- * @throws CertificateException
+ * @param keyStore the keystore to validate against
+ * @param cert the certificate to validate
+ * @throws CertificateException if keystore error and unable to validate
*/
public void validate(KeyStore keyStore, Certificate cert) throws CertificateException
{
diff --git a/jetty-util/src/main/java/org/eclipse/jetty/util/security/Constraint.java b/jetty-util/src/main/java/org/eclipse/jetty/util/security/Constraint.java
index f159ed58f1b..72fb579f21c 100644
--- a/jetty-util/src/main/java/org/eclipse/jetty/util/security/Constraint.java
+++ b/jetty-util/src/main/java/org/eclipse/jetty/util/security/Constraint.java
@@ -21,13 +21,10 @@ package org.eclipse.jetty.util.security;
import java.io.Serializable;
import java.util.Arrays;
-/* ------------------------------------------------------------ */
/**
* Constraint
*
* Describe an auth and/or data constraint.
- *
- *
*/
public class Constraint implements Cloneable, Serializable
{
@@ -93,10 +90,10 @@ public class Constraint implements Cloneable, Serializable
/* ------------------------------------------------------------ */
/**
- * Conveniance Constructor.
+ * Convenience Constructor.
*
- * @param name
- * @param role
+ * @param name the name
+ * @param role the role
*/
public Constraint(String name, String role)
{
@@ -113,7 +110,7 @@ public class Constraint implements Cloneable, Serializable
/* ------------------------------------------------------------ */
/**
- * @param name
+ * @param name the name
*/
public void setName(String name)
{
@@ -172,7 +169,7 @@ public class Constraint implements Cloneable, Serializable
/* ------------------------------------------------------------ */
/**
- * @param role
+ * @param role the role
* @return True if the constraint contains the role.
*/
public boolean hasRole(String role)
@@ -212,7 +209,7 @@ public class Constraint implements Cloneable, Serializable
/* ------------------------------------------------------------ */
/**
- * @param c Data constrain indicator: 0=DC+NONE, 1=DC_INTEGRAL &
+ * @param c Data constrain indicator: 0=DC+NONE, 1=DC_INTEGRAL &
* 2=DC_CONFIDENTIAL
*/
public void setDataConstraint(int c)
@@ -223,7 +220,7 @@ public class Constraint implements Cloneable, Serializable
/* ------------------------------------------------------------ */
/**
- * @return Data constrain indicator: 0=DC+NONE, 1=DC_INTEGRAL &
+ * @return Data constrain indicator: 0=DC+NONE, 1=DC_INTEGRAL &
* 2=DC_CONFIDENTIAL
*/
public int getDataConstraint()
diff --git a/jetty-util/src/main/java/org/eclipse/jetty/util/security/Password.java b/jetty-util/src/main/java/org/eclipse/jetty/util/security/Password.java
index 781adcdeab1..27a74f7e409 100644
--- a/jetty-util/src/main/java/org/eclipse/jetty/util/security/Password.java
+++ b/jetty-util/src/main/java/org/eclipse/jetty/util/security/Password.java
@@ -245,10 +245,6 @@ public class Password extends Credential
return new Password(passwd);
}
- /* ------------------------------------------------------------ */
- /**
- * @param arg
- */
public static void main(String[] arg)
{
if (arg.length != 1 && arg.length != 2)
diff --git a/jetty-util/src/main/java/org/eclipse/jetty/util/ssl/AliasedX509ExtendedKeyManager.java b/jetty-util/src/main/java/org/eclipse/jetty/util/ssl/AliasedX509ExtendedKeyManager.java
index 8dbe305ab7f..c7699991f4d 100644
--- a/jetty-util/src/main/java/org/eclipse/jetty/util/ssl/AliasedX509ExtendedKeyManager.java
+++ b/jetty-util/src/main/java/org/eclipse/jetty/util/ssl/AliasedX509ExtendedKeyManager.java
@@ -43,7 +43,7 @@ public class AliasedX509ExtendedKeyManager extends X509ExtendedKeyManager
* Construct KeyManager instance
* @param keyAlias Alias of the key to be selected
* @param keyManager Instance of KeyManager to be wrapped
- * @throws Exception
+ * @throws Exception if unable to create X509ExtendedKeyManager
*/
public AliasedX509ExtendedKeyManager(X509ExtendedKeyManager keyManager, String keyAlias) throws Exception
{
diff --git a/jetty-util/src/main/java/org/eclipse/jetty/util/ssl/SniX509ExtendedKeyManager.java b/jetty-util/src/main/java/org/eclipse/jetty/util/ssl/SniX509ExtendedKeyManager.java
index 74f317ba01a..be3ae9c1fd2 100644
--- a/jetty-util/src/main/java/org/eclipse/jetty/util/ssl/SniX509ExtendedKeyManager.java
+++ b/jetty-util/src/main/java/org/eclipse/jetty/util/ssl/SniX509ExtendedKeyManager.java
@@ -48,8 +48,8 @@ public class SniX509ExtendedKeyManager extends X509ExtendedKeyManager
/**
* Construct KeyManager instance
* @param keyManager Instance of KeyManager to be wrapped
- * @param dftAlias Alias of the key to be selected if no SNI selection
- * @throws Exception
+ * @param alias Alias of the key to be selected if no SNI selection
+ * @throws Exception if unable to create X509ExtendedKeyManager
*/
public SniX509ExtendedKeyManager(X509ExtendedKeyManager keyManager,String alias) throws Exception
{
diff --git a/jetty-util/src/main/java/org/eclipse/jetty/util/ssl/SslContextFactory.java b/jetty-util/src/main/java/org/eclipse/jetty/util/ssl/SslContextFactory.java
index 5e1b2124a93..6102d1c0020 100644
--- a/jetty-util/src/main/java/org/eclipse/jetty/util/ssl/SslContextFactory.java
+++ b/jetty-util/src/main/java/org/eclipse/jetty/util/ssl/SslContextFactory.java
@@ -642,7 +642,7 @@ public class SslContextFactory extends AbstractLifeCycle
/**
* @param password
* The password for the key store. If null is passed then
- * the {@link Password#getPassword(String, String, String) is used to
+ * the {@link Password#getPassword(String, String, String)} is used to
* obtain a password either from the "org.eclipse.jetty.ssl.password"
* System property or by prompting for manual entry.
*/
@@ -659,7 +659,7 @@ public class SslContextFactory extends AbstractLifeCycle
* @param password
* The password (if any) for the specific key within the key store.
* If null is passed then
- * the {@link Password#getPassword(String, String, String) is used to
+ * the {@link Password#getPassword(String, String, String)} is used to
* obtain a password either from the "org.eclipse.jetty.ssl.keypassword"
* System property or by prompting for manual entry.
*/
@@ -674,7 +674,7 @@ public class SslContextFactory extends AbstractLifeCycle
/**
* @param password
* The password for the trust store. If null is passed then
- * the {@link Password#getPassword(String, String, String) is used to
+ * the {@link Password#getPassword(String, String, String)} is used to
* obtain a password either from the "org.eclipse.jetty.ssl.password"
* System property or by prompting for manual entry.
*/
@@ -887,7 +887,8 @@ public class SslContextFactory extends AbstractLifeCycle
/**
* Override this method to provide alternate way to load a keystore.
- *
+ *
+ * @param resource the resource to load the keystore from
* @return the key store instance
* @throws Exception if the keystore cannot be loaded
*/
@@ -898,7 +899,8 @@ public class SslContextFactory extends AbstractLifeCycle
/**
* Override this method to provide alternate way to load a truststore.
- *
+ *
+ * @param resource the resource to load the truststore from
* @return the key store instance
* @throws Exception if the truststore cannot be loaded
*/
@@ -1317,7 +1319,7 @@ public class SslContextFactory extends AbstractLifeCycle
/**
* Factory method for "scratch" {@link SSLEngine}s, usually only used for retrieving configuration
* information such as the application buffer size or the list of protocols/ciphers.
- *
+ *
* This method should not be used for creating {@link SSLEngine}s that are used in actual socket
* communication.
*
@@ -1351,17 +1353,17 @@ public class SslContextFactory extends AbstractLifeCycle
/**
* Server-side only factory method for creating {@link SSLEngine}s.
- *
+ *
* If the given {@code address} is null, it is equivalent to {@link #newSSLEngine()}, otherwise
* {@link #newSSLEngine(String, int)} is called.
- *
+ *
* If {@link #getNeedClientAuth()} is {@code true}, then the host name is passed to
* {@link #newSSLEngine(String, int)}, possibly incurring in a reverse DNS lookup, which takes time
* and may hang the selector (since this method is usually called by the selector thread).
- *
+ *
* Otherwise, the host address is passed to {@link #newSSLEngine(String, int)} without DNS lookup
* penalties.
- *
+ *
* Clients that wish to create {@link SSLEngine} instances must use {@link #newSSLEngine(String, int)}.
*
* @param address the remote peer address
diff --git a/jetty-util/src/main/java/org/eclipse/jetty/util/statistic/CounterStatistic.java b/jetty-util/src/main/java/org/eclipse/jetty/util/statistic/CounterStatistic.java
index 23ce97eba7b..cb8dd194f11 100644
--- a/jetty-util/src/main/java/org/eclipse/jetty/util/statistic/CounterStatistic.java
+++ b/jetty-util/src/main/java/org/eclipse/jetty/util/statistic/CounterStatistic.java
@@ -54,6 +54,7 @@ public class CounterStatistic
/* ------------------------------------------------------------ */
/**
* @param delta the amount to add to the count
+ * @return the new value
*/
public long add(final long delta)
{
@@ -68,6 +69,8 @@ public class CounterStatistic
/* ------------------------------------------------------------ */
/**
+ * increment the value by one
+ * @return the new value, post increment
*/
public long increment()
{
@@ -76,6 +79,8 @@ public class CounterStatistic
/* ------------------------------------------------------------ */
/**
+ * decrement by 1
+ * @return the new value, post-decrement
*/
public long decrement()
{
diff --git a/jetty-util/src/main/java/org/eclipse/jetty/util/statistic/SampleStatistic.java b/jetty-util/src/main/java/org/eclipse/jetty/util/statistic/SampleStatistic.java
index 2f106f75ec0..4d446838dc1 100644
--- a/jetty-util/src/main/java/org/eclipse/jetty/util/statistic/SampleStatistic.java
+++ b/jetty-util/src/main/java/org/eclipse/jetty/util/statistic/SampleStatistic.java
@@ -23,23 +23,20 @@ import java.util.concurrent.atomic.AtomicLong;
import org.eclipse.jetty.util.Atomics;
-/* ------------------------------------------------------------ */
/**
* SampledStatistics
*
- * Provides max, total, mean, count, variance, and standard
- * deviation of continuous sequence of samples.
+ * Provides max, total, mean, count, variance, and standard deviation of continuous sequence of samples.
*
- * Calculates estimates of mean, variance, and standard deviation
- * characteristics of a sample using a non synchronized
- * approximation of the on-line algorithm presented
- * in Donald Knuth's Art of Computer Programming, Volume 2,
- * Seminumerical Algorithms, 3rd edition, page 232,
- * Boston: Addison-Wesley. that cites a 1962 paper by B.P. Welford
- * that can be found by following the link http://www.jstor.org/pss/1266577
+ * Calculates estimates of mean, variance, and standard deviation characteristics of a sample using a non synchronized
+ * approximation of the on-line algorithm presented in Donald Knuth's Art of Computer Programming, Volume 2,
+ * Seminumerical Algorithms, 3rd edition, page 232, Boston: Addison-Wesley. that cites a 1962 paper by B.P. Welford that
+ * can be found by following Note on a Method for Calculating Corrected Sums
+ * of Squares and Products
*
- * This algorithm is also described in Wikipedia at
- * http://en.wikipedia.org/w/index.php?title=Algorithms_for_calculating_variance§ion=4#On-line_algorithm
+ * This algorithm is also described in Wikipedia at
+ * Algorithms for calculating variance
*/
public class SampleStatistic
{
diff --git a/jetty-util/src/main/java/org/eclipse/jetty/util/thread/ExecutorThreadPool.java b/jetty-util/src/main/java/org/eclipse/jetty/util/thread/ExecutorThreadPool.java
index 6f46db277e1..2ee3f58710f 100644
--- a/jetty-util/src/main/java/org/eclipse/jetty/util/thread/ExecutorThreadPool.java
+++ b/jetty-util/src/main/java/org/eclipse/jetty/util/thread/ExecutorThreadPool.java
@@ -65,7 +65,7 @@ public class ExecutorThreadPool extends AbstractLifeCycle implements ThreadPool,
/* ------------------------------------------------------------ */
/**
* Wraps an {@link ThreadPoolExecutor}.
- * Max pool size is 256, pool thread timeout after 60 seconds, and core pool size is 32 when queueSize >= 0.
+ * Max pool size is 256, pool thread timeout after 60 seconds, and core pool size is 32 when queueSize >= 0.
* @param queueSize can be -1 for using an unbounded {@link LinkedBlockingQueue}, 0 for using a
* {@link SynchronousQueue}, greater than 0 for using a {@link ArrayBlockingQueue} of the given size.
*/
diff --git a/jetty-util/src/main/java/org/eclipse/jetty/util/thread/QueuedThreadPool.java b/jetty-util/src/main/java/org/eclipse/jetty/util/thread/QueuedThreadPool.java
index f0bb6f884b8..7726bf0a00c 100755
--- a/jetty-util/src/main/java/org/eclipse/jetty/util/thread/QueuedThreadPool.java
+++ b/jetty-util/src/main/java/org/eclipse/jetty/util/thread/QueuedThreadPool.java
@@ -193,7 +193,10 @@ public class QueuedThreadPool extends AbstractLifeCycle implements SizedThreadPo
}
/**
- * Delegated to the named or anonymous Pool.
+ * Thread Pool should use Daemon Threading.
+ *
+ * @param daemon true to enable delegation
+ * @see Thread#setDaemon(boolean)
*/
public void setDaemon(boolean daemon)
{
@@ -342,7 +345,10 @@ public class QueuedThreadPool extends AbstractLifeCycle implements SizedThreadPo
}
/**
- * Delegated to the named or anonymous Pool.
+ * Is thread pool using daemon threading
+ *
+ * @return true if delegating to named or anonymous pool
+ * @see Thread#setDaemon(boolean)
*/
@ManagedAttribute("thead pool using a daemon thread")
public boolean isDaemon()
diff --git a/jetty-util/src/main/java/org/eclipse/jetty/util/thread/ScheduledExecutorScheduler.java b/jetty-util/src/main/java/org/eclipse/jetty/util/thread/ScheduledExecutorScheduler.java
index 747882b89e7..26a8e42f345 100755
--- a/jetty-util/src/main/java/org/eclipse/jetty/util/thread/ScheduledExecutorScheduler.java
+++ b/jetty-util/src/main/java/org/eclipse/jetty/util/thread/ScheduledExecutorScheduler.java
@@ -32,7 +32,7 @@ import org.eclipse.jetty.util.component.Dumpable;
/**
* Implementation of {@link Scheduler} based on JDK's {@link ScheduledThreadPoolExecutor}.
- *
+ *
* While use of {@link ScheduledThreadPoolExecutor} creates futures that will not be used,
* it has the advantage of allowing to set a property to remove cancelled tasks from its
* queue even if the task did not fire, which provides a huge benefit in the performance
diff --git a/jetty-util/src/main/java/org/eclipse/jetty/util/thread/ThreadPool.java b/jetty-util/src/main/java/org/eclipse/jetty/util/thread/ThreadPool.java
index 64084dad54e..8b1e17fd6ee 100644
--- a/jetty-util/src/main/java/org/eclipse/jetty/util/thread/ThreadPool.java
+++ b/jetty-util/src/main/java/org/eclipse/jetty/util/thread/ThreadPool.java
@@ -37,6 +37,7 @@ public interface ThreadPool extends Executor
/* ------------------------------------------------------------ */
/**
* Blocks until the thread pool is {@link LifeCycle#stop stopped}.
+ * @throws InterruptedException if thread was interrupted
*/
public void join() throws InterruptedException;
diff --git a/jetty-util/src/test/java/org/eclipse/jetty/util/log/StdErrLogTest.java b/jetty-util/src/test/java/org/eclipse/jetty/util/log/StdErrLogTest.java
index c8e3ad15a51..97a176f0e80 100644
--- a/jetty-util/src/test/java/org/eclipse/jetty/util/log/StdErrLogTest.java
+++ b/jetty-util/src/test/java/org/eclipse/jetty/util/log/StdErrLogTest.java
@@ -160,6 +160,7 @@ public class StdErrLogTest
/**
* Test to make sure that using a Null parameter on parameterized messages does not result in a NPE
+ * @throws NullPointerException failed test
*/
@Test
public void testParameterizedMessage_NullValues() throws NullPointerException
@@ -306,6 +307,7 @@ public class StdErrLogTest
* Tests StdErrLog.warn() methods with level filtering.
*
* Should always see WARN level messages, regardless of set level.
+ * @throws UnsupportedEncodingException failed test
*/
@Test
public void testWarnFiltering() throws UnsupportedEncodingException
@@ -345,6 +347,7 @@ public class StdErrLogTest
* Tests StdErrLog.info() methods with level filtering.
*
* Should only see INFO level messages when level is set to {@link StdErrLog#LEVEL_INFO} and below.
+ * @throws UnsupportedEncodingException failed test
*/
@Test
public void testInfoFiltering() throws UnsupportedEncodingException
@@ -390,6 +393,7 @@ public class StdErrLogTest
/**
* Tests {@link StdErrLog#LEVEL_OFF} filtering.
+ * @throws UnsupportedEncodingException failed test
*/
@Test
public void testOffFiltering() throws UnsupportedEncodingException
@@ -417,6 +421,7 @@ public class StdErrLogTest
* Tests StdErrLog.debug() methods with level filtering.
*
* Should only see DEBUG level messages when level is set to {@link StdErrLog#LEVEL_DEBUG} and below.
+ * @throws UnsupportedEncodingException failed test
*/
@Test
public void testDebugFiltering() throws UnsupportedEncodingException
@@ -465,6 +470,7 @@ public class StdErrLogTest
* Tests StdErrLog with {@link Logger#ignore(Throwable)} use.
*
* Should only see IGNORED level messages when level is set to {@link StdErrLog#LEVEL_ALL}.
+ * @throws UnsupportedEncodingException failed test
*/
@Test
public void testIgnores() throws UnsupportedEncodingException
diff --git a/jetty-util/src/test/java/org/eclipse/jetty/util/resource/ClassPathResourceTest.java b/jetty-util/src/test/java/org/eclipse/jetty/util/resource/ClassPathResourceTest.java
index 5275a9e5140..d2d52d3f5db 100644
--- a/jetty-util/src/test/java/org/eclipse/jetty/util/resource/ClassPathResourceTest.java
+++ b/jetty-util/src/test/java/org/eclipse/jetty/util/resource/ClassPathResourceTest.java
@@ -65,6 +65,7 @@ public class ClassPathResourceTest
/**
* Test a class path resource for directories.
+ * @throws Exception failed test
*/
@Test
public void testClassPathResourceDirectory() throws Exception
@@ -84,6 +85,7 @@ public class ClassPathResourceTest
/**
* Test a class path resource for a file.
+ * @throws Exception failed test
*/
@Test
public void testClassPathResourceFile() throws Exception
diff --git a/jetty-util/src/test/java/org/eclipse/jetty/util/resource/FileSystemResourceTest.java b/jetty-util/src/test/java/org/eclipse/jetty/util/resource/FileSystemResourceTest.java
index d3c4c330f4b..9db0a183487 100644
--- a/jetty-util/src/test/java/org/eclipse/jetty/util/resource/FileSystemResourceTest.java
+++ b/jetty-util/src/test/java/org/eclipse/jetty/util/resource/FileSystemResourceTest.java
@@ -583,6 +583,7 @@ public class FileSystemResourceTest
* for long filenames.
*
* See: http://support.microsoft.com/kb/142982
+ * @throws Exception failed test
*/
@Test
public void testCase8dot3Alias() throws Exception
@@ -617,6 +618,7 @@ public class FileSystemResourceTest
* NTFS Alternative Data / File Streams.
*
* See: http://msdn.microsoft.com/en-us/library/windows/desktop/aa364404(v=vs.85).aspx
+ * @throws Exception failed test
*/
@Test
public void testNTFSFileStreamAlias() throws Exception
@@ -657,6 +659,7 @@ public class FileSystemResourceTest
* NTFS Alternative Data / File Streams.
*
* See: http://msdn.microsoft.com/en-us/library/windows/desktop/aa364404(v=vs.85).aspx
+ * @throws Exception failed test
*/
@Test
public void testNTFSFileDataStreamAlias() throws Exception
@@ -699,6 +702,7 @@ public class FileSystemResourceTest
* NTFS Alternative Data / File Streams.
*
* See: http://msdn.microsoft.com/en-us/library/windows/desktop/aa364404(v=vs.85).aspx
+ * @throws Exception failed test
*/
@Test
public void testNTFSFileEncodedDataStreamAlias() throws Exception
@@ -924,6 +928,7 @@ public class FileSystemResourceTest
/**
* The most basic access example
+ * @throws Exception failed test
*/
@Test
public void testExist_Normal() throws Exception