Eclipse
/
jetty.project
mirror of https://github.com/jetty/jetty.project.git
1
0
Fork 0
Code Issues Packages Projects Releases Wiki Activity

464727 - Update Javadoc for Java 8 DocLint 

+ Fixed jetty-util's javadoc
This commit is contained in:
Joakim Erdfelt 2015-04-15 12:49:04 -07:00
parent b26552cbb5
commit 45b82c32a1
65 changed files with 569 additions and 259 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

7
jetty-util/src/main/java/org/eclipse/jetty/util/AbstractTrie.java
View File

@ -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>
{

5
jetty-util/src/main/java/org/eclipse/jetty/util/ArrayQueue.java
View File

@ -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>
{

18
jetty-util/src/main/java/org/eclipse/jetty/util/ArrayTernaryTrie.java
View File

@ -24,20 +24,22 @@ import java.util.HashSet;
import java.util.Set;
/* ------------------------------------------------------------ */
/**
* <p>A Ternary Trie String lookup data structure.</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>
* The Trie is stored in 3 arrays:<dl>
* 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:
* </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)
{

2
jetty-util/src/main/java/org/eclipse/jetty/util/ArrayTrie.java
View File

@ -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>
{

5
jetty-util/src/main/java/org/eclipse/jetty/util/ArrayUtil.java
View File

@ -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)
{

9
jetty-util/src/main/java/org/eclipse/jetty/util/BlockingArrayQueue.java
View File

@ -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

35
jetty-util/src/main/java/org/eclipse/jetty/util/BufferUtil.java
View File

@ -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 &lt;&lt;&lt; and &gt;&gt;&gt;)
*/

7
jetty-util/src/main/java/org/eclipse/jetty/util/CompletableCallback.java
View File

@ -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);

8
jetty-util/src/main/java/org/eclipse/jetty/util/ConcurrentArrayQueue.java
View File

@ -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>
{

10
jetty-util/src/main/java/org/eclipse/jetty/util/DateCache.java
View File

@ -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)

2
jetty-util/src/main/java/org/eclipse/jetty/util/HostMap.java
View File

@ -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>

37
jetty-util/src/main/java/org/eclipse/jetty/util/IO.java
View File

@ -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)
{

7
jetty-util/src/main/java/org/eclipse/jetty/util/IPAddressMap.java
View File

@ -35,11 +35,12 @@ import java.util.StringTokenizer;
* 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
* nnn- =&gt; nnn-255
* -nnn =&gt; 0-nnn
* - =&gt; 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>

23
jetty-util/src/main/java/org/eclipse/jetty/util/IteratingCallback.java
View File

@ -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>
@ -149,6 +154,8 @@ public abstract class IteratingCallback implements Callback
* <li>{@link Action#SUCCEEDED} when the overall job is completed</li>
* </ul>
*
* @return the appropriate Action
*
* @throws Exception if the sub task processing throws
*/
protected abstract Action process() throws Exception;
@ -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
*/

17
jetty-util/src/main/java/org/eclipse/jetty/util/LazyList.java
View File

@ -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)

8
jetty-util/src/main/java/org/eclipse/jetty/util/Loader.java
View File

@ -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
{

4
jetty-util/src/main/java/org/eclipse/jetty/util/MemoryUtils.java
View File

@ -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;
}
}

3
jetty-util/src/main/java/org/eclipse/jetty/util/MultiException.java
View File

@ -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

3
jetty-util/src/main/java/org/eclipse/jetty/util/MultiMap.java
View File

@ -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)

24
jetty-util/src/main/java/org/eclipse/jetty/util/MultiPartInputStreamParser.java
View File

@ -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

6
jetty-util/src/main/java/org/eclipse/jetty/util/MultiPartOutputStream.java
View File

@ -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

6
jetty-util/src/main/java/org/eclipse/jetty/util/MultiPartWriter.java
View File

@ -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

2
jetty-util/src/main/java/org/eclipse/jetty/util/PatternMatcher.java
View File

@ -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

1
jetty-util/src/main/java/org/eclipse/jetty/util/QuotedStringTokenizer.java
View File

@ -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)

14
jetty-util/src/main/java/org/eclipse/jetty/util/RolloverFileOutputStream.java
View File

@ -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,

7
jetty-util/src/main/java/org/eclipse/jetty/util/Scanner.java
View File

@ -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)

2
jetty-util/src/main/java/org/eclipse/jetty/util/SharedBlockingCallback.java
View File

@ -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

