diff options
| author | Joakim Erdfelt | 2015-04-15 19:49:04 +0000 |
|---|---|---|
| committer | Joakim Erdfelt | 2015-04-15 21:38:35 +0000 |
| commit | 45b82c32a121909e7b4011e2e301aa14b9b02376 (patch) | |
| tree | 3fa05704d640ba2d8da6d9257de1d59a5755e736 /jetty-util/src/main/java/org | |
| parent | b26552cbb582e6744e3af6f534eb091f4ce65bed (diff) | |
| download | org.eclipse.jetty.project-45b82c32a121909e7b4011e2e301aa14b9b02376.tar.gz org.eclipse.jetty.project-45b82c32a121909e7b4011e2e301aa14b9b02376.tar.xz org.eclipse.jetty.project-45b82c32a121909e7b4011e2e301aa14b9b02376.zip | |
464727 - Update Javadoc for Java 8 DocLint
+ Fixed jetty-util's javadoc
Diffstat (limited to 'jetty-util/src/main/java/org')
62 files changed, 555 insertions, 258 deletions
diff --git a/jetty-util/src/main/java/org/eclipse/jetty/util/AbstractTrie.java b/jetty-util/src/main/java/org/eclipse/jetty/util/AbstractTrie.java index d4ff8b6fa6..1f6223d9cd 100644 --- a/jetty-util/src/main/java/org/eclipse/jetty/util/AbstractTrie.java +++ b/jetty-util/src/main/java/org/eclipse/jetty/util/AbstractTrie.java @@ -22,12 +22,13 @@ import java.nio.ByteBuffer; import java.nio.charset.StandardCharsets; -/* ------------------------------------------------------------ */ -/** Abstract Trie implementation. +/** + * Abstract Trie implementation. * <p>Provides some common implementations, which may not be the most * efficient. For byte operations, the assumption is made that the charset * is ISO-8859-1</p> - * @param <V> + * + * @param <V> the type of object that the Trie holds */ public abstract class AbstractTrie<V> implements Trie<V> { diff --git a/jetty-util/src/main/java/org/eclipse/jetty/util/ArrayQueue.java b/jetty-util/src/main/java/org/eclipse/jetty/util/ArrayQueue.java index a02c804ace..1e44b3b588 100644 --- a/jetty-util/src/main/java/org/eclipse/jetty/util/ArrayQueue.java +++ b/jetty-util/src/main/java/org/eclipse/jetty/util/ArrayQueue.java @@ -25,11 +25,12 @@ import java.util.Queue; /* ------------------------------------------------------------ */ /** * Queue backed by circular array. - * <p/> + * <p> * This partial Queue implementation (also with {@link #remove()} for stack operation) * is backed by a growable circular array. + * </p> * - * @param <E> + * @param <E> the type of object the queue holds */ public class ArrayQueue<E> extends AbstractList<E> implements Queue<E> { diff --git a/jetty-util/src/main/java/org/eclipse/jetty/util/ArrayTernaryTrie.java b/jetty-util/src/main/java/org/eclipse/jetty/util/ArrayTernaryTrie.java index e289aebcda..142bb5882a 100644 --- a/jetty-util/src/main/java/org/eclipse/jetty/util/ArrayTernaryTrie.java +++ b/jetty-util/src/main/java/org/eclipse/jetty/util/ArrayTernaryTrie.java @@ -24,20 +24,22 @@ import java.util.HashSet; import java.util.Set; -/* ------------------------------------------------------------ */ /** * <p>A Ternary Trie String lookup data structure.</p> + * <p> * This Trie is of a fixed size and cannot grow (which can be a good thing with regards to DOS when used as a cache). + * </p> * <p> - * The Trie is stored in 3 arrays:<dl> + * The Trie is stored in 3 arrays: + * </p> + * <dl> * <dt>char[] _tree</dt><dd>This is semantically 2 dimensional array flattened into a 1 dimensional char array. The second dimension * is that every 4 sequential elements represents a row of: character; hi index; eq index; low index, used to build a * ternary trie of key strings.</dd> - * <dt>String[] _key<dt><dd>An array of key values where each element matches a row in the _tree array. A non zero key element + * <dt>String[] _key</dt><dd>An array of key values where each element matches a row in the _tree array. A non zero key element * indicates that the _tree row is a complete key rather than an intermediate character of a longer key.</dd> * <dt>V[] _value</dt><dd>An array of values corresponding to the _key array</dd> * </dl> - * </p> * <p>The lookup of a value will iterate through the _tree array matching characters. If the equal tree branch is followed, * then the _key array is looked up to see if this is a complete match. If a match is found then the _value array is looked up * to return the matching value. @@ -52,7 +54,7 @@ import java.util.Set; * Trie is required external locks need to be applied. * </p> * - * @param <V> + * @param <V> the Entry type */ public class ArrayTernaryTrie<V> extends AbstractTrie<V> { @@ -141,8 +143,8 @@ public class ArrayTernaryTrie<V> extends AbstractTrie<V> /* ------------------------------------------------------------ */ /** Copy Trie and change capacity by a factor - * @param trie - * @param factor + * @param trie the trie to copy from + * @param factor the factor to grow the capacity by */ public ArrayTernaryTrie(ArrayTernaryTrie<V> trie, double factor) { diff --git a/jetty-util/src/main/java/org/eclipse/jetty/util/ArrayTrie.java b/jetty-util/src/main/java/org/eclipse/jetty/util/ArrayTrie.java index 172503e2ea..65a4e2fbf3 100644 --- a/jetty-util/src/main/java/org/eclipse/jetty/util/ArrayTrie.java +++ b/jetty-util/src/main/java/org/eclipse/jetty/util/ArrayTrie.java @@ -44,7 +44,7 @@ import java.util.Set; * and not mutated during that access. If concurrent mutations of the * Trie is required external locks need to be applied. * </p> - * @param <V> + * @param <V> the entry type */ public class ArrayTrie<V> extends AbstractTrie<V> { diff --git a/jetty-util/src/main/java/org/eclipse/jetty/util/ArrayUtil.java b/jetty-util/src/main/java/org/eclipse/jetty/util/ArrayUtil.java index 903b9a4dae..36a8a8a0c7 100644 --- a/jetty-util/src/main/java/org/eclipse/jetty/util/ArrayUtil.java +++ b/jetty-util/src/main/java/org/eclipse/jetty/util/ArrayUtil.java @@ -25,8 +25,8 @@ import java.util.Arrays; import java.util.List; -/* ------------------------------------------------------------ */ /** + * Utility methods for Array manipulation */ public class ArrayUtil implements Cloneable, Serializable @@ -60,6 +60,7 @@ public class ArrayUtil * @param item The item to add * @param type The type of the array (in case of null array) * @return new array with contents of array plus item + * @param <T> the array entry type */ public static<T> T[] addToArray(T[] array, T item, Class<?> type) { @@ -86,6 +87,7 @@ public class ArrayUtil * @param item The item to add * @param type The type of the array (in case of null array) * @return new array with contents of array plus item + * @param <T> the array entry type */ public static<T> T[] prependToArray(T item, T[] array, Class<?> type) { @@ -113,6 +115,7 @@ public class ArrayUtil /** * @param array Any array of object * @return A new <i>modifiable</i> list initialised with the elements from <code>array</code>. + * @param <E> the array entry type */ public static<E> List<E> asMutableList(E[] array) { diff --git a/jetty-util/src/main/java/org/eclipse/jetty/util/BlockingArrayQueue.java b/jetty-util/src/main/java/org/eclipse/jetty/util/BlockingArrayQueue.java index bb1e2ddbdc..d8894baf5b 100644 --- a/jetty-util/src/main/java/org/eclipse/jetty/util/BlockingArrayQueue.java +++ b/jetty-util/src/main/java/org/eclipse/jetty/util/BlockingArrayQueue.java @@ -33,13 +33,16 @@ import java.util.concurrent.locks.ReentrantLock; /** * A BlockingQueue backed by a circular array capable or growing. - * <p/> + * <p> * 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. - * <p/> + * </p> + * <p> * Unlike {@link java.util.concurrent.ArrayBlockingQueue}, this class is able to grow and provides a blocking put call. - * <p/> + * </p> + * <p> * 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}. + * </p> * * @param <E> * 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 377a10c2b2..6e5c85b4e9 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: + * </p> * <pre> * buffer.clear(); * channel.write(buffer); * </pre> + * <p> * Which looks as if it should write no data, but in fact writes the buffer worth of garbage. * </p> * <p> @@ -58,13 +60,14 @@ import org.eclipse.jetty.util.resource.Resource; * <p> * 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:<pre> + * in flush mode. Thus the following tests will pass: + * </p> + * <pre> * ByteBuffer buffer = BufferUtil.allocate(1024); * assert(buffer.remaining()==0); * BufferUtil.clear(buffer); * assert(buffer.remaining()==0); * </pre> - * </p> * <p>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: + * </p> * <pre> * int pos = BufferUtil.flipToFill(buffer); * try @@ -83,8 +87,9 @@ import org.eclipse.jetty.util.resource.Resource; * flipToFlush(buffer, pos); * } * </pre> - * The flipToFill method will effectively clear the buffer if it is emtpy and will compact the buffer if there is no space. - * + * <p> + * The flipToFill method will effectively clear the buffer if it is empty and will compact the buffer if there is no space. + * </p> */ 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 1020bb6267..156b4c20bc 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; /** + * <p> * 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. - * <p /> + * </p> + * <p> * 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. - * <p /> + * </p> * Typical usage: * <pre> * 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 6c4996b379..9508b9724a 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. - * <p/> + * <p> * 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. - * <p/> + * </p> + * <p> * The algorithm used is a variation of the algorithm from Gidenstam, Sundell and Tsigas * (http://www.adm.hb.se/~AGD/Presentations/CacheAwareQueue_OPODIS.pdf). + * </p> * - * @param <T> + * @param <T> the Array entry type */ public class ConcurrentArrayQueue<T> extends AbstractQueue<T> { 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 1b5784fd0d..04343242dd 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 18f557f139..5db650f8a9 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 <TYPE> the element type */ @SuppressWarnings("serial") public class HostMap<TYPE> extends HashMap<String, TYPE> 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 6a0032a874..03b0dc7443 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 370693c518..f9143ff1ed 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. * </p> * <pre> - * 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 * </pre> + * @param <TYPE> the Map Entry value type */ @SuppressWarnings("serial") public class IPAddressMap<TYPE> extends HashMap<String, TYPE> 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 0f53d46878..a155a4e569 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. - * <p/> + * <p> * 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. - * <p/> + * </p> + * <p> * 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. - * <p/> + * </p> + * <p> * 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. - * <p/> + * </p> + * <p> * 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. + * </p> */ 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. - * <p/> + * <p> * Implementations must start the asynchronous execution of the sub task * (if any) and return an appropriate action: + * </p> * <ul> * <li>{@link Action#IDLE} when no sub tasks are available for execution * but the overall job is not completed yet</li> @@ -148,6 +153,8 @@ public abstract class IteratingCallback implements Callback * has been started</li> * <li>{@link Action#SUCCEEDED} when the overall job is completed</li> * </ul> + * + * @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. - * <p/> + * <p> * A callback can only be reset to IDLE from the * SUCCEEDED or FAILED states or if it is already IDLE. + * </p> * * @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 2013a6851a..0855be3854 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. + * <p> * 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. + * </p> * <p> * 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. - * - * <p><h4>Usage</h4> + * </p> + * <strong>Usage</strong> * <pre> * 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 <E> the list entry type */ public static<E> List<E> 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 <E> the list entry type */ @SuppressWarnings("unchecked") public static<E> List<E> 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 <E> the list entry type */ @SuppressWarnings("unchecked") public static <E> 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 500f9f9c83..062029cef4 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 <code>loadClass</code> * @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 a0e50f4561..a8f830de4e 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. - * <p /> + * 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 fdc62c516c..3212551e79 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 286889bcde..2d9a53342d 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 <V> the entry type for multimap values */ @SuppressWarnings("serial") public class MultiMap<V> extends HashMap<String,List<V>> @@ -283,7 +284,7 @@ public class MultiMap<V> extends HashMap<String,List<V>> * Test for a specific single value in the map. * <p> * 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 a8607ea00f..273c9f96d3 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<Part> 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<Part> 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 ddf985045b..13284c2f46 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 f0654f594b..93f603cd1a 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 503010163d..0d23f2fcb3 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 7436c6021f..951a1b3ed2 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 8085f1eeea..1ff0b7631c 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 848aa08e6a..c6631da555 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 3e2645e818..68d1234d96 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. - * <p /> + * <p> * A typical usage pattern is: * <pre> * 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 62ad1cf54a..068025526b 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. - * <p /> + * <p> * {@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. - * <p /> + * <p> * Example usage: * <pre> * 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 6accd1e8d8..33655ccb4d 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 ccda7416b2..b8b3afa658 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. * </p> * - * @param <V> + * @param <V> the entry type */ public class TreeTrie<V> extends AbstractTrie<V> { 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 131e6105ba..280ae4c28d 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 <V> + * @param <V> the Trie entry type */ public interface Trie<V> { @@ -49,6 +49,7 @@ public interface Trie<V> /* ------------------------------------------------------------ */ /** 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<V> * @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 42789983ee..6eedd3e6fe 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. * <p> * 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 <T> the array and list entry type */ public static <T> List<T> 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 bb0f7f1a9c..cf0f985ba0 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. + * <p> * 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. - * <P>UTF-8 encoding is used by default for % encoded characters. This + * </p> + * <p> + * 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 + * </p> * + * @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</p> + * 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</p> + * 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 8727d1326d..e776c9a4d5 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". * <p> * This class handles the encoding and decoding for either * the query string of a URL or the _content of a POST HTTP request. - * - * <h4>Notes</h4> + * </p> + * <b>Notes</b> + * <p> * 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. + * </p> * <p> * The hashtable either contains String single values, vectors * of String or arrays of Strings. + * </p> * <p> * This class is only partially synchronised. In particular, simple * get operations are not protected from concurrent updates. + * </p> * * @see java.net.URLEncoder */ @@ -103,7 +107,8 @@ public class UrlEncoded extends MultiMap<String> 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<String> 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<String> 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. <code>"blah?a=&b=&c="</code>. + * @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<String> 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. <code>"blah?a=&b=&c="</code>. + * @return the MultiMap as a string encoded with % encodings. */ public static String encode(MultiMap<String> map, Charset charset, boolean equalsForNullValue) { @@ -190,6 +203,8 @@ public class UrlEncoded extends MultiMap<String> 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<String> map, String charset) { @@ -199,6 +214,8 @@ public class UrlEncoded extends MultiMap<String> 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<String> map, Charset charset) { @@ -282,7 +299,7 @@ public class UrlEncoded extends MultiMap<String> 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<String> 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<String> map, int maxLength, int maxKeys) throws IOException @@ -499,7 +519,9 @@ public class UrlEncoded extends MultiMap<String> 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<String> map, int maxLength, int maxKeys) throws IOException @@ -637,6 +659,11 @@ public class UrlEncoded extends MultiMap<String> 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<String> map, String charset, int maxLength, int maxKeys) throws IOException @@ -661,6 +688,11 @@ public class UrlEncoded extends MultiMap<String> 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<String> map, Charset charset, int maxLength, int maxKeys) throws IOException @@ -785,6 +817,8 @@ public class UrlEncoded extends MultiMap<String> 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<String> 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<String> 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<String> 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 bc037439b1..c0912e6df2 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 <bjoern@hoehrmann.de> + * 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 1422d7b4da..99e7454552 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 <code>@ManagedAttribute</code> 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 07d9688e04..c29b138e64 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 <code>@ManagedObject</code> 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 + * <code>@ManagedObject</code> 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 ae3eb40e4a..bdc789ff6a 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 <code>@ManagedOperation</code> 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 c4c678731c..aab349fb21 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 bbb95a627e..a75d459366 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 <T> the Bean type * @see #getBeans() */ public <T> Collection<T> getBeans(Class<T> 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 <T> the Bean type */ public <T> T getBean(Class<T> 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 772c03fd2a..060a3d1344 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. - * <p>This is a conveniance method that uses addBean(lifecycle,true) + * <p>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 0713c6e761..45c7bf0230 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. - * <br /> + * <br> * 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 9da7788e89..65ec959ae0 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. * <p>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 7a322f28ac..505d240f77 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; * <dl> * <dt>${name|hierarchy}.LEVEL=(ALL|DEBUG|INFO|WARN|OFF)</dt> * <dd> - * Sets the level that the Logger should log at.<br/> - * Names can be a package name, or a fully qualified class name.<br/> - * Default: INFO<br/> - * <br/> + * Sets the level that the Logger should log at.<br> + * Names can be a package name, or a fully qualified class name.<br> + * Default: INFO<br> + * <br> * Examples: * <dl> * <dt>org.eclipse.jetty.LEVEL=WARN</dt> @@ -56,35 +56,35 @@ import org.eclipse.jetty.util.annotation.ManagedObject; * <dt>${name}.SOURCE=(true|false)</dt> * <dd> * Logger specific, attempt to print the java source file name and line number - * where the logging event originated from.<br/> + * where the logging event originated from.<br> * Name must be a fully qualified class name (package name hierarchy is not supported - * by this configurable)<br/> - * Warning: this is a slow operation and will have an impact on performance!<br/> + * by this configurable)<br> + * Warning: this is a slow operation and will have an impact on performance!<br> * Default: false * </dd> * * <dt>${name}.STACKS=(true|false)</dt> * <dd> - * Logger specific, control the display of stacktraces.<br/> + * Logger specific, control the display of stacktraces.<br> * Name must be a fully qualified class name (package name hierarchy is not supported - * by this configurable)<br/> + * by this configurable)<br> * Default: true * </dd> * * <dt>org.eclipse.jetty.util.log.stderr.SOURCE=(true|false)</dt> * <dd>Special Global Configuration, attempt to print the java source file name and line number - * where the logging event originated from.<br/> + * where the logging event originated from.<br> * Default: false * </dd> * * <dt>org.eclipse.jetty.util.log.stderr.LONG=(true|false)</dt> * <dd>Special Global Configuration, when true, output logging events to STDERR using - * long form, fully qualified class names. when false, use abbreviated package names<br/> + * long form, fully qualified class names. when false, use abbreviated package names<br> * Default: false * </dd> * <dt>org.eclipse.jetty.util.log.stderr.ESCAPE=(true|false)</dt> * <dd>Global Configuration, when true output logging events to STDERR are always - * escaped so that control characters are replaced with '?"; '\r' with '<' and '\n' replaced '|'<br/> + * escaped so that control characters are replaced with '?"; '\r' with '<' and '\n' replaced '|'<br> * Default: true * </dd> * </dl> @@ -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 - * <p> * * <pre> * 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 eeacc27435..7f9c629e2e 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 <code>true</code> of the object <code>o</code> 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 310df4a761..32a83568c4 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 <code>jar:file:///a/b/c/foo.jar!/x.html</code> isContainedIn <code>file:///a/b/c/foo.jar</code> - * @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 792e43a137..e56c7b5d81 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. + * <p> + * An invocation of this convenience constructor of the form. + * </p> + * <pre> + * new PathResource(file); + * </pre> + * <p> + * behaves in exactly the same way as the expression + * </p> + * <pre> + * new PathResource(file.toPath()); + * </pre> + + * @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. + * <p> + * Must be an absolute URI using the <code>file</code> 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. + * <p> + * An invocation of this convenience constructor of the form. + * </p> + * <pre> + * new PathResource(url); + * </pre> + * <p> + * behaves in exactly the same way as the expression + * </p> + * <pre> + * new PathResource(url.toURI()); + * </pre> + * + * @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 c06390704f..1e4823bd40 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. + * <p> + * 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 960956f56a..e72ddaeebf 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 a2a438c987..537baa5879 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 cf4eeb377e..22ffd7737a 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<? extends CRL> 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 f159ed58f1..72fb579f21 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 781adcdeab..27a74f7e40 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 8dbe305ab7..c7699991f4 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 74f317ba01..be3ae9c1fd 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 5e1b2124a9..6102d1c002 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. - * <p /> + * <p> * 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. - * <p /> + * <p> * If the given {@code address} is null, it is equivalent to {@link #newSSLEngine()}, otherwise * {@link #newSSLEngine(String, int)} is called. - * <p /> + * <p> * 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). - * <p /> + * <p> * Otherwise, the host address is passed to {@link #newSSLEngine(String, int)} without DNS lookup * penalties. - * <p /> + * <p> * 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 23ce97eba7..cb8dd194f1 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 2f106f75ec..4d446838dc 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 * <p> - * 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. * <p> - * 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 <cite>Donald Knuth's Art of Computer Programming, Volume 2, + * Seminumerical Algorithms, 3rd edition, page 232, Boston: Addison-Wesley</cite>. that cites a 1962 paper by B.P. Welford that + * can be found by following <a href="http://www.jstor.org/pss/1266577">Note on a Method for Calculating Corrected Sums + * of Squares and Products</a> * <p> - * 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 <a href= + * "http://en.wikipedia.org/w/index.php?title=Algorithms_for_calculating_variance&section=4#On-line_algorithm"> + * Algorithms for calculating variance </a> */ 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 6f46db277e..2ee3f58710 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 f0bb6f884b..7726bf0a00 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 747882b89e..26a8e42f34 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}. - * <p /> + * <p> * 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 64084dad54..8b1e17fd6e 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; |