Apache
/
commons-lang
mirror of https://github.com/apache/commons-lang.git
1
0
Fork 0
Code Issues Packages Projects Releases Wiki Activity

Adding lots of @since 3.0s 

git-svn-id: https://svn.apache.org/repos/asf/commons/proper/lang/trunk@1082044 13f79535-47bb-0310-9956-ffa450edef68
This commit is contained in:
Henri Yandell 2011-03-16 04:26:58 +00:00
parent edcfd40d71
commit e5b0844c4f
17 changed files with 93 additions and 1 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

1
src/main/java/org/apache/commons/lang3/ObjectUtils.java
View File

@ -113,6 +113,7 @@ public static <T> T defaultIfNull(T object, T defaultValue) {
* @param values the values to test, may be {@code null} or empty
* @return the first value from {@code values} which is not {@code null},
* or {@code null} if there are no non-null values
* @since 3.0
*/
public static <T> T firstNonNull(T... values) {
if (values != null) {

35
src/main/java/org/apache/commons/lang3/StringEscapeUtils.java
View File

@ -56,6 +56,8 @@ public class StringEscapeUtils {
* While {@link #escapeJava(String)} is the expected method of use, this
* object allows the Java escaping functionality to be used
* as the foundation for a custom translator.
*
* @since 3.0
*/
public static final CharSequenceTranslator ESCAPE_JAVA =
new LookupTranslator(
@ -74,6 +76,8 @@ public class StringEscapeUtils {
* While {@link #escapeEcmaScript(String)} is the expected method of use, this
* object allows the EcmaScript escaping functionality to be used
* as the foundation for a custom translator.
*
* @since 3.0
*/
public static final CharSequenceTranslator ESCAPE_ECMASCRIPT =
new AggregateTranslator(
@ -94,6 +98,8 @@ public class StringEscapeUtils {
* While {@link #escapeXml(String)} is the expected method of use, this
* object allows the XML escaping functionality to be used
* as the foundation for a custom translator.
*
* @since 3.0
*/
public static final CharSequenceTranslator ESCAPE_XML =
new AggregateTranslator(
@ -107,6 +113,8 @@ public class StringEscapeUtils {
* While {@link #escapeHtml3(String)} is the expected method of use, this
* object allows the HTML escaping functionality to be used
* as the foundation for a custom translator.
*
* @since 3.0
*/
public static final CharSequenceTranslator ESCAPE_HTML3 =
new AggregateTranslator(
@ -120,6 +128,8 @@ public class StringEscapeUtils {
* While {@link #escapeHtml4(String)} is the expected method of use, this
* object allows the HTML escaping functionality to be used
* as the foundation for a custom translator.
*
* @since 3.0
*/
public static final CharSequenceTranslator ESCAPE_HTML4 =
new AggregateTranslator(
@ -134,6 +144,8 @@ public class StringEscapeUtils {
* While {@link #escapeCsv(String)} is the expected method of use, this
* object allows the CSV escaping functionality to be used
* as the foundation for a custom translator.
*
* @since 3.0
*/
public static final CharSequenceTranslator ESCAPE_CSV = new CsvEscaper();
@ -174,6 +186,8 @@ public int translate(CharSequence input, int index, Writer out) throws IOExcepti
* While {@link #unescapeJava(String)} is the expected method of use, this
* object allows the Java unescaping functionality to be used
* as the foundation for a custom translator.
*
* @since 3.0
*/
// TODO: throw "illegal character: \92" as an Exception if a \ on the end of the Java (as per the compiler)?
public static final CharSequenceTranslator UNESCAPE_JAVA =
@ -196,6 +210,8 @@ public int translate(CharSequence input, int index, Writer out) throws IOExcepti
* While {@link #unescapeEcmaScript(String)} is the expected method of use, this
* object allows the EcmaScript unescaping functionality to be used
* as the foundation for a custom translator.
*
* @since 3.0
*/
public static final CharSequenceTranslator UNESCAPE_ECMASCRIPT = UNESCAPE_JAVA;
@ -205,6 +221,8 @@ public int translate(CharSequence input, int index, Writer out) throws IOExcepti
* While {@link #unescapeHtml3(String)} is the expected method of use, this
* object allows the HTML unescaping functionality to be used
* as the foundation for a custom translator.
*
* @since 3.0
*/
public static final CharSequenceTranslator UNESCAPE_HTML3 =
new AggregateTranslator(
@ -219,6 +237,8 @@ public int translate(CharSequence input, int index, Writer out) throws IOExcepti
* While {@link #unescapeHtml4(String)} is the expected method of use, this
* object allows the HTML unescaping functionality to be used
* as the foundation for a custom translator.
*
* @since 3.0
*/
public static final CharSequenceTranslator UNESCAPE_HTML4 =
new AggregateTranslator(
@ -234,6 +254,8 @@ public int translate(CharSequence input, int index, Writer out) throws IOExcepti
* While {@link #unescapeXml(String)} is the expected method of use, this
* object allows the XML unescaping functionality to be used
* as the foundation for a custom translator.
*
* @since 3.0
*/
public static final CharSequenceTranslator UNESCAPE_XML =
new AggregateTranslator(
@ -248,6 +270,8 @@ public int translate(CharSequence input, int index, Writer out) throws IOExcepti
* While {@link #unescapeCsv(String)} is the expected method of use, this
* object allows the CSV unescaping functionality to be used
* as the foundation for a custom translator.
*
* @since 3.0
*/
public static final CharSequenceTranslator UNESCAPE_CSV = new CsvUnescaper();
@ -349,6 +373,8 @@ public static final String escapeJava(String input) {
*
* @param input String to escape values in, may be null
* @return String with escaped values, {@code null} if null string input
*
* @since 3.0
*/
public static final String escapeEcmaScript(String input) {
return ESCAPE_ECMASCRIPT.translate(input);
@ -377,6 +403,8 @@ public static final String unescapeJava(String input) {
* @see #unescapeJava(String)
* @param input the {@code String} to unescape, may be null
* @return A new unescaped {@code String}, {@code null} if null string input
*
* @since 3.0
*/
public static final String unescapeEcmaScript(String input) {
return UNESCAPE_ECMASCRIPT.translate(input);
@ -408,6 +436,8 @@ public static final String unescapeEcmaScript(String input) {
* @see <a href="http://www.w3.org/TR/REC-html40/sgml/entities.html">HTML 4.0 Character entity references</a>
* @see <a href="http://www.w3.org/TR/html401/charset.html#h-5.3">HTML 4.01 Character References</a>
* @see <a href="http://www.w3.org/TR/html401/charset.html#code-position">HTML 4.01 Code positions</a>
*
* @since 3.0
*/
public static final String escapeHtml4(String input) {
return ESCAPE_HTML4.translate(input);
@ -420,6 +450,7 @@ public static final String escapeHtml4(String input) {
* @param input the {@code String} to escape, may be null
* @return a new escaped {@code String}, {@code null} if null string input
*
* @since 3.0
*/
public static final String escapeHtml3(String input) {
return ESCAPE_HTML3.translate(input);
@ -440,6 +471,8 @@ public static final String escapeHtml3(String input) {
*
* @param input the {@code String} to unescape, may be null
* @return a new unescaped {@code String}, {@code null} if null string input
*
* @since 3.0
*/
public static final String unescapeHtml4(String input) {
return UNESCAPE_HTML4.translate(input);
@ -452,6 +485,8 @@ public static final String unescapeHtml4(String input) {
*
* @param input the {@code String} to unescape, may be null
* @return a new unescaped {@code String}, {@code null} if null string input
*
* @since 3.0
*/
public static final String unescapeHtml3(String input) {
return UNESCAPE_HTML3.translate(input);

38
src/main/java/org/apache/commons/lang3/Validate.java
View File

@ -437,6 +437,8 @@ public static <T extends CharSequence> T notEmpty(T chars) {
* @throws NullPointerException if the character sequence is {@code null}
* @throws IllegalArgumentException if the character sequence is blank
* @see #notBlank(CharSequence)
*
* @since 3.0
*/
public static <T extends CharSequence> T notBlank(T chars, String message, Object... values) {
if (chars == null) {
@ -464,6 +466,8 @@ public static <T extends CharSequence> T notBlank(T chars, String message, Objec
* @throws NullPointerException if the character sequence is {@code null}
* @throws IllegalArgumentException if the character sequence is blank
* @see #notBlank(CharSequence, String, Object...)
*
* @since 3.0
*/
public static <T extends CharSequence> T notBlank(T chars) {
return notBlank(chars, DEFAULT_NOT_BLANK_EX_MESSAGE);
@ -615,6 +619,8 @@ public static <T extends Iterable<?>> T noNullElements(T iterable) {
* @throws NullPointerException if the array is {@code null}
* @throws IndexOutOfBoundsException if the index is invalid
* @see #validIndex(Object[], int)
*
* @since 3.0
*/
public static <T> T[] validIndex(T[] array, int index, String message, Object... values) {
Validate.notNull(array);
@ -644,6 +650,8 @@ public static <T> T[] validIndex(T[] array, int index, String message, Object...
* @throws NullPointerException if the array is {@code null}
* @throws IndexOutOfBoundsException if the index is invalid
* @see #validIndex(Object[], int, String, Object...)
*
* @since 3.0
*/
public static <T> T[] validIndex(T[] array, int index) {
return validIndex(array, index, DEFAULT_VALID_INDEX_ARRAY_EX_MESSAGE, Integer.valueOf(index));
@ -670,6 +678,8 @@ public static <T> T[] validIndex(T[] array, int index) {
* @throws NullPointerException if the collection is {@code null}
* @throws IndexOutOfBoundsException if the index is invalid
* @see #validIndex(Collection, int)
*
* @since 3.0
*/
public static <T extends Collection<?>> T validIndex(T collection, int index, String message, Object... values) {
Validate.notNull(collection);
@ -696,6 +706,8 @@ public static <T extends Collection<?>> T validIndex(T collection, int index, St
* @throws NullPointerException if the collection is {@code null}
* @throws IndexOutOfBoundsException if the index is invalid
* @see #validIndex(Collection, int, String, Object...)
*
* @since 3.0
*/
public static <T extends Collection<?>> T validIndex(T collection, int index) {
return validIndex(collection, index, DEFAULT_VALID_INDEX_COLLECTION_EX_MESSAGE, Integer.valueOf(index));
@ -723,6 +735,8 @@ public static <T extends Collection<?>> T validIndex(T collection, int index) {
* @throws NullPointerException if the character sequence is {@code null}
* @throws IndexOutOfBoundsException if the index is invalid
* @see #validIndex(CharSequence, int)
*
* @since 3.0
*/
public static <T extends CharSequence> T validIndex(T chars, int index, String message, Object... values) {
Validate.notNull(chars);
@ -753,6 +767,8 @@ public static <T extends CharSequence> T validIndex(T chars, int index, String m
* @throws NullPointerException if the character sequence is {@code null}
* @throws IndexOutOfBoundsException if the index is invalid
* @see #validIndex(CharSequence, int, String, Object...)
*
* @since 3.0
*/
public static <T extends CharSequence> T validIndex(T chars, int index) {
return validIndex(chars, index, DEFAULT_VALID_INDEX_CHAR_SEQUENCE_EX_MESSAGE, Integer.valueOf(index));
@ -777,6 +793,8 @@ public static <T extends CharSequence> T validIndex(T chars, int index) {
* @param expression the boolean expression to check
* @throws IllegalStateException if expression is {@code false}
* @see #validState(boolean, String, Object...)
*
* @since 3.0
*/
public static void validState(boolean expression) {
if (expression == false) {
@ -797,6 +815,8 @@ public static void validState(boolean expression) {
* @param values the optional values for the formatted exception message, null array not recommended
* @throws IllegalStateException if expression is {@code false}
* @see #validState(boolean)
*
* @since 3.0
*/
public static void validState(boolean expression, String message, Object... values) {
if (expression == false) {
@ -819,6 +839,8 @@ public static void validState(boolean expression, String message, Object... valu
* @param pattern the regular expression pattern, not null
* @throws IllegalArgumentException if the character sequence does not match the pattern
* @see #matchesPattern(CharSequence, String, String, Object...)
*
* @since 3.0
*/
public static void matchesPattern(CharSequence input, String pattern) {
if (Pattern.matches(pattern, input) == false) {
@ -840,6 +862,8 @@ public static void matchesPattern(CharSequence input, String pattern) {
* @param values the optional values for the formatted exception message, null array not recommended
* @throws IllegalArgumentException if the character sequence does not match the pattern
* @see #matchesPattern(CharSequence, String)
*
* @since 3.0
*/
public static void matchesPattern(CharSequence input, String pattern, String message, Object... values) {
if (Pattern.matches(pattern, input) == false) {
@ -861,6 +885,8 @@ public static void matchesPattern(CharSequence input, String pattern, String mes
* @param value the object to validate, not null
* @throws IllegalArgumentException if the value falls out of the boundaries
* @see #inclusiveBetween(Object, Object, Comparable, String, Object...)
*
* @since 3.0
*/
public static <T> void inclusiveBetween(T start, T end, Comparable<T> value) {
if (value.compareTo(start) < 0 || value.compareTo(end) > 0) {
@ -882,6 +908,8 @@ public static <T> void inclusiveBetween(T start, T end, Comparable<T> value) {
* @param values the optional values for the formatted exception message, null array not recommended
* @throws IllegalArgumentException if the value falls out of the boundaries
* @see #inclusiveBetween(Object, Object, Comparable)
*
* @since 3.0
*/
public static <T> void inclusiveBetween(T start, T end, Comparable<T> value, String message, Object... values) {
if (value.compareTo(start) < 0 || value.compareTo(end) > 0) {
@ -903,6 +931,8 @@ public static <T> void inclusiveBetween(T start, T end, Comparable<T> value, Str
* @param value the object to validate, not null
* @throws IllegalArgumentException if the value falls out of the boundaries
* @see #exclusiveBetween(Object, Object, Comparable, String, Object...)
*
* @since 3.0
*/
public static <T> void exclusiveBetween(T start, T end, Comparable<T> value) {
if (value.compareTo(start) <= 0 || value.compareTo(end) >= 0) {
@ -924,6 +954,8 @@ public static <T> void exclusiveBetween(T start, T end, Comparable<T> value) {
* @param values the optional values for the formatted exception message, null array not recommended
* @throws IllegalArgumentException if the value falls out of the boundaries
* @see #exclusiveBetween(Object, Object, Comparable)
*
* @since 3.0
*/
public static <T> void exclusiveBetween(T start, T end, Comparable<T> value, String message, Object... values) {
if (value.compareTo(start) <= 0 || value.compareTo(end) >= 0) {
@ -948,6 +980,8 @@ public static <T> void exclusiveBetween(T start, T end, Comparable<T> value, Str
* @param obj the object to check, null throws an exception
* @throws IllegalArgumentException if argument is not of specified class
* @see #isInstanceOf(Class, Object, String, Object...)
*
* @since 3.0
*/
public static void isInstanceOf(Class<?> type, Object obj) {
if (type.isInstance(obj) == false) {
@ -968,6 +1002,8 @@ public static void isInstanceOf(Class<?> type, Object obj) {
* @param values the optional values for the formatted exception message, null array not recommended
* @throws IllegalArgumentException if argument is not of specified class
* @see #isInstanceOf(Class, Object)
*
* @since 3.0
*/
public static void isInstanceOf(Class<?> type, Object obj, String message, Object... values) {
if (type.isInstance(obj) == false) {
@ -992,6 +1028,8 @@ public static void isInstanceOf(Class<?> type, Object obj, String message, Objec
* @param type the class to check, not null
* @throws IllegalArgumentException if argument can not be converted to the specified class
* @see #isAssignableFrom(Class, Class, String, Object...)
*
* @since 3.0
*/
public static void isAssignableFrom(Class<?> superType, Class<?> type) {
if (superType.isAssignableFrom(type) == false) {

2
src/main/java/org/apache/commons/lang3/builder/ReflectionToStringBuilder.java
View File

@ -377,6 +377,8 @@ public static String toStringExclude(Object object, String[] excludeFieldNames)
/**
* Which field names to exclude from output. Intended for fields like <code>"password"</code>.
*
* @since 3.0 this is protected instead of private
*/
protected String[] excludeFieldNames;

1
src/main/java/org/apache/commons/lang3/concurrent/AtomicInitializer.java
View File

@ -61,6 +61,7 @@
* </p>
*
* @author Apache Software Foundation
* @since 3.0
* @version $Id$
* @param <T> the type of the object managed by this initializer class
*/

1
src/main/java/org/apache/commons/lang3/concurrent/AtomicSafeInitializer.java
View File

@ -50,6 +50,7 @@
* </p>
*
* @author Apache Software Foundation
* @since 3.0
* @version $Id$
* @param <T> the type of the object managed by this initializer class
*/

1
src/main/java/org/apache/commons/lang3/concurrent/BackgroundInitializer.java
View File

@ -79,6 +79,7 @@
* operation is complete or to cancel the operation.
* </p>
*
* @since 3.0
* @version $Id$
* @param <T> the type of the object managed by this initializer class
*/

1
src/main/java/org/apache/commons/lang3/concurrent/CallableBackgroundInitializer.java
View File

@ -61,6 +61,7 @@
*
* </p>
*
* @since 3.0
* @version $Id$
* @param <T> the type of the object managed by this initializer class
*/

1
src/main/java/org/apache/commons/lang3/concurrent/ConcurrentException.java
View File

@ -30,6 +30,7 @@
* </p>
*
* @author Apache Software Foundation
* @since 3.0
* @version $Id$
*/
public class ConcurrentException extends Exception {

1
src/main/java/org/apache/commons/lang3/concurrent/ConcurrentInitializer.java
View File

@ -35,6 +35,7 @@
* </p>
*
* @author Apache Software Foundation
* @since 3.0
* @version $Id$
* @param <T> the type of the object managed by this initializer class
*/

1
src/main/java/org/apache/commons/lang3/concurrent/ConcurrentRuntimeException.java
View File

@ -31,6 +31,7 @@
* </p>
*
* @author Apache Software Foundation
* @since 3.0
* @version $Id$
*/
public class ConcurrentRuntimeException extends RuntimeException {

1
src/main/java/org/apache/commons/lang3/concurrent/ConcurrentUtils.java
View File

@ -28,6 +28,7 @@
* </p>
*
* @author Apache Software Foundation
* @since 3.0
* @version $Id$
*/
public class ConcurrentUtils {

1
src/main/java/org/apache/commons/lang3/concurrent/ConstantInitializer.java
View File

@ -35,6 +35,7 @@
* </p>
*
* @author Apache Software Foundation
* @since 3.0
* @version $Id$
* @param <T> the type of the object managed by this initializer
*/

1
src/main/java/org/apache/commons/lang3/concurrent/LazyInitializer.java
View File

@ -73,6 +73,7 @@
* </p>
*
* @author Apache Software Foundation
* @since 3.0
* @version $Id$
* @param <T> the type of the object managed by this initializer class
*/

1
src/main/java/org/apache/commons/lang3/concurrent/MultiBackgroundInitializer.java
View File

@ -91,6 +91,7 @@
* by {@code MultiBackgroundInitializer} waits forever.
* </p>
*
* @since 3.0
* @version $Id$
*/
public class MultiBackgroundInitializer

3
src/main/java/org/apache/commons/lang3/concurrent/TimedSemaphore.java
View File

@ -122,7 +122,8 @@
* resources. After that {@link #acquire()} must not be called any more.
* </p>
*
* @version $Id:$
* @since 3.0
* @version $Id$
*/
public class TimedSemaphore {
/**

4
src/main/java/org/apache/commons/lang3/text/StrBuilder.java
View File

@ -468,6 +468,7 @@ public StrBuilder append(Object obj) {
*
* @param seq the CharSequence to append
* @return this, to enable chaining
* @since 3.0
*/
public StrBuilder append(CharSequence seq) {
if (seq == null) {
@ -484,6 +485,7 @@ public StrBuilder append(CharSequence seq) {
* @param startIndex the start index, inclusive, must be valid
* @param length the length to append, must be valid
* @return this, to enable chaining
* @since 3.0
*/
public StrBuilder append(CharSequence seq, int startIndex, int length) {
if (seq == null) {
@ -717,6 +719,7 @@ public StrBuilder append(boolean value) {
*
* @param ch the value to append
* @return this, to enable chaining
* @since 3.0
*/
public StrBuilder append(char ch) {
int len = length();
@ -2000,6 +2003,7 @@ public boolean endsWith(String str) {
//-----------------------------------------------------------------------
/**
* {@inheritDoc}
* @since 3.0
*/
public CharSequence subSequence(int startIndex, int endIndex) {
if (startIndex < 0) {