4
jetty-util/src/main/java/org/eclipse/jetty/util/SocketAddressResolver.java
View File

@ -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);

34
jetty-util/src/main/java/org/eclipse/jetty/util/StringUtil.java
View File

@ -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 )
{

2
jetty-util/src/main/java/org/eclipse/jetty/util/TreeTrie.java
View File

@ -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>
{

4
jetty-util/src/main/java/org/eclipse/jetty/util/Trie.java
View File

@ -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);

2
jetty-util/src/main/java/org/eclipse/jetty/util/TypeUtil.java
View File

@ -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)
{

54
jetty-util/src/main/java/org/eclipse/jetty/util/URIUtil.java
View File

@ -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)
{

72
jetty-util/src/main/java/org/eclipse/jetty/util/UrlEncoded.java
View File

@ -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=&amp;b=&amp;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=&amp;b=&amp;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)

2
jetty-util/src/main/java/org/eclipse/jetty/util/Utf8Appendable.java
View File

@ -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 &lt;bjoern@hoehrmann.de&gt;
* 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:

5
jetty-util/src/main/java/org/eclipse/jetty/util/annotation/ManagedAttribute.java
View File

@ -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>&#064;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";

6
jetty-util/src/main/java/org/eclipse/jetty/util/annotation/ManagedObject.java
View File

@ -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>&#064;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>&#064;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";

4
jetty-util/src/main/java/org/eclipse/jetty/util/annotation/ManagedOperation.java
View File

@ -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>&#064;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";

2
jetty-util/src/main/java/org/eclipse/jetty/util/annotation/Name.java
View File

@ -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 "";
}

10
jetty-util/src/main/java/org/eclipse/jetty/util/component/Container.java
View File

@ -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);

12
jetty-util/src/main/java/org/eclipse/jetty/util/component/ContainerLifeCycle.java
View File

@ -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)
{

2
jetty-util/src/main/java/org/eclipse/jetty/util/component/LifeCycle.java
View File

@ -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.
*

1
jetty-util/src/main/java/org/eclipse/jetty/util/log/Logger.java
View File

@ -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);
}

25
jetty-util/src/main/java/org/eclipse/jetty/util/log/StdErrLog.java
View File

@ -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 '&lt;' 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:

2
jetty-util/src/main/java/org/eclipse/jetty/util/resource/FileResource.java
View File

@ -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

6
jetty-util/src/main/java/org/eclipse/jetty/util/resource/JarFileResource.java
View File

@ -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)

59
jetty-util/src/main/java/org/eclipse/jetty/util/resource/PathResource.java
View File

@ -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;

107
jetty-util/src/main/java/org/eclipse/jetty/util/resource/Resource.java
View File

@ -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
{

6
jetty-util/src/main/java/org/eclipse/jetty/util/resource/ResourceCollection.java
View File

@ -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
{

4
jetty-util/src/main/java/org/eclipse/jetty/util/resource/URLResource.java
View File

@ -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");

20
jetty-util/src/main/java/org/eclipse/jetty/util/security/CertificateValidator.java
View File

@ -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
{

17
jetty-util/src/main/java/org/eclipse/jetty/util/security/Constraint.java
View File

@ -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 &amp;
* 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 &amp;
* 2=DC_CONFIDENTIAL
*/
public int getDataConstraint()

4
jetty-util/src/main/java/org/eclipse/jetty/util/security/Password.java
View File

@ -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)

2
jetty-util/src/main/java/org/eclipse/jetty/util/ssl/AliasedX509ExtendedKeyManager.java
View File

@ -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
{

4
jetty-util/src/main/java/org/eclipse/jetty/util/ssl/SniX509ExtendedKeyManager.java
View File

@ -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
{

18
jetty-util/src/main/java/org/eclipse/jetty/util/ssl/SslContextFactory.java
View File

@ -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.
*/
@ -888,6 +888,7 @@ 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
*/
@ -899,6 +900,7 @@ 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

5
jetty-util/src/main/java/org/eclipse/jetty/util/statistic/CounterStatistic.java
View File

@ -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()
{

21
jetty-util/src/main/java/org/eclipse/jetty/util/statistic/SampleStatistic.java
View File

@ -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&section=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&amp;section=4#On-line_algorithm">
* Algorithms for calculating variance </a>
*/
public class SampleStatistic
{

2
jetty-util/src/main/java/org/eclipse/jetty/util/thread/ExecutorThreadPool.java
View File

@ -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 &gt;= 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.
*/

10
jetty-util/src/main/java/org/eclipse/jetty/util/thread/QueuedThreadPool.java
View File

@ -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()

2
jetty-util/src/main/java/org/eclipse/jetty/util/thread/ScheduledExecutorScheduler.java
View File

@ -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

1
jetty-util/src/main/java/org/eclipse/jetty/util/thread/ThreadPool.java
View File

@ -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;

6
jetty-util/src/test/java/org/eclipse/jetty/util/log/StdErrLogTest.java
View File

@ -160,6 +160,7 @@ public class StdErrLogTest
/**
* Test to make sure that using a Null parameter on parameterized messages does not result in a NPE
* @throws NullPointerException failed test
*/
@Test
public void testParameterizedMessage_NullValues() throws NullPointerException
@ -306,6 +307,7 @@ public class StdErrLogTest
* Tests StdErrLog.warn() methods with level filtering.
* <p>
* Should always see WARN level messages, regardless of set level.
* @throws UnsupportedEncodingException failed test
*/
@Test
public void testWarnFiltering() throws UnsupportedEncodingException
@ -345,6 +347,7 @@ public class StdErrLogTest
* Tests StdErrLog.info() methods with level filtering.
* <p>
* Should only see INFO level messages when level is set to {@link StdErrLog#LEVEL_INFO} and below.
* @throws UnsupportedEncodingException failed test
*/
@Test
public void testInfoFiltering() throws UnsupportedEncodingException
@ -390,6 +393,7 @@ public class StdErrLogTest
/**
* Tests {@link StdErrLog#LEVEL_OFF} filtering.
* @throws UnsupportedEncodingException failed test
*/
@Test
public void testOffFiltering() throws UnsupportedEncodingException
@ -417,6 +421,7 @@ public class StdErrLogTest
* Tests StdErrLog.debug() methods with level filtering.
* <p>
* Should only see DEBUG level messages when level is set to {@link StdErrLog#LEVEL_DEBUG} and below.
* @throws UnsupportedEncodingException failed test
*/
@Test
public void testDebugFiltering() throws UnsupportedEncodingException
@ -465,6 +470,7 @@ public class StdErrLogTest
* Tests StdErrLog with {@link Logger#ignore(Throwable)} use.
* <p>
* Should only see IGNORED level messages when level is set to {@link StdErrLog#LEVEL_ALL}.
* @throws UnsupportedEncodingException failed test
*/
@Test
public void testIgnores() throws UnsupportedEncodingException

2
jetty-util/src/test/java/org/eclipse/jetty/util/resource/ClassPathResourceTest.java
View File

@ -65,6 +65,7 @@ public class ClassPathResourceTest
/**
* Test a class path resource for directories.
* @throws Exception failed test
*/
@Test
public void testClassPathResourceDirectory() throws Exception
@ -84,6 +85,7 @@ public class ClassPathResourceTest
/**
* Test a class path resource for a file.
* @throws Exception failed test
*/
@Test
public void testClassPathResourceFile() throws Exception

5
jetty-util/src/test/java/org/eclipse/jetty/util/resource/FileSystemResourceTest.java
View File

@ -583,6 +583,7 @@ public class FileSystemResourceTest
* for long filenames.
* <p>
* See: http://support.microsoft.com/kb/142982
* @throws Exception failed test
*/
@Test
public void testCase8dot3Alias() throws Exception
@ -617,6 +618,7 @@ public class FileSystemResourceTest
* NTFS Alternative Data / File Streams.
* <p>
* See: http://msdn.microsoft.com/en-us/library/windows/desktop/aa364404(v=vs.85).aspx
* @throws Exception failed test
*/
@Test
public void testNTFSFileStreamAlias() throws Exception
@ -657,6 +659,7 @@ public class FileSystemResourceTest
* NTFS Alternative Data / File Streams.
* <p>
* See: http://msdn.microsoft.com/en-us/library/windows/desktop/aa364404(v=vs.85).aspx
* @throws Exception failed test
*/
@Test
public void testNTFSFileDataStreamAlias() throws Exception
@ -699,6 +702,7 @@ public class FileSystemResourceTest
* NTFS Alternative Data / File Streams.
* <p>
* See: http://msdn.microsoft.com/en-us/library/windows/desktop/aa364404(v=vs.85).aspx
* @throws Exception failed test
*/
@Test
public void testNTFSFileEncodedDataStreamAlias() throws Exception
@ -924,6 +928,7 @@ public class FileSystemResourceTest
/**
* The most basic access example
* @throws Exception failed test
*/
@Test
public void testExist_Normal() throws Exception